公开 API

函数

Export	说明
`createAgent(options)`	创建一个带私有 workspace 和默认 workspace 工具的内存态 `Agent`。
`createBareAgent(options)`	创建一个不带默认工具、workspace 提示词，也不创建 workspace 目录的内存态 `Agent`。
`defineAgent(options)`	从 agent 配置创建一个 `AgentSpec` 模板。模板本身无状态；`spawn()` 每次创建一个拥有独立历史和 workspace 的会话。
`isAgentSpec(target)`	类型守卫，区分 `AgentSpec` 模板与存活的 `AgentLike` 会话。
`query(params)`	一次性 async generator helper。
`tool(name, description, inputSchema, handler)`	创建自定义工具定义。
`agentTool(name, target, metadata)`	把另一个 `AgentLike` 或 `AgentSpec` 暴露成模型工具，并明确支持 `ask`、`handoff`、`observe` 三种调用模式。传入模板时每次调用 spawn 全新会话；传入会话时跨调用保留历史。传入 `inputSchema` + `mapInput`（需要 0.21.0）时工具改用自定义 typed 输入形状（ask-only），返回类型为 `ToolDefinition<any>`。
`delegateTool(name, description, agent, options)`	高级 helper，把一个 `AgentLike` 或 `AgentSpec` 暴露成 mailbox-backed 委托工具。
`skill(options)`	创建内存态 skill。
`loadSkill(path)`	从包含 `SKILL.md` 的目录加载 skill。
`createMCPTools(client, options)`	把 MCP client 映射成 SDK 工具。
`connectMCPStdioServer(server, options)`	连接 stdio MCP server，并返回工具和 close handle。
`connectMCPStreamableHTTPServer(url, options)`	连接远程 Streamable HTTP MCP server，支持可选 OAuth。
`createJsonlContextTracer(options)`	创建用于 agent 运行上下文事件的 JSONL trace sink。
`createLangSmithContextTracer(options)`	基于同一套 provider-agnostic 上下文事件创建 LangSmith trace sink。
`createLangfuseContextTracer(options)`	基于同一套 provider-agnostic 上下文事件创建 Langfuse trace sink（构建在 `@langfuse/tracing` v5 之上）。
`createCompositeContextTracer(tracers)`	把上下文 trace 事件广播到多个 trace sink。
`defineContextTracer(impl)`	从实现对象创建自定义 trace sink，校验 `onEvent` 并在创建时绑定 `failOnError`。
`createCompositeAgentHooks(hooks)`	按数组顺序串联 hook，后一个收到前一个的输出。
`createJsonlHistoryStore(options)`	创建 JSONL history store，把 Agent 的对话历史按每行一条 message 持久化。
`defineHistoryStore(impl)`	从实现对象创建自定义 history store，校验 `load`/`append`/`replace` 并在创建时绑定 `failOnError`。
`DEFAULT_COMPACTION_PROMPT`	`autoCompact` 使用的内置摘要指令。
`SUBMIT_OUTPUT_TOOL_NAME`	设置 `AgentOptions.outputSchema` 时注入的内置工具名（`"submit_output"`）。该模式下此名字被保留。
`teamMember(options)`	创建一个团队成员，带 name、role、focus 和 agent。
`createTeam(options)`	创建一个围绕 Lead 的可调用 Team，包含成员、mailbox 和内置 runtime。Lead 提交一批 handoff 后，SDK 会先执行成员，再继续调用 Lead 模型。通过 `runner.maxConcurrentWorkItems` 设置跨成员并发上限，默认值为 `1`。
`createTeamRunner(options)`	高级 runtime，用于手动运行带 mailbox AgentLike 委托工具的 root `AgentLike`。它接收 `maxConcurrentWorkItems`，同时保留成员失败隔离和全局中止清理。
`createMemoryMailbox()`	创建默认内存 mailbox adapter。
`createSQLiteMailbox(options)`	基于 SQLite-like database 创建持久化 mailbox adapter。
`createBuiltinTools(options)`	创建内置文件与 Shell 工具，用于手动组装工具列表。
`createAgentWorkspaceTools(options)`	创建可选的 agent 文件与 Shell workspace 工具。

Agent

Agent 是 type-only 导出（0.17.0 起为破坏性变更：构造器不再导出）。请用 createAgent()、createBareAgent() 或 AgentSpec.spawn() 创建实例——工厂还会生成 session id 并安装 workspace。

