从开发者视角理解 Agent、RemoteAgent 和 Session 的实际公开 API 使用面

SDK Surface

如果你只想记住开发者真正会用到的 API 形态，可以先记这四个对象：

Agent：本地 runtime 入口
RemoteAgent：远程 session 客户端
AgentSession：本地工作对象
RemoteAgentSession：远程工作对象

本地典型流程

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

const agent = new Agent({
  id: "demo",
  path: process.cwd(),
});

const session = await agent.sessions.create();
await session.set({ model });

const turn = await session.prompt({
  query: "总结一下这个仓库",
});

await turn.finished;

多个 Session 共用宿主模型策略时，使用 prepare_session 钩子统一注入。

远程典型流程

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

const agent = new RemoteAgent({
  url: "http://127.0.0.1:5314/agents/repo-helper",
});

const session = await agent.sessions.get("repo-analysis");
const turn = await session.prompt({
  query: "继续",
});

await turn.finished;

`Agent`

当 agent runtime 和你的应用运行在同一本地进程或同一个宿主环境里时，用 Agent。

核心方法：

new Agent(options)
agent.ready()
agent.dispose()
agent.sessions
agent.setInstruction(input)
agent.getEnv() / agent.setEnv() / agent.patchEnv()
agent.getConfig()
agent.getLogger()
agent.getContext()
agent.getShell()
agent.plugins

典型职责：

创建和恢复本地 session
在构造时自动启动 plugin lifecycle 与 ActionSchedule，必要时显式 ready() / dispose()
暴露 plugin 集成入口
提供配置与日志这两个较窄的高级辅助能力

agent.getLogger() 返回当前 Agent 自己持有的 logger。独立集成代码可以调用 getLogger(project_root?) 创建新的隔离实例；package 不再暴露进程级全局 logger。

如果你需要 RPC 或 HTTP 暴露，请使用 @downcity/server 提供的 AgentRPC / AgentHTTP。

`RemoteAgent`

当另一个进程已经暴露了 agent 时，用 RemoteAgent。

核心方法：

new RemoteAgent({ url })
agent.sessions

它当前支持：

http://...
https://...
rpc://...

典型职责：

连接一个已有的远程 agent 服务
切换到已知的远程 session
浏览可用的远程 session 列表
响应 runtime plugin action，例如 shell 审批请求

`AgentSession`

AgentSession 是本地模式下最核心的执行对象。

核心方法：

session.id
session.agentId
session.config
session.set(input)
session.get_info()
session.prompt(input)
session.stop()
session.subscribe(subscriber)
session.messages(input?)
session.system()
session.approvals()
session.approval_mode()
session.set_approval_mode(input)
session.resolve_approval(input)
session.fork(input?)

典型顺序：

await agent.sessions.create()
await session.set({ model }) 或在 Agent 构造时传默认模型
const turn = await session.prompt({ query })
await turn.finished
按需再用 session.messages() / session.get_info() / session.fork()

`RemoteAgentSession`

RemoteAgentSession 尽量保持和本地 session 一样的交互形状，但不负责客户端侧模型注入。

核心方法：

session.id
session.get_info()
session.prompt(input)
session.stop()
session.subscribe(subscriber)
session.messages(input?)
session.system()
session.approvals()
session.approval_mode()
session.set_approval_mode(input)
session.resolve_approval(input)
session.fork(input?)

一个关键差异：

本地 AgentSession 支持 set({ model })
远程 RemoteAgentSession 不提供模型配置方法

Agent 项目和 Federation AIService 的关系

如果你在正常的 Downcity Agent 项目里使用这套 SDK，还要额外区分：

纯 SDK 嵌入：宿主通过 prepare_session 或本地 session.set({ model }) 注入实例
Downcity 项目：通过 execution.modelId 绑定到 Federation AIService

也就是说，session.set({ model }) 不是所有场景都该用的默认路径。

什么时候用哪个方法

需要一条全新的会话：agent.sessions.create()
需要继续一个已知 session：agent.sessions.get(sessionId)
- 需要做 session 切换器、历史侧边栏或第三方 session 浏览器：agent.sessions.list()
- 需要归档单个不再活跃的会话：agent.sessions.archive({ id })
- 需要浏览已归档的会话列表：agent.sessions.archived(input?)
- 需要永久清空已归档会话：agent.sessions.clean_archive()
需要读取单个 session 的当前摘要/详情：get_info()
需要分页读取会话内容：messages()
需要实时监听 Message、流式增量、Turn 与 Session 状态：subscribe()
需要处理当前 Session 的工具审批：approvals() / resolve_approval()
需要停止当前 turn 并清空未吸收队列：stop()
需要查看当前实际生效的 system prompt 快照：system()
需要从当前状态分叉一条新会话：fork()

SDK Surface

SDK Surface

推荐心智模型

本地典型流程

远程典型流程

`Agent`

`RemoteAgent`

`AgentSession`

`RemoteAgentSession`

Agent 项目和 Federation AIService 的关系

什么时候用哪个方法

继续阅读

目录