Agent SDK
理解 @downcity/agent 提供的本地 Agent、远程 Agent、Session，以及它与 City AIService 的关系
Agent SDK
@downcity/agent 当前提供两类主要 SDK 入口：
Agent：本地嵌入式 agentRemoteAgent：远程 agent 客户端
这套 SDK 的核心是 session。无论本地还是远程，真正承载执行的都是 session，而不是 Agent 本身。
两条常见使用路径
1. 纯 SDK 嵌入模式
这种模式下，宿主自己持有模型实例：
new Agent({ model })- 或
await session.set({ model })
适合：
- Node 服务内直接嵌入
- 本地脚本或内部工具
- 你已经自己管理模型实例
2. Downcity / Town / City 集成模式
这种模式下，Agent 项目不直接持有 provider、API key 或模型实例。
模型目录和 provider 细节由 City AIService 持有，Agent 项目只绑定：
{
"execution": {
"type": "api",
"modelId": "quality"
}
}适合：
- 正常的 Downcity Agent 项目
- 多个 Agent 共享同一套模型池
- 希望把 provider、key、模型目录统一收口到 City
什么时候用 Agent
当你的应用和 agent 运行在同一进程，或者至少在同一个本地运行环境里，适合直接用：
import { Agent } from "@downcity/agent";你可以显式传入：
idpathtoolsinstructionmodelplugins
它更像本地嵌入式执行壳。
什么时候用 RemoteAgent
当另一个进程已经把 agent 暴露出来时，适合用：
import { RemoteAgent } from "@downcity/agent";然后通过：
new RemoteAgent({ url: "http://127.0.0.1:15314" })去连接它。
RemoteAgent 当前支持：
http://...https://...rpc://...
它更像配套的远程客户端，而不是模型宿主。
共同的核心对象：Session
无论是本地还是远程，SDK 的核心使用面都围绕 session：
createSession()getSession()listSessions()getInfo()prompt()subscribe()history()system()fork()
现在统一的交互模型是：
const turn = await session.prompt(...)session.subscribe(...)await turn.finished
大多数 SDK 使用问题，最终都会落到“session 应该怎么创建、配置和消费”。
一个重要差异
纯本地 SDK session
本地 SDK session 的模型可以来自：
new Agent({ model })或者：
await session.set({ model })Downcity Agent 项目
项目 runtime 的模型来自：
downcity.json.execution.modelId- 已连接的
City AIService模型目录
也就是说，在 Downcity 集成模式里：
- Agent 项目只保存
modelId - Town 负责去 City AIService 解析这个
modelId - provider、key、baseURL 都不放在 Agent 项目里
远程 SDK session
远程 session 当前不支持直接传本地模型实例。
这是因为远程模式下，模型实例应该留在服务端本地持有，而不是由客户端携带。