const agent = createAgent(options);

for await (const message of agent.query(prompt)) {
  console.log(message);
}

const result = await agent.prompt(prompt);

// 对话历史的深拷贝，包括从 AgentOptions.historyStore seed 的消息。
// 修改返回值不会污染运行中的历史。
const history = await agent.getHistory();

// 整体替换对话历史。仅限空闲时调用（query 运行中会抛
// ConcurrentQueryError）；配置了 historyStore 时 store 会同步替换，
// 持久化保持一致。SDK 不校验内容——由宿主负责其合法性。
await agent.replaceHistory(messages);

// 以 subtype "interrupted" 结束当前 query，已完成轮次保留在历史中，
// 后续可以用新的 query 继续对话。有 query 被中断时返回 true，空闲时返回 false。
agent.interrupt();

// 经 AgentOptions.outputSchema 声明的结构化输出契约（如有）。
// 只读；agentTool() 的契约继承会读取它。需要 0.21.0 及以上版本。
agent.outputSchema;

interrupt() 是 QueryOptions.signal 的协作式对应物：signal 以 error_abort 终止 query，而 interrupt 只丢弃在飞的一轮、以 interrupted 收尾（不算错误）。没有在飞的 query 时返回 false，宿主据此知道可以直接发下一个 query。

当 agent 需要私有 workspace 来存放持久文件和测试证据时，使用 createAgent()。当宿主只想要纯模型循环，并希望显式传入所有系统提示词和工具时，使用 createBareAgent()：

import { createBareAgent, createBuiltinTools } from "agent-lattice";

const agent = createBareAgent({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com/anthropic",
  model: "deepseek-v4-flash",
  systemPrompt: "你是一个简洁的工程助手。",
  tools: createBuiltinTools({
    cwd: process.cwd(),
    allowedDirectories: [process.cwd()],
  }),
});

AgentOptions

选项	类型	说明
`apiKey`	`string`	Provider API key。
`baseURL`	`string`	可选的 Anthropic 兼容接口地址，例如 DeepSeek。
`name`	`string`	可选的 trace source 名称。
`model`	`string`	模型名。
`systemPrompt`	`string`	作为 provider system prompt 发送的稳定角色和职责指令。
`maxTokens`	`number`	单次模型请求的最大输出 token。
`maxTurns`	`number`	agent loop 最大轮次，超过后返回 `error_max_turns`。
`thinkingConfig`	`ThinkingConfig`	默认推理配置。可传 `{ type: "adaptive" }`、`{ type: "enabled", budgetTokens }` 或 `{ type: "disabled" }`。`disabled` 会显式发送给 provider（即 `thinking: { "type": "disabled" }`），因为 DeepSeek 等 Anthropic 兼容端点默认开启思考。省略时，SDK 不发送 thinking 配置。各 provider 的实际生效情况见 Provider 兼容性。
`reasoningEffort`	`ReasoningEffort`	Provider 的默认推理强度。可传 `"low"`、`"high"` 或 `"max"`，请求时序列化为 `reasoning_effort`（Kimi 约定——DeepSeek 忽略，见 Provider 兼容性）。省略时使用 provider 默认值。
`requestTimeoutMs`	`number`	单次模型请求的期限（毫秒）。即使 model client 忽略它，SDK 也会兜底执行。不设置则 SDK 不加限制。
`outputSchema`	`OutputSchema`	要求 run 以校验过的结构化 payload 收尾。SDK 会注入内置的 `submit_output` 工具；校验通过的提交以 `subtype: "success"` 结束、payload 落在 `SDKResultMessage.structuredResult`；未提交就结束回合则以 `error_missing_output`（`MissingOutputError`）失败。与 `QueryOptions.outputFormat` 不同，它只要求 provider 支持工具调用。
`tools`	`ToolDefinition[]`	模型可调用的自定义工具。
`toolBatchPolicy`	`ToolBatchPolicy`	可选的执行前 hook，在任何 handler 运行前允许或拒绝完整工具批次。
`hooks`	`AgentHooks`	改写工具结果和外发模型请求的生命周期回调。委派的子 agent 不会继承。
`autoCompact`	`boolean \| AutoCompactOptions`	超过 token 阈值后把较早历史替换为模型写出的摘要。默认关闭；传 `true` 使用默认配置。
`toolConcurrency`	`ToolConcurrencyOptions`	工具调用调度。默认是 `{ mode: "safe", maxConcurrency: 10 }`；未声明安全规则的工具保持顺序执行。
`skills`	`SkillDefinition[]`	每次 query 按需选择的可复用指令包。
`workspace`	`string \| false \| { cwd: string; allowedDirectories?: string[]; bashTimeoutMs?: number }`	可选的私有 workspace 覆盖配置。传了 `name` 时默认是 `~/.agent/workspaces/<name>`，否则是 `~/.agent/workspaces/agent-<session-id>`。传 `false`（需要 0.23.0）则完全关闭内建工作区——不装内建文件/Shell 工具，不加 workspace 提示段落——等价于 `createBareAgent()`，且对 `defineAgent()` 同样生效。
`permission`	`function`	可允许或拒绝工具执行的权限回调。
`modelClient`	`ModelClient`	用于测试或替换 provider 的自定义模型客户端。
`tracer`	`ContextTracer`	可选的 agent 上下文事件 trace sink。
`historyStore`	`HistoryStore`	可选的对话历史持久化 adapter。首次 query 前加载一次；之后每次历史写入触发 `append()`，compaction 触发 `replace()`。

