Agent SDK

@downcity/agent 用于在同一进程中创建 Agent、管理 Session 并执行模型调用。完整 API 参考在 Agent SDK 文档。

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

const agent = new Agent({
  id: "repo-helper",
  path: process.cwd(),
  prepare_session: async (session) => await session.set({ model }),
  tools: { search: search_tool },
  plugins: [plugin],
  env: { API_KEY: process.env.API_KEY ?? "" },
});

const session = await agent.sessions.create();
const turn = await session.prompt({ query: "检查当前项目" });
const result = await turn.finished;

await agent.dispose();

Agent 在构造时启动 plugin 生命周期与后台任务；需要明确等待就绪时使用 await agent.ready()，关闭时使用 await agent.dispose()。HTTP 与 RPC 由独立包 @downcity/server 的 AgentHTTP 与 AgentRPC 提供。

流式消息

subscribe() 返回统一的实时 Session Mutation：

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

Tool 生命周期统一使用 variant: "part"、type: "tool"。等待用户决定的 unrestricted 请求会在 mutation.part.approval 中携带完整审批信息；审批决定通过独立的 Session 命令提交，不通过事件回调回复：

const unsubscribe = session.subscribe((mutation) => {
  if (
    mutation.variant === "part" &&
    mutation.type === "tool" &&
    mutation.part.state === "approval-required" &&
    mutation.part.approval
  ) {
    const { approval_id, command, cwd, reason } = mutation.part.approval;
    show_approval({ approval_id, command, cwd, reason });
  }
});

async function decide_approval(approval_id: string, decision: "approved" | "denied") {
  await session.resolve_approval({ approval_id, decision });
}

历史快照使用 session.messages()；连接断开后重新读取快照并建立新的订阅。

继续阅读：完整 Agent SDK 文档。

Agent SDK

Agent SDK

流式消息

目录