API Reference

Agent SDK 顶层函数、Agent 方法、配置选项与环境变量参考。

​

API Reference

​

顶层函数

函数	说明
query({ prompt, options })	一次性流式查询，返回 AsyncGenerator<SDKMessage>
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<SDKMessage>
agent.prompt(text)	阻塞查询，返回 Promise<QueryResult>
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）、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<string, McpServerConfig>	—	MCP server 连接
subAgents	Record<string, AgentDefinition>	—	供 Task/MultiTask 使用的 subagent 定义；每个条目拥有自己的 capabilities——绝不从父 Agent 继承
hooks	Record<string, Array<{ matcher?, hooks, timeout? }>>	—	生命周期 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<string, string>	—	环境变量
toolEnv	Record<string, string | undefined>	—	传给 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。

​

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。

​

Cron

仅 Node 的子路径 @zerone-agent/agent-sdk/cron/node。状态存放在 <dataDir>/cron/（默认 ~/.agents/cron/）：tasks.json、executions.jsonl、execution-index.json，以及单写者 runtime.lock（O_EXCL——崩溃会留下该文件；错误信息会给出路径以便手动清理）。

​

在线运行时

createDefaultCronService({ dataDir?, resolveAgent, ... }) 组合文件存储、Agent 执行器与目录锁。start() 获取 runtime.lock、恢复中断的执行并运行调度器；stop() 排空并释放。

​

离线维护

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? }) 存储在 <dataDir>/memory（默认 ~/.agents/memory），带单写者锁、journal + checkpoint 崩溃恢复与 purge 脱敏。绝不隐式创建数据目录。

测试基础设施——runMemoryStorageConformance 是测试基础设施：它在调用时惰性导入 vitest 并返回 Promise<void>（在 vitest 测试文件顶层 await 它）。仅导入包根从不要求 vitest；只有运行该套件的消费方需要自行安装 vitest（SDK 不带 vitest 依赖）。

Journal 恢复——loadMemoryState(memoryDir, diagnostics?) 接受可选的 DiagnosticsSink 用于撕裂尾部告警（SDK 内部使用，不属于子路径导出）。

行为变化——纯新增：没有既有 API 被移除或改变默认值；针对更早版本编写的代码可以继续编译。

​

Diagnostics sink

宿主通过注入 sink 拥有全部 SDK 诊断输出——不做全局 console 猴子补丁。

export interface DiagnosticsSink extends Logger {
  warn(msg: string, fields?: Record<string, unknown>, cause?: unknown): void
  error(msg: string, fields?: Record<string, unknown>, cause?: unknown): void
  child(fields: Record<string, unknown>): 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] <event> hook failed）、文件系统 Skill 加载/重载失败、SnapshotEngine 超时警告、executeSingleTool 错误。其余诊断输出逐字节不变。