BareAgentOptions

createBareAgent() 接收 BareAgentOptions，也就是去掉 workspace 的 AgentOptions。它不会注入 workspace 提示词，不会创建默认 workspace 目录，也不会注册内置工具；需要工具时必须显式传入 tools。

QueryOptions

选项	类型	说明
`stream`	`boolean`	是否输出底层 provider stream event，默认 `true`。
`outputFormat`	`OutputFormat`	请求结构化输出，可传 `"json"`，也可通过 `{ type: "json_schema", schema }` 指定 JSON Schema 输出；最终文本会原样返回。
`thinkingConfig`	`ThinkingConfig`	覆盖当前 query 的 Agent 推理配置。固定预算最大为 `maxTokens - 1`。
`reasoningEffort`	`ReasoningEffort`	覆盖当前 query 的 Agent 默认推理强度。
`requestTimeoutMs`	`number`	覆盖当前 query 的单次请求期限。
`signal`	`AbortSignal`	中断当前 query，以 `error_abort` 收尾。对比 `Agent.interrupt()`：以 `interrupted` 收尾并保留对话。
`runtime`	`AgentRuntimeContext`	Team runner 和 delegate tools 传入的运行时上下文。
`tracer`	`ContextTracer`	query 级 trace sink，可覆盖或补充本次 query 的追踪。

上下文追踪

import {
  createAgent,
  createCompositeContextTracer,
  createJsonlContextTracer,
  createLangSmithContextTracer,
} from "agent-lattice";

const tracer = createCompositeContextTracer([
  createJsonlContextTracer({ path: ".agent-runs/session.jsonl" }),
  createLangSmithContextTracer({
    projectName: process.env.LANGSMITH_PROJECT,
    workspaceId: process.env.LANGSMITH_WORKSPACE_ID,
  }),
]);

const agent = createAgent({
  model: "deepseek-v4-flash",
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com/anthropic",
  tracer,
});

try {
  await agent.prompt("Trace this run.", { stream: false });
} finally {
  await tracer.close?.();
}

createJsonlContextTracer() 可以接收 path 写入一个明确文件，也可以接收 dir 按 session_id 写文件。它还支持 redact(event) 在持久化前做本地过滤，以及 failOnError 让 trace 写入失败时终止 agent run。

createLangSmithContextTracer() 默认使用内置的 langsmith RunTree（0.17.0 起）；只有注入自定义 runtime 或测试 fake 时才需要传 LangSmith 兼容的 RunTree 构造器或 runTree(config) 工厂函数。SDK 直接依赖 langsmith，并复用 langsmith/run_trees 的官方 RunTree / RunTreeConfig 类型。按 LangSmith 官方方式配置 LANGSMITH_TRACING、LANGSMITH_ENDPOINT、LANGSMITH_API_KEY 和 LANGSMITH_PROJECT。只有组织级或多 workspace API key 才需要 LANGSMITH_WORKSPACE_ID。也可以把 apiKey、apiUrl 和 workspaceId 直接传给 createLangSmithContextTracer()；workspaceId 只用于选择 LangSmith workspace，不是 project 名。如果需要完整自定义 LangSmith client，可以通过 client 显式传入 Client。短生命周期的测试或脚本退出前，请在 finally 中 close 或 flush tracer，确保 LangSmith 收到根 run 的最终 patch。

