Agent 类

本地 Agent 的核心公开使用面包括：

• new Agent(options)
• agent.ready()
• agent.dispose()
• agent.sessions
• agent.getEnv()
• agent.setEnv(next)
• agent.patchEnv(patch)
• agent.getConfig()
• agent.getLogger()
• agent.plugins

agent.sessions.create() 和 agent.sessions.get() 返回 AgentSession。

agent.getConfig()、agent.getLogger() 和 agent.getContext() 是高级集成辅助入口；没有 agent.getRuntime() 公开方法。

Sessions

agent.sessions 返回一个 AgentSessions，包含以下方法：

• agent.sessions.create(input?)
• agent.sessions.get(sessionId)
• agent.sessions.list(input?)
• agent.sessions.archive({ id })
• agent.sessions.archived(input?)
• agent.sessions.clean_archive()

archive({ id }) 把当前 agent 下一个已存在且未在执行中的 session 移动到归档目录。archived(input?) 列出已归档 session 的分页摘要。clean_archive() 永久删除所有已归档 session，并返回被删除的 session id 列表。

构造参数

• id
• path
• env
• tools
• instruction
• plugins
• Session
• prepare_session
• release_session
• config
• plugin_config

当前没有 mode 这个构造参数。

prepare_session(session) 在每个 turn 执行前调用。模型选择、模型 ID、默认模型和恢复策略由宿主实现；SDK 只消费宿主通过 session.set({ model }) 注入的运行时模型实例。

release_session(session_id) 在 Session 归档成功后调用，供宿主清理自己持有的编排数据。

核心语义

• Agent 本身是本地执行壳
• 真正的执行对象是它创建出来的 session

从 API 设计上看，它更像一个“session 工厂 + 后台能力管理入口”。Transport（RPC、HTTP）由 @downcity/server 单独提供。

Env

Agent 的 env 是当前实例生命周期内的动态运行时状态。构造参数 env 与项目根目录 .env 会组成初始值；同名值以 .env 为准，之后宿主可以在不重建 Agent 的情况下更新它。

• agent.getEnv()：返回当前 env 的浅拷贝快照
• agent.setEnv(next)：整体替换当前 env
• agent.patchEnv(patch)：增量更新当前 env，字段值为 null 或 undefined 时删除该 key

setInstruction()、setEnv()、patchEnv() 以及 plugin 注册表修改都采用相同的 Session step 边界：配置方法成功后，已有 Session 会把修改加入自己的统一输入队列，并在下一个 step 检查点生效。当前流式响应和工具执行继续使用本 step 已经提交的 instruction、env 与 plugin 视图；如果本轮没有后续 step，则在下一个 Session turn 开始时生效。

生效时 Session timeline 会写入 completed action message。新创建的 Session 直接使用 Agent 最新配置，不需要重放此前的 action。默认 safe sandbox 会允许当前 Session step 已生效的 Agent env 进入 shell 子进程，但不会继承完整宿主 process.env。

agent.patchEnv({
  OPENAI_API_KEY: token,
  OLD_TOKEN: null,
});

ready() 和 dispose()

new Agent(...) 之后，plugin lifecycle 与 ActionSchedule 会自动启动。

• await agent.ready()：等待后台能力启动完成。session 入口在模型执行前会等待当前 Agent 就绪；需要显式检查点时再直接调用。
• await agent.dispose()：停止 plugin lifecycle、ActionSchedule、shell 等后台资源。

RPC / HTTP 暴露

Agent 自身不再启动任何 transport。需要 RPC 或 HTTP 时，使用 @downcity/server：

import { AgentRPC, AgentHTTP } from "@downcity/server";

const rpc = new AgentRPC(agent);
await rpc.listen({ host: "127.0.0.1", port: 15314 });

const http = new AgentHTTP(agent);
await http.server().listen({ host: "127.0.0.1", port: 5314 });

agent.plugins

agent.plugins 是本地 SDK 里很重要的公开面。

你可以直接用它做：

• agent.plugins.register(plugin)
• agent.plugins.unregister(pluginName)
• agent.plugins.has(pluginName)
• agent.plugins.get(pluginName)
• agent.plugins.status(pluginName)
• agent.plugins.snapshots()
• agent.plugins.list()
• agent.plugins.availability(pluginName)
• agent.plugins.runAction({ plugin, action, payload })
• agent.plugins.pipeline(pointName, value)
• agent.plugins.guard(pointName, value)
• agent.plugins.effect(pointName, value)
• agent.plugins.resolve(pointName, value)