Agent SDK

完整的 Agent SDK 文档现在已经迁到独立的 Agent 文档域。

推荐从这里开始：

@downcity/agent 当前对外提供两个主要 SDK 入口：

Agent：本地嵌入式 Agent
RemoteAgent：远程 Agent 客户端

安装

pnpm add @downcity/agent

如果你要使用 ChatPlugin 这类内建 plugin class，还需要额外安装：

pnpm add @downcity/plugins

这里最重要的区分

纯 SDK 嵌入模式：模型由宿主直接持有
Downcity 项目模式：模型通常来自 execution.modelId + City AIService

也就是说，并不是所有场景都应该默认去写 session.set({ model })。

本地 Agent

当你的应用与 Agent 运行在同一进程，并且可以直接注入 tools、plugins 与 model 时，使用 new Agent(...)。

import { Agent } from "@downcity/agent";
import { createOpenAI } from "@ai-sdk/openai";

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

const agent = new Agent({
  id: "vibecape-official",
  path: "/path/to/agent-project",
  tools: {},
  model: openai.responses("gpt-5"),
});

const session = await agent.createSession();

const turn = await session.prompt({
  query: "把本地文件重命名为新的规范",
});
const result = await turn.finished;

console.log(result.text);

如果没有在 Agent 构造时传默认模型，也可以对单个 session 调用 session.set({ model })。

注入 ChatPlugin

如果你的 client 需要直接在 @downcity/agent 内启动 chat 渠道，可以显式传入 ChatPlugin 实例：

import { Agent } from "@downcity/agent";
import { ChatPlugin } from "@downcity/plugins";

const agent = new Agent({
  id: "vibecape-official",
  path: "/path/to/agent-project",
  tools: {},
  plugins: [
    new ChatPlugin({
      telegram: {
        botToken: process.env.TELEGRAM_BOT_TOKEN!,
      },
    }),
  ],
});

plugins 接收“已经实例化好的 plugin 对象”。

观察执行过程

const unsubscribe = session.subscribe((event) => {
  if (event.type === "text-delta") {
    process.stdout.write(event.text);
  }
});

const turn = await session.prompt({
  query: "继续刚才的话题",
});
await turn.finished;
unsubscribe();

启动 RPC

const started = await agent.start({
  rpc: {
    host: "127.0.0.1",
    port: 15314,
  },
});

console.log(started.rpc?.url);

通过 Town 暴露 HTTP

town agent start

远程 Agent

当另一个进程已经通过 HTTP 或 RPC 暴露了 Agent 时，使用 RemoteAgent。

import { RemoteAgent } from "@downcity/agent";

const agent = new RemoteAgent({
  url: "http://127.0.0.1:15314",
});

const session = await agent.createSession();

const turn = await session.prompt({
  query: "总结一下当前仓库结构",
});
const result = await turn.finished;

console.log(result.text);

远程 session 当前不支持客户端直接传本地模型实例。

Session 落盘位置

SDK session 默认落盘到：

<projectRoot>/.downcity/agents/<agentId>/sessions/<sessionId>/messages/messages.jsonl

Agent SDK

目录