Thanks to visit codestin.com
Credit goes to voltagent.dev

Skip to main content
Workspaces

Workspace

Experimental

The Workspace API is experimental. Expect iteration and possible breaking changes as we refine the API.

Workspace gives agents a persistent home base with filesystem, sandbox execution, search, and skills. It keeps tool usage structured and observable while staying configurable per agent or conversation.

Quick start​

import { Agent, Workspace, LocalSandbox, InMemoryVectorAdapter } from "@voltagent/core";

const workspace = new Workspace({
  id: "demo-workspace",
  operationTimeoutMs: 30000,
  filesystem: {
    // Defaults to in-memory. Swap in NodeFilesystemBackend or a custom backend for persistence.
  },
  sandbox: new LocalSandbox(),
  search: {
    autoIndexPaths: ["/"],
    embedding: "openai:text-embedding-3-small",
    vector: new InMemoryVectorAdapter(),
  },
  skills: {
    rootPaths: ["/skills"],
  },
});

const agent = new Agent({
  name: "workspace-agent",
  model,
  instructions: "Use workspace tools when needed.",
  workspace,
  // workspaceToolkits is optional; defaults add filesystem + sandbox + search + skills
});

If you only want specific toolkits:

const agent = new Agent({
  name: "workspace-agent",
  model,
  instructions: "Use workspace tools when needed.",
  workspace,
  workspaceToolkits: {
    filesystem: false,
    sandbox: {},
    search: {},
    skills: {},
  },
});

You can also set a global workspace on the VoltAgent instance. Agents inherit it unless they pass their own workspace or set workspace: false:

import { Agent, VoltAgent, Workspace } from "@voltagent/core";

const workspace = new Workspace({ id: "shared-workspace" });

const volt = new VoltAgent({
  workspace,
  agents: {
    support: new Agent({ name: "support", model }),
  },
});

Skills root resolvers can receive context:

const workspace = new Workspace({
  skills: {
    rootPaths: async ({ workspace, filesystem }) => ["/skills", `/skills/${workspace.id}`],
  },
});

Workspace in custom tool calls​

When an agent has a workspace, custom tool execute handlers receive it through tool options (options.workspace).

const readWorkspaceFile = createTool({
  name: "read_workspace_file",
  description: "Read data from workspace inside a tool call",
  parameters: z.object({ path: z.string() }),
  execute: async ({ path }, options) => {
    const workspace = options?.workspace;
    if (!workspace) {
      return "Workspace is not configured.";
    }
    return await workspace.filesystem.read(path);
  },
});

Workspace lifecycle + utilities​

You can initialize or tear down the workspace explicitly, and inspect runtime info:

await workspace.init();

const info = workspace.getInfo();
const pathContext = workspace.getPathContext();
const toolsConfig = workspace.getToolsConfig();

await workspace.destroy();

Guides​

Table of Contents