> ## Documentation Index > Fetch the complete documentation index at: https://docs.zerone.run/llms.txt > Use this file to discover all available pages before exploring further. # API Reference > Agent SDK 顶层函数、Agent 方法、配置选项与环境变量参考。 # API Reference ## 顶层函数 | 函数 | 说明 | | ------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `query({ prompt, options })` | 一次性流式查询，返回 `AsyncGenerator` | | `createAgent(options)` | 创建带 Session 持久化的可复用 Agent | | `tool(name, desc, schema, handler)` | 创建带 Zod schema 校验的 Tool | | `createSdkMcpServer({ name, tools })` | 将 Tool 打包为进程内 MCP server | | `defineTool(config)` | 底层 Tool 定义辅助函数 | | `getAllBaseTools()` | 获取全部 18 个内建 Tool | | `registerSkill(definition)` | 注册自定义 Skill | | `getAllSkills()` | 获取所有已注册 Skill | | `createProvider(apiType, opts)` | 直接创建 LLM Provider | | `createHookRegistry(config)` | 创建生命周期事件的 hook 注册表 | | `listSessions()` | 列出持久化 Session | | `forkSession(id)` | 分叉 Session 以创建分支 | | `compactMessagesStream(opts)` | 压缩内存消息（保留尾部语义）；流式发出 `compact` 事件并返回消息与状态，供自定义持久化保持一致性 | | `compactMessages(opts)` | `compactMessagesStream` 的非流式封装 | | `compactSessionStream(opts)` | 按 `sessionId` 压缩持久化 Session（无需 Agent）；流式发出 `compact` 事件，原子化持久化消息、摘要与 token 计数。**宿主负责跨请求 Session 加锁** | | `compactSession(opts)` | `compactSessionStream` 的非流式封装 | ## 压缩（Compaction） ### 存储归属 SDK 拥有持久化 Session 时使用 `compactSessionStream()` 或 `compactSession()`；宿主持有自定义存储时使用 `compactMessagesStream()` 或 `compactMessages()`，并将返回的 `messages` 与 `state` 一起持久化。两组接口默认都逐字保留最近的查询。 ### 压缩选项 两个独立开关控制最近尾部保留多少。`toolProtectedQueries` 在全部四个入口均为新增；`QueryEngine.compactStream`/`compact` 与 `Agent.compactStream`/`compact` 同时获得这两个参数；engine 流此前仅接受位置参数 `protectedQueries`。 | 选项 | 默认值 | 含义 | | ---------------------- | --- | -------------------------------------------- | | `protectedQueries` | `4` | 逐字保留的最近用户查询数（头部摘要、尾部保留） | | `toolProtectedQueries` | `2` | 尾部中保留**完整** `tool_result` 内容的查询数；更早的尾部结果会被清空 | | 入口 | 形态 | | --------------------------------------------------------------------- | --------------------------------------------------------- | | `compactMessagesStream(opts)` / `compactMessages(opts)` | `opts.protectedQueries`、`opts.toolProtectedQueries` | | `compactSessionStream(opts)` / `compactSession(opts)` | `opts.protectedQueries`、`opts.toolProtectedQueries` | | `QueryEngine.compactStream(protectedQueries?, toolProtectedQueries?)` | 位置参数（此前仅有位置参数 `protectedQueries`） | | `QueryEngine.compact(protectedQueries?, toolProtectedQueries?)` | 位置参数（此前**无参数**） | | `Agent.compactStream(opts?)` / `Agent.compact(opts?)` | `{ protectedQueries?, toolProtectedQueries? }`（此前**无参数**） | 将 `toolProtectedQueries` 设为不小于尾部大小可完全禁用 tool result 裁剪。省略参数时保留历史默认值（逐字保留 4 个查询，其中最近 2 个保留完整 tool result）。 ### 行为变化 1. `pruneMessages` 现在真正保护最近 `PRUNE_PROTECTED_QUERIES`（4）个查询的大体积 tool result——此前无论新旧都会清空所有超大结果。 2. 压缩现在会裁剪存活尾部中最近 2 个查询之外的大体积 tool result；将 `toolProtectedQueries` 设为不小于尾部大小可禁用。一个待完成的最终用户查询会占用一个保护槽位（该状态下已完成 Tool 的保留数从 2 降为 1）。 原始的裸输入辅助函数 `compactConversationStream()`、`compactConversation()` 与 `compactConversationWithProtectedTail()` 不再从包根导出。自定义存储集成请迁移到 `compactMessagesStream()` 或 `compactMessages()`；基于持久化 Session 的集成请迁移到 `compactSessionStream()` 或 `compactSession()`。 ## Agent 方法 | 方法 | 说明 | | ------------------------------- | -------------------------------------------- | | `agent.query(prompt)` | 流式查询，返回 `AsyncGenerator` | | `agent.prompt(text)` | 阻塞查询，返回 `Promise` | | `agent.getMessageLog()` | 所有已发出消息的追加式审计日志 | | `agent.compactStream()` | 手动压缩当前历史（保留尾部），流式发出 `compact` 事件并持久化 Session | | `agent.compact()` | `compactStream()` 的非流式封装 | | `agent.getMessageHistory()` | engine 的持久历史（压缩后视图） | | `agent.clear()` | 重置 Session | | `agent.interrupt()` | 中止当前查询 | | `agent.setModel(model)` | 在会话中切换模型 | | `agent.setPermissionMode(mode)` | 切换权限模式 | | `agent.getApiType()` | 获取当前 API 类型 | | `agent.close()` | 关闭 MCP 连接并持久化 Session | ## 选项 | 选项 | 类型 | 默认值 | 说明 | | -------------------- | ------------------------------------------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `apiType` | `string` | 自动检测 | `'anthropic-messages'` 或 `'openai-completions'` | | `model` | `string` | `claude-sonnet-4-6` | LLM 模型 ID | | `apiKey` | `string` | `ZERONE_AGENT_API_KEY` 环境变量 | API key | | `baseURL` | `string` | — | 自定义 API 端点 | | `cwd` | `string` | `process.cwd()` | 工作目录 | | `agent` | `AgentDefinition` | — | 主 Agent 定义：`prompt`（系统提示词）、`appendPrompt`、`maxTurns`（默认 `10`）、`capabilities`（Agent-local 能力包，见 [Subagent](/zh/sdk/subagents)）、`availableSkills`（仅根 Agent 生效、作用于运行时 Skill 注册表的 allowlist）。失效的通配符、零匹配 allowlist 和零 Tool 的 Agent 都会记录警告 | | `customTools` | `ToolDefinition[]` | — | 自定义 Tool，与内建 Tool 池合并 | | `permissionMode` | `string` | `bypassPermissions` | `default` / `acceptEdits` / `dontAsk` / `bypassPermissions` / `plan` / `auto` | | `canUseTool` | `function` | — | 自定义权限回调 | | `maxSessionQueries` | `number` | — | 纳入 LLM 上下文的最大查询数；更早的查询触发减半压缩 | | `maxBudgetUsd` | `number` | — | 花费上限 | | `thinking` | `ThinkingConfig` | — | 扩展思考（`{ type: 'adaptive' \| 'enabled' \| 'disabled', budgetTokens? }`）；不设置则不启用 | | `effort` | `string` | — | 推理强度：`low` / `medium` / `high` / `xhigh` / `max`；不设置则不发送 | | `mcpServers` | `Record` | — | MCP server 连接 | | `subAgents` | `Record` | — | 供 Task/MultiTask 使用的 subagent 定义；每个条目拥有自己的 `capabilities`——绝不从父 Agent 继承 | | `hooks` | `Record>` | — | 生命周期 hook | | `resume` | `string` | — | 按 ID 恢复 Session | | `continue` | `boolean` | `false` | 继续最近一次 Session | | `persistSession` | `boolean` | `true` | 将 Session 持久化到磁盘 | | `sessionId` | `string` | 自动生成 | 显式 Session ID | | `outputFormat` | `{ type: 'json_schema', schema }` | — | 结构化输出 | | `sandbox` | `SandboxSettings` | — | 文件系统/网络沙箱 | | `settingSources` | `SettingSource[]` | — | 从 `~/.agents/skills/`（`user`）和/或 `${cwd}/.agents/skills/`（`project`）加载 Skill | | `extraUserSkillDirs` | `string[]` | — | 额外的用户级 Skill 目录（标记为 `source='user'`） | | `env` | `Record` | — | 环境变量 | | `toolEnv` | `Record` | — | 传给 Bash/Grep 子进程的环境变量（默认与 process.env 合并） | | `toolEnvInherit` | `boolean` | `true` | 为 `false` 时完全替换 process.env（配合 `toolEnv` 实现完全隔离的子进程环境） | | `abortController` | `AbortController` | — | 取消控制器 | AGENTS.md 大小限制：每个文件上限 32 KiB。超限文件会被跳过，并在系统提示中注入一条 `[ERROR]` 消息代替。 ## Subagent 能力隔离 每个 Agent 运行在 Runtime-global 的 RuntimeEnvironment 之上，并携带 Agent-local、绝不继承的 AgentCapabilities（`connectionTools`、`customTools`、`skills`、`allowedTools`、`disallowedTools`）。委派深度固定为 1。完整的合并规则、解析顺序和 2.x → 3.0 迁移表见 [Subagent](/zh/sdk/subagents)。 ## MCP server 传输 `mcpServers` 条目通过 `type` 或 `transport` 选择字段区分（两个名字都接受——`.agents/mcp.json` 和 Provider 文档中两种拼写都在使用）。SDK 接受以下值，并在两个选择字段都省略时推断传输方式： | 选择字段值 | 底层传输 | 必填字段 | | ----------------- | ---------------------------------------------- | --------- | | `stdio` | `StdioClientTransport` | `command` | | `sse` | `SSEClientTransport`（旧版 HTTP+SSE） | `url` | | `streamable_http` | `StreamableHTTPClientTransport`（规范推荐的规范名） | `url` | | `streamable-http` | `StreamableHTTPClientTransport`（kebab-case 别名） | `url` | | `http` | `StreamableHTTPClientTransport`（向后兼容） | `url` | | （省略）+ `command` | `StdioClientTransport`（推断） | `command` | | （省略）+ `url` | `StreamableHTTPClientTransport`（推断） | `url` | `streamable_http` / `streamable-http` / `http` 视为等价——三者都实例化 `StreamableHTTPClientTransport`。如果 `type` 和 `transport` 同时存在且归一化为不同的传输类型，SDK 会以冲突错误快速失败。未知的显式值同样快速失败，错误信息会列出所有支持的别名。 ### stdio 工作目录 `McpStdioConfig` 接受可选的 `cwd` 字段，作为派生 server 的工作目录。相对的 `command` 路径和 `args` 中的相对条目都相对该目录解析。 | 来源 | 解析顺序 | | -------------------- | --------------------------------- | | `McpStdioConfig.cwd` | 优先 | | `AgentOptions.cwd` | server 级 `cwd` 未设置时回退 | | （均未设置） | MCP SDK 默认值（派生时的 `process.cwd()`） | Agent SDK 会把 `AgentOptions.cwd` 注入未显式指定 `cwd` 的 stdio server 配置——因此 `{ command: 'npx', args: ['my-server'] }` 这样的 server 会在 Agent 的工作区中运行，而不是宿主进程目录。这不影响 `sse` / Streamable HTTP 传输。 ### stdio stderr 策略 `McpStdioConfig` 接受可选的 `stderr` 字段，转发给派生的 server 进程： | 取值 | 行为 | | ---------- | ---------------------------------------------------- | | 省略 | 上游 MCP SDK 默认 `"inherit"`——子进程 stderr 进入宿主进程的 stderr | | `"ignore"` | 丢弃子进程 stderr（适合有严格输出边界的宿主） | 有意不暴露 `"pipe"`——SDK 不提供 stderr 消费方。该字段参与连接池键的计算。 ## 环境变量 | 变量 | 说明 | | --------------------------- | ---------------------------------------------- | | `ZERONE_AGENT_API_KEY` | API key（首选） | | `ZERONE_AGENT_AUTH_TOKEN` | 备选认证 token | | `ZERONE_AGENT_API_TYPE` | `anthropic-messages`（默认）或 `openai-completions` | | `ZERONE_AGENT_MODEL` | 默认模型覆盖 | | `ZERONE_AGENT_BASE_URL` | 自定义 API 端点 | | `ZERONE_AGENT_MCP_GRACE_MS` | MCP server 关闭宽限期（毫秒，默认 30000） | Provider 配置示例见 [Model](/zh/sdk/providers)。 ## Cron 仅 Node 的子路径 `@zerone-agent/agent-sdk/cron/node`。状态存放在 `/cron/`（默认 `~/.agents/cron/`）：`tasks.json`、`executions.jsonl`、`execution-index.json`，以及单写者 `runtime.lock`（O\_EXCL——崩溃会留下该文件；错误信息会给出路径以便手动清理）。 ### 在线运行时 `createDefaultCronService({ dataDir?, resolveAgent, ... })` 组合文件存储、Agent 执行器与目录锁。`start()` 获取 `runtime.lock`、恢复中断的执行并运行调度器；`stop()` 排空并释放。 ### 离线维护 ```typescript theme={null} import { withCronMaintenanceSession } from '@zerone-agent/agent-sdk/cron/node' await withCronMaintenanceSession({ dataDir }, async (service) => { await service.create({ cron: '0 16 * * *', prompt: 'Run the report' }) const executions = await service.listExecutions({ limit: 50 }) }) ``` 在同一目录上进行短期 CRUD 与执行历史访问：获取完全相同的 `runtime.lock`（运行中的 Runtime 或另一个维护会话会快速失败），使用与在线服务相同的适配器与校验，从不启动 Scheduler/定时器/Agent 执行器，从不执行启动恢复，并在回调结束时释放锁。会话结束后保留的 service 引用会拒绝一切操作。 ## Memory（3.x） 宿主无关的长期记忆：一个深层的 `MemoryService` 架在事务化的 `MemoryStorage` 接缝之上。作用域：`global`、`user`、`workspace`。每次变更都要求 `expectedRevision` 并原子化提交审计事件；容量归档是确定性的（importance 升序 → updatedAt 升序 → id 升序）并落在同一提交中。 * `createMemoryService({ storage, budgets?, policy?, resolveWorkspace?, events?, diagnostics? })` ——核心入口；生命周期 `stopped → starting → running → stopping → stopped`（由宿主拥有；Agent 绝不启动/停止它）。 * `service.bind({ actor, sessionId?, workspace?, ... }, policy?)` → `MemorySession`（add/search/replace/remove/renderContext）。一个 Session 只读 global + user + 其绑定的 workspace；`policy.writableScopes` 收窄写权限。 * `service.admin` ——仅宿主使用：queryWorkspaces / queryRecords / mutate（create|update|archive|restore|delete|purge）/ queryAudit。 * `runMemoryStorageConformance(name, factory, hooks?)` ——可复用的适配器测试套件。 * `AgentOptions.memoryService` ——存在时会挂载延迟加载的 `Memory`/`MemorySearch` 内建 Tool（ADR 0005 `context.services.memory`）；不存在则两个 Tool 都不存在。SDK 绝不把记忆注入提示词：宿主需显式调用 `session.renderContext()`。 * Node 适配器：`@zerone-agent/agent-sdk/memory/node` ——`createDefaultMemoryService({ dataDir? })` 存储在 `/memory`（默认 `~/.agents/memory`），带单写者锁、journal + checkpoint 崩溃恢复与 purge 脱敏。绝不隐式创建数据目录。 **测试基础设施**——`runMemoryStorageConformance` 是测试基础设施：它在调用时惰性导入 vitest 并返回 `Promise`（在 vitest 测试文件顶层 await 它）。仅导入包根从不要求 vitest；只有运行该套件的消费方需要自行安装 vitest（SDK 不带 vitest 依赖）。 **Journal 恢复**——`loadMemoryState(memoryDir, diagnostics?)` 接受可选的 `DiagnosticsSink` 用于撕裂尾部告警（SDK 内部使用，不属于子路径导出）。 **行为变化**——纯新增：没有既有 API 被移除或改变默认值；针对更早版本编写的代码可以继续编译。 ## Diagnostics sink 宿主通过注入 sink 拥有全部 SDK 诊断输出——不做全局 console 猴子补丁。 ```typescript theme={null} export interface DiagnosticsSink extends Logger { warn(msg: string, fields?: Record, cause?: unknown): void error(msg: string, fields?: Record, cause?: unknown): void child(fields: Record): DiagnosticsSink } ``` * **注入**：`AgentOptions.logger`（已放宽为接受 `Logger | DiagnosticsSink`）；普通 `Logger` 会被自动适配——`warn` 降级为 `error`，`cause` 被丢弃。一次注入贯穿 engine/hooks/snapshot/tools/MCP/skills，subagent 的子 engine 通过 Task/MultiTask 派生管线继承它。独立构造的 `CronService` 接受 `diagnostics?: DiagnosticsSink`——它优先于旧的字符串式 `onDiagnostic`。**两层结构**：Agent 级诊断 sink 仅限构造时（`AgentOptions.logger`）——它拥有该 Agent 整个生命周期的 provider/hooks/snapshot/tools/MCP/skills 输出（复用的 Provider、HookRegistry 与 SnapshotEngine 是构造期绑定的单例，query 级 sink 无法一致地重新绑定它们）。既有的 `QueryOverrides.logger` 保留并保持 **engine 级作用域**：query 级 logger 只接收该查询的 engine/tool-executor 输出，与之前一致——它绝不重新绑定 Agent 级 sink。 * **默认值**：`createDiagnosticsSink()`（基于 console）。字节规则：根部不注入前缀（调用点保留其完整的既有消息字符串），`fields` 仅在定义时作为第二个 console 参数打印，**`cause` 绝不打印**。 * **通道约定**：`fields` 只携带安全摘要；`cause` 是供宿主自行消费的原始错误——这是"安全摘要"与"原始错误"之间的显式边界。`warn`/`error` 始终输出；`debug`/`trace` 遵循 `LogLevel`（`AgentOptions.logLevel` 仍控制默认 sink 的过滤）。 ### 诊断行为变化（按发布标记） 此前打印底层错误文本的位置，现在输出脱敏骨架 + `fields.errorType`（原始错误在 `cause` 上，或在既有的 throw/return 错误通道上）：hook 失败（`[Hook] hook failed`）、文件系统 Skill 加载/重载失败、SnapshotEngine 超时警告、`executeSingleTool` 错误。其余诊断输出逐字节不变。