本地 Agent 快速开始

创建带 Workspace 持久 Sandbox 的本地 Agent，并完成第一次 Session 执行

安装

pnpm add @downcity/agent @downcity/city @downcity/federation @downcity/sandbox-microsandbox
npx microsandbox setup

@downcity/sandbox-microsandbox 是跨平台 Sandbox Provider，为每个 Workspace 提供独立、持久的 microVM 环境。

完整示例

import { Agent } from "@downcity/agent";
import { City, Shell, Workspace } from "@downcity/city";
import { create_openai_compatible_model } from "@downcity/federation";
import { MicrosandboxProvider } from "@downcity/sandbox-microsandbox";

const model = create_openai_compatible_model({
  id: "gpt-5",
  upstream_model: "gpt-5",
  base_url: "https://api.openai.com/v1",
  api_key: process.env.OPENAI_API_KEY!,
});
const workspace = new Workspace({
  id: "project",
  path: "/path/to/project",
  shell: new Shell({
    sandbox_provider: new MicrosandboxProvider(),
  }),
});
const agent = new Agent({ id: "repo-helper", model });
const city = new City({
  workspaces: [workspace],
  agents: [agent],
});

try {
  const session = await agent.sessions.create({ workspace });
  const turn = await session.prompt({ query: "总结当前仓库结构" });
  console.log((await turn.finished).text);
} finally {
  await city.close();
}

所有权

  • City 持有 Power 与登记资源，但不理解 Workspace 的执行后端。
  • Workspace 持有项目资源、环境变量与可选 Shell。
  • Shell 持有 Sandbox Provider、Workspace 持久 Sandbox 与 Shell Sessions；shell_id 与 Chat session_id 相互独立。
  • Agent 持有 Chat Sessions。Chat Session 只借用选中的 Workspace，不拥有 Shell 或 Sandbox。

Shell 命令默认使用 target: "sandbox"，项目固定挂载到 /workspace。同一 Workspace 会跨 Chat Session 保留 HOME 和已安装工具。target: "host" 必须提供原因并经过审批。Sandbox 启动失败不会降级成宿主执行。

没有 Shell 时，Workspace 仍提供文件与搜索工具。city.close() 会释放 Agent、Power 与 Workspace；Workspace 再委托 Shell 停止 Sandbox 计算资源并保留其持久文件系统。

下一步