本地 Agent 快速开始

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

安装

以下示例使用 macOS：

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

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

完整的最小示例

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

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

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

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

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

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

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

六个关键步骤

1. 创建当前平台的 Sandbox Adapter。
2. 创建 Shell 并注入 Sandbox。
3. 创建 Workspace 并传入 Shell。
4. 创建 Agent 并传入 Workspace 与模型。
5. 创建 Session，通过 prompt() 启动 Turn，并等待 turn.finished。
6. 在 finally 中调用 agent.dispose()。

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

对象与生命周期

Workspace + Shell → Agent → Session → Turn
                         └──────────────→ agent.dispose()

• 一个 Workspace 实例只能绑定一个 Agent。
• 同一物理目录可以创建多个 Workspace 实例，分别交给不同 Agent。
• new Agent(...) 后，Plugin lifecycle 与 ActionSchedule 会立即开始启动。
• Session 入口会等待 Agent runtime 就绪；只有需要显式启动检查点时才调用 await agent.ready()。
• agent.dispose() 会同时释放独占 Workspace、Shell 进程、PTY 和 Sandbox，不需要再次调用 workspace.dispose()。
• HTTP/RPC transport 不属于 Agent；需要网络服务时使用 @downcity/server。

模型如何解析

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

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

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

下一步

• Session 总览
• Shell 与沙箱
• Tools 与 Plugins
• 构造参数
• HTTP 与 RPC