Local Agent

本地 Agent RPC 与 Town HTTP

理解 Agent RPC 与 Town 托管 HTTP 暴露之间的真实分工

本地 Agent RPC 与 Town HTTP

本地 Agent 可以在当前进程里直接调用,也可以暴露本机 RPC 给另一个本地进程调用。

HTTP 不是 Agent SDK 自己的 server 能力。在 Downcity 里,HTTP 暴露由 Town 负责。

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);

返回里会有:

  • started.rpc?.url
  • started.pluginsStarted

agent.start() 不负责什么

agent.start() 不负责启动 HTTP server。

也就是说,这样的写法并不是当前真实 API:

await agent.start({
  http: {
    host: "127.0.0.1",
    port: 15314,
  },
});

如何通过 Town 暴露 HTTP

如果你要 HTTP,对应做法是用 Town 启动 Agent,并让 Town 发布 Agent HTTP 网关:

town agent start

这里的职责划分是:

  • Agent:本地执行壳
  • agent.start():长期运行能力中的 plugins / 本机 RPC
  • town agent start:Agent 进程宿主与 HTTP 网关发布者

start() 和不 start() 的区别

不调用 agent.start() 时:

  • 你仍然可以直接 await agent.createSession(),再用 session.prompt() / session.subscribe()
  • 适合把 Agent 当作当前进程里的本地库
  • 不会启动 plugin 的后台生命周期
  • 不会启动 RPC

调用 agent.start() 之后:

  • plugins 默认会启动
  • ActionSchedule 和其他后台 loop 才会真正持续运行
  • 如果传了 rpc,还会暴露 rpc://... 地址

什么时候用 RPC

  • 另一个本地进程想直接消费 Agent session 能力
  • 你不想自己额外挂 HTTP
  • 你想走更轻量的本机 transport

什么时候用 HTTP

  • 外部 client 需要通过 Town 的 HTTP 网关调用 Agent
  • 你想给前后端或第三方程序一个标准 HTTP 入口
  • 你需要 Town 在同一个网关上托管 SDK 路由和 plugin HTTP 路由

一个和 plugin 相关的重要点

Town 暴露 Agent HTTP 网关时,已注册 plugin 的 plugin.http.server.register(...) 会自动挂到同一个 HTTP app 上。

所以:

  • agent.plugins 负责插件注册表与调用
  • Town 负责把插件的 HTTP 路由真正挂出去

相关文档