创建带模型、Shell 和平台 Sandbox 的本地 Agent，并完成第一次 Session 执行

本地 Agent 快速开始

这条路径适合把 Agent 直接嵌入 Node.js 应用。一个完整的本地 Agent 由 Workspace、Shell、平台 Sandbox、模型和 Session 组成。

安装

以下示例使用 macOS：

pnpm add @downcity/agent @downcity/workspace @downcity/sandbox-macos @ai-sdk/openai

其他平台只替换 Sandbox package 和实例：

平台	Package	Adapter
macOS	`@downcity/sandbox-macos`	`MacOsSeatbeltSandbox`
Linux	`@downcity/sandbox-linux`	`LinuxBubblewrapSandbox`
Windows	`@downcity/sandbox-windows-mxc`	`WindowsMxcSandbox`

完整的最小示例

import { Agent } from "@downcity/agent";
import { City } from "@downcity/agent";
import { Workspace } from "@downcity/workspace";
import { createOpenAI } from "@ai-sdk/openai";
import { MacOsSeatbeltSandbox } from "@downcity/sandbox-macos";
import { Shell } from "@downcity/workspace";

const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
});

const shell = new Shell({
  sandbox: new MacOsSeatbeltSandbox(),
});

const workspace = new Workspace({
  id: "project",
  path: "/path/to/project",
  shell,
});

const city = new City({ workspaces: [workspace] });
const agent = new Agent({
  id: "repo-helper",
  city,
  model: openai.responses("gpt-5"),
});

try {
  const session = await agent.sessions.create({ workspace: city.workspaces.get("project")! });
  const turn = await session.prompt({
    query: "总结当前仓库结构",
  });

  const result = await turn.finished;
  console.log(result.text);
} finally {
  await agent.dispose();
}

六个关键步骤

创建当前平台的 Sandbox Adapter。
创建 Shell 并注入 Sandbox。
创建 Workspace 并传入项目路径、稳定 ID 和 Shell。
创建包含 Workspace 的 City，独立创建 Agent，再调用 city.agents.add(agent)。
创建 Session，通过 prompt() 启动 Turn，并等待 turn.finished。
在 finally 中调用 agent.dispose()。

Shell 很重要：没有 Shell 时，Workspace 仍提供文件和搜索工具，但 Agent 没有 shell_exec 与 shell_session，无法运行项目命令或管理长时间进程。SDK 不会自动选择 Sandbox，也不会在缺少 Adapter 时静默切换到 unrestricted。

对象与生命周期

City(Workspace) → Agent(city) → Agent Session(Workspace) → Turn
                                      └──────────────→ agent.dispose()

Agent 绑定一个 City；每个 Session 显式选择 City 中的 Workspace。
Workspace 只描述项目资源边界；AgentWorkspace 承载当前 Agent 在该项目中的 Session 和运行状态。
多个 Agent 可以指向同一目录，但应使用不同的 agent.id 和独立的 Workspace 数据分区。
new Agent(...) 后，Plugin lifecycle 与 ActionSchedule 会立即开始启动。
Session 执行会自动等待 Agent runtime 就绪，调用方不管理独立的启动状态。
agent.dispose() 释放 Agent 的 Session 与 Plugin；city.close() 释放共享 Workspace、Shell 和 Sandbox。
HTTP/RPC transport 不属于 Agent；需要网络服务时使用 @downcity/agent。

模型如何解析

本地执行按以下顺序选择模型：

Session 通过 await session.set({ model }) 设置的模型。
Agent 构造参数中的默认 model。

如果两处都没有模型，Session 无法执行。纯 SDK 嵌入模式由宿主持有模型实例；Downcity 项目模式则由 CLI 宿主根据项目配置和 City AIService 模型目录解析模型。

本地 Agent 快速开始

本地 Agent 快速开始

安装

完整的最小示例

六个关键步骤

对象与生命周期

模型如何解析

下一步

目录