createLangfuseContextTracer()（需要 0.19.0）通过当前的 @langfuse/tracing （v5）SDK 把同一套事件映射为 Langfuse observation：每次 agent run 一个 chain observation，每次模型调用一个 generation，每次工具调用一个 tool，辅助事件则是自动结束的 event observation。Langfuse SDK 基于 OpenTelemetry——在进程启动时用 tracer provider 注册 LangfuseSpanProcessor（来自 @langfuse/otel），并配置标准的 LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY / LANGFUSE_BASE_URL 环境变量。把注册好的 processor 作为 spanProcessor 传入，flush()/close() 就会排空未发送的 span，保证短生命周期进程退出前数据送达。startObservation 默认使用内置的 @langfuse/tracing 函数；只有注入自定义 runtime 或测试替身时才需要显式传入。

把 tracer 传给 team.query() 或 team.prompt() 时，一次 Team 调用只创建一个顶层 chain。Lead 执行、Member 执行以及 Lead 收到报告后的后续执行共享同一个 trace session，并显示为该 chain 的子节点。Agent 原来的 session ID 会保留在 agent_session_id metadata 中。

版本可用性

下表中的能力在所列版本及之后可用。0.22.0 之前，SDK 对未知选项是忽略而不是报错，因此在旧版本上调用新 API 会正常成功、而该特性静默失效。自 0.22.0 起，主要工厂（createAgent()/createBareAgent()/defineAgent()、agentTool()、delegateTool()、tool()）遇到未知 option 键会直接抛错，但其它 options 对象仍然忽略未知键——请核对已安装版本，不要指望有异常抛出。

特性	最低版本
`toolConcurrency`、`isConcurrencySafe`、`toolBatchPolicy`、`reasoningEffort`	0.9.25
`SDKResultMessage.usage`、`stop_reason`、`TokenUsage`、`ConcurrentQueryError`	0.10.0
`requestTimeoutMs`、`TimeoutError`、result subtype `error_timeout`	0.11.0
`hooks`、`AgentHooks`、`createCompositeAgentHooks`	0.12.0
`autoCompact`、`DEFAULT_COMPACTION_PROMPT`、`SDKSystemCompactionMessage`	0.13.0
溢出后的压缩兜底恢复、`model_context_window_exceeded`	0.14.0
`defineAgent()`、`AgentSpec`、`AgentToolTarget`、`isAgentSpec()`、`agentTool()`/`delegateTool()` 的 `AgentSpec` 模板目标	0.15.0
`AssistantModelMessage.providerResponseId`、`AssistantModelMessage.model`、`ToolResult.endTurn`、`Agent.interrupt()`（同时加入 `AgentLike` 接口——对自定义实现方是破坏性变更）、result subtype `interrupted`、`AgentOptions.historyStore`、`HistoryStore`、`createJsonlHistoryStore`、`Agent.getHistory()`	0.16.0
`Agent.replaceHistory()`、`AgentLike.interrupt()` 返回 `boolean`（对自定义实现方是破坏性变更）、`defineContextTracer()`、`defineHistoryStore()`（破坏性变更：`failOnError` 字段从 `ContextTracer`/`HistoryStore` 端口类型移除——自定义实现方必须改用 `defineXxx` 工厂）、`Agent` 改为 type-only 导出（破坏性变更：`new Agent()` 不再可用）、`createLangSmithContextTracer()` 默认使用内置 `RunTree`、`tool_use` trace 事件携带工具 `description`	0.17.0
`thinkingConfig: { type: "disabled" }` 显式发送 `thinking: { "type": "disabled" }` 而不再省略该字段（修复 DeepSeek 等默认开启思考的 provider）	0.17.1
在 `max_tokens` 处截断的响应中的工具调用不再执行；每个调用收到一条错误 `tool_result`，要求模型缩短输出后重新发起	0.18.0
`createLangfuseContextTracer()`、`LangfuseContextTracerOptions`、`LangfuseObservationLike`、`LangfuseChainLike`、`LangfuseGenerationLike`、`LangfuseToolLike`、`LangfuseStartObservation`、`LangfuseFlushableSpanProcessor`、`LangfuseKVMap`	0.19.0
`AgentOptions.outputSchema`、`OutputSchema`、`SUBMIT_OUTPUT_TOOL_NAME`、`MissingOutputError`、`SDKResultMessage.structuredResult`、result subtype `error_missing_output`、`AgentRuntimeFailure` code `missing_output`、`ToolResult.structuredResult`、`AgentToolOptions.outputSchema`	0.20.0
`AgentToolOptions.inputSchema` + `mapInput`（typed ask-only 委派）、`agentTool()` 从 target 继承 `outputSchema` 并在装配期核对显式声明、`Agent.outputSchema` getter、`agentTool()` 返回 `ToolDefinition<any>`（行为变化：schema 被继承时 `ask` 的工具结果从固定文本 `"Structured output submitted."` 变为校验后的 JSON）	0.21.0
严格 options 校验：`createAgent()`/`createBareAgent()`/`defineAgent()`（`AgentOptions`）、`agentTool()`（`AgentToolOptions`）、`delegateTool()`（`DelegateToolOptions`）和 `tool()`（`ToolOptions`）在装配期对未知 option 键抛错（行为变化：以前被静默忽略的多余键，例如 spread 进来的宿主字段，现在会抛错）。`ToolOptions.metadata` / `AgentToolOptions.metadata` 透传到 `ToolDefinition.metadata`（宿主持有，不展示给模型）	0.22.0
`AgentOptions.workspace: false`（裸模式，经 `defineAgent()` 也生效）、`agentTool()` 契约固定：显式声明 `outputSchema` 而 target 未声明时按父级 schema 校验子级 `structuredResult`；父子都没声明 schema 时 `ask` 把子级 `structuredResult` 以未校验的 JSON 透出（行为变化：以前 `ask` 结果会回退成文本 content 并丢弃它）	0.23.0

