Agent SDK
使用 @downcity/agent 构建具备项目文件、受控命令、Power 与持久 Session 的本地或远程 Agent
@downcity/agent 提供本地 Agent 执行运行时；@downcity/city 提供组合根、Workspace/Power
资源、transport 与 RemoteAgent。两种客户端形态都以 Session 为主要工作对象：Agent 组合执行
能力，Session 承载持续对话及其执行状态。
一分钟心智模型
| 对象 | 负责 | 不负责 |
|---|---|---|
Workspace | 项目文件、Env、Tools 与可选 Shell | Agent 身份、Power、Session 持久化与 Sandbox 实现 |
Shell | Sandbox Provider、Workspace 持久 Sandbox 与 Shell Sessions | Chat Session 身份与 City 生命周期 |
Agent | 模型、指令、自定义 Tool 与 Session | Power 实例、Workspace 资源、HTTP/RPC transport |
AgentSessions | 当前 Agent 的全部 Session；每个 Session 可以接收一个 Workspace | Agent 身份与 Power 定义 |
Session | 对话状态、消息历史、执行顺序与审批 | 项目资源所有权 |
City | Workspace 与 Power 资源、生命周期、Storage 和 transport | Session 执行语义 |
SessionTurnContext | 一个 Turn 的执行上下文与生命周期 | 保存长期 Agent 状态 |
RemoteAgent | 访问服务端 Agent 与 Session | 配置服务端模型 |
选择本地还是远程
| 场景 | 使用 |
|---|---|
| Agent 与应用运行在同一个 Node.js 进程 | Agent |
| 应用需要直接注入模型、Tool、Power 和 Shell | Agent |
| Agent 已由另一个进程通过 HTTP/RPC 暴露 | RemoteAgent |
| 客户端只需要创建 Session、发送 prompt 和订阅结果 | RemoteAgent |
网络服务不属于 Agent。创建 City，通过 city.agents.add(agent) 加入 Agent，再使用
city.http() 或 city.rpc() 暴露整个 City。
推荐的本地组合
Shell 是本地 Agent 使用项目命令和进程的标准入口。下面的嵌入式示例直接把 microsandbox Provider 注入 Shell：
import { Agent } from "@downcity/agent";
import { Workspace } from "@downcity/city";
import { MicrosandboxProvider } from "@downcity/sandbox-microsandbox";
import { Shell } from "@downcity/city";
const shell = new Shell({
sandbox_provider: new MicrosandboxProvider(),
});
const workspace = new Workspace({
id: "project",
path: process.cwd(),
shell,
runtime_path: "/path/to/downcity-runtime/project",
});
const agent = new Agent({
id: "repo-helper",
model,
});
// Session 在创建时选择 Workspace。
try {
const session = await agent.sessions.create({ workspace });
const turn = await session.prompt({ query: "总结当前仓库" });
const result = await turn.finished;
console.log(result.text);
} finally {
await agent.dispose();
}只需要记住这条主链路：
Agent + Workspace + Shell → agent.session() / agent.sessions.create({ workspace }) → Session → send() / prompt() → turn.finished → dispose()agent.dispose() 会释放 Session 使用的资源并解除当前 City 绑定；City 负责收口 Power 唯一实例、
lifecycle 与 ActionSchedule。项目目录不会创建 .downcity。
模型归属
纯 SDK 嵌入模式由宿主持有模型实例：
- 在
new Agent({ model })中设置默认模型。 - 或对一个本地 Session 调用
await session.set({ model })覆盖默认模型。
Downcity 项目模式由 CLI 宿主根据项目配置和 City AIService 模型目录解析模型。远程 Session 不提供客户端模型配置 API，模型始终由服务端宿主持有。