Agent 类

本地 Agent SDK 的核心公开接口

Agent 是本地 SDK 中可跨项目复用的执行主体，拥有稳定 ID、可见名称、能力描述、指令、模型、自定义 Tool 和 Session 集合。它不持有 Power，也不绑定 Workspace；chat() 暴露属于 Agent 自己的那段对话。

公开 API

  • new Agent(options)
  • agent.id
  • agent.name
  • agent.description
  • agent.workspace
  • agent.session({ workspace? })
  • agent.sessions.create({ workspace })
  • agent.sessions.get(session_id, origin_type?, { workspace? })
  • agent.set_instruction(input)
  • agent.get_instructions()
  • agent.get_logger()
  • agent.dispose()

Agent 自己就是一条 Session，用 session() 取用；所有会话（包括它）都从 agent.sessions 创建与恢复：

const session = await agent.session({ workspace });
const turn = await session.prompt({ query: "这个仓库的结构怎么样" });

const work = await agent.sessions.create({ workspace });

会话用 set 写配置、get 读状态，两者共用同一个手柄：

await session.set({ model, workspace });   // 写
session.get("workspace");                   // 运行时实例
session.get("workspace_id");                // 持久化标识

构造参数

  • id：稳定 Agent 身份和私有数据分区键。
  • name：可选的用户可见名称；省略时使用 id。
  • description：可选的一句话能力简介，供展示与 Group 语义调度使用。
  • tools：该 Agent 创建的 Session 可使用的自定义 Tool。
  • instruction：Agent 级静态基础指令。
  • model：默认 ModelClient，本地 Session 可以覆盖。
  • workspace：可选的新建 Session 默认目录；不是绑定，可在会话中切换。
  • session_class：可选的本地自定义 Session 类。

workspace 只是新建会话的默认目录。它不影响 Agent 的身份，也不会限制 Agent 之后使用其他目录； 省略时新建的会话没有项目上下文。每个 Session 都可以通过 session.set({ workspace }) 或在创建时 传入 { workspace } 选择自己的当前目录。详见 Agent 对话 与 管理 Session。

一个 Agent 可以在多个 Workspace 中工作。Power 由 City 提供，City 中全部 Power 自动对全部 Agent 可用；执行时从 city.powers.scope({ agent_id: agent.id, workspace_id: workspace.id }) 创建明确的执行视图。agent.dispose() 会释放 Session 与当前 City 绑定；网络 transport 仍由宿主负责关闭。