已安装版本可从 node_modules/agent-lattice/package.json 读取；包没有把它导出为可 import 的路径。

核心类型

Export	说明
`SDKMessage`	SDK 输出事件的 union 类型。
`AgentLikeEvent`	`AgentLike.query()` 输出的 union，包含普通 SDK 消息和团队 runtime 事件。
`AgentLike`	`Agent` 和可调用 `Team` wrapper 都实现的最小接口：`query()`、`prompt()` 和 `interrupt()`（后者需要 0.16.0；返回 `boolean` 需要 0.17.0）。
`AgentSpec`	由 `defineAgent()` 创建的 agent 模板：无状态的身份定义（名称、模型、提示词、工具、workspace 策略），附 `spawn()` 用于创建独立会话。
`AgentToolTarget`	`agentTool()` 和 `delegateTool()` 接受的联合类型：存活的 `AgentLike` 会话或 `AgentSpec` 模板。
`AgentOptions`	Agent 构造参数。
`BareAgentOptions`	`createBareAgent()` 的构造参数，相当于去掉 `workspace` 的 `AgentOptions`。
`AgentWorkspaceOptions`	`AgentOptions.workspace` 接收的字符串路径或 workspace 配置对象，用于覆盖默认 workspace。
`AgentWorkspaceToolsOptions`	`createBuiltinTools()` 和 `createAgentWorkspaceTools()` 接收的 `cwd`、写入根目录和 Shell 超时配置。
`QueryOptions`	每次 query 的 streaming、取消、runtime 和 tracing 配置。
`OutputFormat`	`QueryOptions.outputFormat` 接收的结构化输出格式：`"json"` 或 `{ type: "json_schema", schema }`。
`OutputSchema`	`AgentOptions.outputSchema` 和 `AgentToolOptions.outputSchema` 接收的校验形状：`{ parse(input: unknown): T }`。zod schema 直接满足该接口（需要 0.20.0）。
`ThinkingConfig`	`AgentOptions.thinkingConfig` 和 `QueryOptions.thinkingConfig` 接收的推理配置。
`ReasoningEffort`	`AgentOptions.reasoningEffort` 和 `QueryOptions.reasoningEffort` 接收的 provider 推理强度：`"low"`、`"high"` 或 `"max"`。
`TokenUsage`	`SDKResultMessage.usage` 和 `AssistantModelMessage.usage` 上报的 token 计数。
`AssistantModelMessage`	`ModelClient` 返回的一轮 assistant 消息：`content`，可选的 `usage` 与 `stopReason`，以及可选的 provider 元数据 `providerResponseId`（provider 分配的响应 id）和 `model`（实际服务该响应的模型，可能与请求的模型不同）。
`StopReason`	模型停止的原因。`"max_tokens"` 表示输出被截断；`"model_context_window_exceeded"` 表示上下文窗口耗尽，这才是 `autoCompact` 兜底恢复的对象。
`AgentRuntimeFailure`	写入失败事件和上游报告 metadata 的归一化成员错误。
`TeamRunnerConfig`	Team runtime 限制，包括 `maxDelegateDepth` 和 `maxConcurrentWorkItems`。并发默认值为 `1`，同一目标 mailbox 始终串行。
`ContextTracer`	包含 `onEvent`、可选 `flush` 和可选 `close` 的 trace sink 接口。只暴露方法——`failOnError` 由创建它的工厂绑定（`createXxxContextTracer` 的 options 或 `defineContextTracer()`）。
`ContextTraceEvent`	Agent 输出的结构化 trace event envelope。
`ContextTraceEventType`	Trace event 类型字符串 union。
`JsonlContextTracerOptions`	内置 JSONL tracer 的配置。
`LangSmithContextTracerOptions`	LangSmith tracer adapter 的配置。
`LangfuseContextTracerOptions`	Langfuse tracer adapter 的配置（需要 0.19.0）。
`LangfuseObservationLike`	`@langfuse/tracing` 的 `LangfuseObservation` 联合类型别名；`LangfuseChainLike`、`LangfuseGenerationLike`、`LangfuseToolLike` 分别是具体 observation 类的别名（需要 0.19.0）。
`LangfuseStartObservation`	`@langfuse/tracing` 的 `startObservation` 函数类型别名，用于 `LangfuseContextTracerOptions.startObservation`（需要 0.19.0）。
`LangfuseFlushableSpanProcessor`	`LangfuseSpanProcessor` 所满足的最小 `forceFlush()` 形状，用于 `LangfuseContextTracerOptions.spanProcessor`（需要 0.19.0）。
`HistoryStore`	Agent 对话历史的持久化 adapter 接口：`load()`、`append(message)`、`replace(messages)`。compaction 会调用 `replace()`，所以 store 必须支持整体替换。只暴露方法——`failOnError` 由创建它的工厂绑定（`createJsonlHistoryStore` 的 options 或 `defineHistoryStore()`）。
`JsonlHistoryStoreOptions`	内置 JSONL history store 的配置：`path` 和可选 `failOnError`。
`LangSmithRunTreeLike`	LangSmith 官方 `RunTree` 类型的别名。
`LangSmithRunTreeConfig`	LangSmith 官方 `RunTreeConfig` 类型的别名。
`ToolDefinition`	传入 Agent 的工具定义。可携带从 `ToolOptions.metadata`/`AgentToolOptions.metadata` 透传的宿主持有 `metadata`（需要 0.22.0）；不展示给模型。
`ToolResult`	工具 handler 的返回值：`content` 加可选的 `endTurn`——设置后该批次结束后以 `subtype: "success"` 收尾，不再调用模型；以及可选的 `structuredResult`（需要 0.20.0）——与 `endTurn: true` 搭配时作为结构化 payload 落到 `SDKResultMessage.structuredResult`，否则被忽略。
`ToolOptions`	`tool()` 的可选配置，包括根据输入判断的 `isConcurrencySafe`，以及透传到 `ToolDefinition.metadata` 的宿主持有 `metadata`（需要 0.22.0）。
`ToolConcurrencyMode`	工具调度模式：`"safe"`、`"all"` 或 `"sequential"`。
`ToolConcurrencyOptions`	Agent 的工具调度模式和正整数 `maxConcurrency` 上限。
`AutoCompactOptions`	压缩配置：`thresholdTokens`（100000）、`keepRecentMessages`（6）、`prompt`、`model`、`maxTokens`。
`SDKSystemCompactionMessage`	`subtype: "compaction"` 的 `system` 消息，历史被摘要时输出，包含消息条数和摘要自身的用量。
`AgentHooks`	`AgentOptions.hooks` 接收的生命周期回调：`onToolResult` 和 `onModelRequest`。hook 抛错会直接从 `query()` 抛出。
`ToolResultHookContext`	`onToolResult` 的入参：工具名、原始输入、结果块，以及调用失败时的 error。
`ModelRequestHookContext`	`onModelRequest` 的入参：即将发出的 messages 和 system prompt，以及轮次编号。
`ModelRequestHookResult`	单次请求的替换 `messages` 和/或 `systemPrompt`；不影响存储的历史。
`ToolBatchPolicy`	在执行前检查完整工具批次的可选 Agent 策略。
`ToolBatchPolicyContext`	策略输入，包含来源、业务上下文、signal，以及标记为 `tool` 或 `agent_tool` 的工具调用。
`ToolBatchPolicyResult`	允许批次，或通过错误码、消息、冲突调用 ID 和下一步建议拒绝批次。
`AgentToolInput`	`agentTool()` 的标准输入结构。
`AgentToolOptions`	`agentTool()` 的说明、目标 mailbox 等配置，以及 `outputSchema`（需要 0.20.0）：`ask` 模式下工具结果是子级校验后的结构化输出 JSON 字符串；子级未提交或提交不合法时以 `child_output_invalid` 工具错误返回。自 0.21.0 起，缺省的 `outputSchema` 从 target 自身的声明继承（`spec.options.outputSchema` 或活 Agent 的 `outputSchema` getter；宿主自定义 `AgentLike` 适配器没有可读声明，不继承也不核对），显式传入且与 target 声明不一致时在装配期抛错。同样自 0.21.0 起，`inputSchema` + `mapInput`（必须成对出现）启用 typed 委派：工具以自定义 schema 为输入——ask-only，没有 `mode`/`workspaceGrants`——先校验父级入参再调用子级，并由 `mapInput` 把校验后的入参投影成子级 prompt。还接收宿主持有的 `metadata`（需要 0.22.0），透传到 `ToolDefinition.metadata`，不展示给模型。自 0.23.0 起又固定了两种契约组合：显式声明 `outputSchema` 而 target 未声明时放行，并按父级 schema 校验子级的 `structuredResult`；父子都没声明 schema 时，`ask` 会把子级的 `structuredResult` 原样（未校验）以 JSON 透出，而不是回退成文本 content 丢弃它。
`DelegateToolOptions`	mailbox-backed AgentLike 委托配置。
`SkillDefinition`	可复用指令包。
`MCPClient`	`createMCPTools()` 使用的最小 MCP client 接口。
`MCPStdioConnection`	已连接的 stdio MCP server。
`MCPStreamableHTTPConnection`	已连接的远程 MCP server，包含 auth/session helpers。
`Team`	围绕 lead 的可调用 wrapper，包含 members、成员 AgentLike 工具和高级 mailbox 控制能力。默认 `prompt()` 返回 root lead 的最终答案，而不是 handoff 接收回执。
`TeamRunner`	驱动 mailbox-backed AgentLike 委托工具的高级 runtime，包括需要 mailbox 后续回复才能最终交付的已接收 handoff。
`TeamRunnerMessage`	root SDK 事件和 team runner 活动事件的 union 类型。
`TeamMemberDefinition`	有名字的团队成员，带 role 和 `AgentLike`。
`TeamMailbox`	团队消息存储接口，包含成员级 `claimNext()`。
`TeamMessage`	带 thread/work item 上下文的消息记录。
`TeamDrainOptions`	`team.drain()` 的限制和 abort signal。
`TeamDrainResult`	`team.drain()` 返回的已处理、失败和轮次统计。
`SQLiteDatabaseLike`	`createSQLiteMailbox()` 接收的最小 database 接口。
`SQLiteMailboxOptions`	SQLite mailbox adapter 配置。
`PermissionDecision`	权限回调返回的允许或拒绝决策。
`ModelClient`	自定义或 mock 模型客户端接口。

错误类型

Error	说明
`APIError`	Provider 请求或响应失败。
`ToolExecutionError`	工具 handler 执行失败。
`MaxTurnsError`	Agent loop 达到 `maxTurns`。
`AbortError`	请求被中断。
`TimeoutError`	模型请求超过 `requestTimeoutMs`，result subtype 为 `error_timeout`。
`ToolBatchRejectedError`	工具批次在任何工具执行前被拒绝。
`ConcurrentQueryError`	Agent 上一次 query 尚未结束时又发起了一次。一个 Agent 只承载一个会话。
`MissingOutputError`	设置了 `AgentOptions.outputSchema` 的 run 在模型未调用 `submit_output` 的情况下结束；result subtype 为 `error_missing_output`。