用 Agent SDK 在本地进程里创建一个可执行的 Agent，并理解本地模型与 City AIService 模型的差异

本地 Agent 快速开始

安装

pnpm add @downcity/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: "repo-helper",
  path: "/path/to/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);

最重要的三步

new Agent(...)
await agent.createSession()
确保 session 有 model

这三步里第 3 步最容易被遗漏，也是本地 SDK 最常见的踩坑点。

第 3 步有两种做法：

在 new Agent({ model }) 里传默认模型
或者对某个 session 单独调用 await session.set({ model })

如果两种都没做，本地 session 没有模型，无法执行。

一个关键区分

纯 SDK 嵌入模式

如果你是直接把 @downcity/agent 嵌到自己的 Node 应用里，最常见就是：

new Agent({ model })
或 session.set({ model })

模型实例由你的宿主代码直接持有。

Downcity Agent 项目模式

如果你是在正常的 Downcity / Town 项目里跑 Agent，通常不应该在项目里直接持有 provider 配置或模型实例。

这时模型来自：

downcity.json.execution.modelId
已连接的 City AIService

也就是说：

Agent 项目只选择 modelId
City AIService 管理 provider、API key、模型目录

什么时候需要 `agent.start()`

new Agent(...) 只是在当前进程里创建一个本地 agent 实例。

如果你只是想在宿主代码里直接跑 session：

const session = await agent.createSession();
const turn = await session.prompt({ query: "hello" });
await turn.finished;

通常不需要调用 agent.start()。

当前 agent.start() 的职责是：

启动 plugin lifecycle
可选启动本机 RPC 服务

例如：

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

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

如果你需要 HTTP 服务端点，应通过 town agent start 由 Town 发布 HTTP 网关，而不是 agent.start({ http: ... })。

本地 Agent 快速开始

目录