示例

按任务选择 Agent SDK 示例并在本地运行。

​

从示例开始

SDK 仓库的 examples/ 目录包含 30 余个可运行示例，按基础查询、多轮会话、Tool、Skill、MCP、subagent、权限和 UI 集成组织。本页是策划索引；examples/ 目录本身是权威来源。

克隆仓库并安装依赖后，可直接运行一个示例：

git clone https://github.com/zerone-agents/agent-sdk.git
cd agent-sdk
npm install
npx tsx examples/basic/01-simple-query.ts

运行前设置所选 Provider 的 API key。涉及文件或 Bash 的示例应在临时工作目录运行，并先检查权限配置。

​

类别总览

类别	内容
basic/	简单查询、多 Tool、多轮、prompt API、系统提示词
tools/	自定义 Tool、权限、二进制读取、TodoWrite、Edit Tool
agents/	Subagent、Task Tool 模式、MultiTask 编排
skills/	上下文内 Skill、文件系统 Skill Agent
sessions/	Session 回退、分叉、查询上限
streaming/	流式响应、带 Tool 的流式、子任务事件
mcp/	MCP server 集成、自定义 MCP Tool
advanced/	Hook、OpenAI/官方 API 兼容、Web 搜索、压缩、推理强度
testing/	并行 Tool、max tokens、连接错误的测试工具

​

基础

示例	说明
examples/basic/01-simple-query.ts	带事件处理的流式查询
examples/basic/02-multi-tool.ts	多 Tool 编排（Glob + Bash）
examples/basic/03-multi-turn.ts	多查询 Session 持久化
examples/basic/04-prompt-api.ts	阻塞式 prompt() API
examples/basic/05-custom-system-prompt.ts	自定义系统提示词

​

Tool 与权限

示例	说明
examples/tools/07-custom-tools.ts	用 defineTool() 自定义 Tool
examples/tools/10-permissions.ts	带 Tool 限制的只读 Agent
examples/tools/21-test-read-binary.ts	Read Tool 二进制文件处理（图片、tar.gz）
examples/tools/22-todowrite.ts	用 TodoWrite Tool 做结构化任务跟踪
examples/tools/28-edit-tool-features.ts	Edit Tool 高级特性（old_string 校验、多文件）
examples/tools/37-read-directory.ts	用 Read Tool 列出目录
examples/tools/38-tool-env-isolation.ts	控制 Bash/Grep 子进程可见的环境变量（宿主嵌入隔离）

​

Agent 与 Subagent

示例	说明
examples/agents/09-subagents.ts	Subagent 委派
examples/agents/29-task-tool-modes.ts	Task Tool 的 subagent_type 模式（explore 与 general）
examples/agents/30-multitask.ts	用 MultiTask Tool 并行编排 subagent

​

Skill

示例	说明
examples/skills/12-skills.ts	Skill 系统用法
examples/skills/14-filesystem-skills-agent.ts	文件系统 Skill 加载
examples/skills/15-nested-skills.ts	嵌套 Skill 目录 + frontmatter 覆盖 + 变量替换

​

Session 与历史

示例	说明
examples/sessions/23-session-revert.ts	将 Session 回退到之前的消息状态
examples/sessions/24-fork-from-message.ts	从任意消息分叉 Session
examples/sessions/25-revert-fork-guide.ts	完整指南：回退与分叉模式
examples/sessions/26-agent-revert-api.ts	Agent 回退 API（程序化 Session 回退）
examples/sessions/27-caller-revert-flow.ts	调用方控制的回退流程
examples/sessions/31-session-query-limit.ts	用 maxSessionQueries 限制 Session 上下文

​

流式

示例	说明
examples/streaming/16-streaming.ts	流式响应（行分隔 JSON 事件）
examples/streaming/17-streaming-with-tools.ts	带 Tool 调用与结果的流式
examples/streaming/33-subtask-completed-event.ts	流式模式下的子任务完成事件
examples/streaming/34-streaming-tool-results.ts	流式 Tool 结果（中间输出）

​

MCP 集成

示例	说明
examples/mcp/06-mcp-server.ts	MCP server 集成
examples/mcp/11-custom-mcp-tools.ts	tool() + createSdkMcpServer()

​

高级特性

示例	说明
examples/advanced/08-official-api-compat.ts	query() API 模式
examples/advanced/13-hooks.ts	生命周期 hook
examples/advanced/15-openai-compat.ts	OpenAI / DeepSeek 模型
examples/advanced/18-system-preset-alignment.ts	系统预设对齐，保持行为一致
examples/advanced/19-web-search.ts	Web 搜索 Tool 集成
examples/advanced/20-compact-features.ts	压缩特性（上下文窗口管理）
examples/advanced/32-reasoning-effort.ts	推理强度控制

​

Web UI

示例	说明
examples/web/server.ts	用于测试的 Web 聊天界面

运行任意示例：

npx tsx examples/basic/01-simple-query.ts
npx tsx examples/agents/09-subagents.ts
npx tsx examples/streaming/34-streaming-tool-results.ts

启动 Web UI：

npx tsx examples/web/server.ts

​

推荐路径

1. 简单 blocking query。
2. Streaming 事件消费。
3. 自定义 Tool。
4. Session 恢复。
5. Skill 与 subagent 能力隔离。