先看要点#

• Agent SDK 把「模型 + 工具 + 记忆 + 子智能体」打包成一个可直接调用的运行时，一行 query() 就能跑起一个会自己上网、写文件、执行命令的智能体。
• 同一套 SDK 提供两种语言入口：TypeScript（@tencent-ai/agent-sdk）与 Python（codebuddy-agent-sdk），心智模型一致：查询（query）→ 会话（session）→ 编排（agents/hooks）。
• 该示例仓库的 7 个示例正好串起一条能力进化线：单次问答 → 多轮对话 → 会话恢复 → 工具与钩子 → 多智能体编排 → 全栈聊天应用 → AI 自举的邮件助理。
• 选示例时可以按用途来：quick-start 用来熟悉调用，chat-demo 用来研究聊天应用，research-assistant 展示多智能体分工，mail-assistant 则适合看较完整的应用架构。

一、SDK 是什么：不是「调用 API」，而是「托管一个智能体」#

传统做法里，接入大模型要走一条很长的路：

1
Prompt 工程 → 函数调用 Schema → 工具注册 → 循环调度
2
→ 上下文管理 → 子任务拆分 → 流式输出 → 错误恢复 → 安全护栏

而 Agent SDK 把这套「智能体运行时」直接下沉成一行代码：

1
// quick-start/quick-start.ts（摘录）
2
import { query } from '@tencent-ai/agent-sdk';
3
import * as path from 'node:path';
4

5
const q = query({
6
  prompt: '你好！请用简洁的方式告诉我你擅长做什么事情。',
7
  options: {
8
    maxTurns: 100,
9
    cwd: path.join(process.cwd(), 'agent'),
10
    allowedTools: ['Task', 'Bash', 'Glob', 'Grep', 'Read', 'Write', 'Edit',
11
                   'WebFetch', 'WebSearch', 'TodoWrite', 'KillBash'],
12
    debug: true,
13
  },
14
});
15

16
for await (const message of q) {
17
  if (message.type === 'assistant' && message.message) {
18
    const textContent = message.message.content.find((c: any) => c.type === 'text');
19
    if (textContent && 'text' in textContent) {
20
      console.log('智能体回复：', textContent.text);
21
    }
22
  }
23
}

query() 返回异步消息流。在这些示例中，assistant 消息的 message.content 可以包含 text 和 tool_use 内容块，result 表示本轮结束；应用再把内容块转成自己的 WebSocket 事件。不能把 tool_use 内容块当成固定的顶层消息类型或固定先后顺序。

Python 侧完全镜像：

1
# research-assistant/research_agent/agent.py（摘录）
2
from codebuddy_agent_sdk import CodeBuddySDKClient, CodeBuddyAgentOptions
3

4
async with CodeBuddySDKClient(options=options) as client:
5
    await client.query(prompt=query_text)
6
    async for msg in client.receive_response():
7
        if type(msg).__name__ == 'AssistantMessage':
8
            process_assistant_message(msg, tracker, transcript)

值得注意：本文摘录省略了部分模型配置，便于聚焦调用结构；官方示例实际上有显式 model 设置。运行时需按当前 SDK、账号权限和认证配置选择可用模型，不能假设所有示例都会自动继承同一个默认模型。

二、七个示例，一条能力进化线#

把它们排成一条线，就是 Agent 应用从玩具到生产力的四个里程碑：

1
里程碑 ① 会聊天          → quick-start / multi-turn-session
2
里程碑 ② 会干活（工具）  → profile-builder / spreadsheet-assistant
3
里程碑 ③ 会分工（多体）  → research-assistant
4
里程碑 ④ 会自举（扩展）  → mail-assistant / chat-demo（全栈形态）

三、核心概念地图#

示例再多，底层概念就五个：

1
// multi-turn-session/examples.ts（摘录）
2
await using session = unstable_v2_createSession({}); // 不指定模型
3

4
await session.send('今年是哪一年？只回答年份数字。');
5
for await (const msg of session.stream()) { /* …第一轮… */ }
6

7
await session.send('再往后推10年是哪一年？只回答数字。'); // 它还记得上一轮
8
for await (const msg of session.stream()) { /* …第二轮… */ }

1
// 根据 quick-start 示例改写：补上路径规范化与目录边界检查。
2
import * as path from 'node:path';
3

4
const customScriptsPath = path.resolve(process.cwd(), 'agent/custom_scripts');
5
const hooks = {
6
  PreToolUse: [{
7
    matcher: 'Write|Edit|MultiEdit',
8
    hooks: [
9
      async (input: any) => {
10
        const filePath = path.resolve(input.tool_input.file_path ?? '');
11
        const relative = path.relative(customScriptsPath, filePath);
12
        const outside = relative === '..'
13
          || relative.startsWith('..' + path.sep)
14
          || path.isAbsolute(relative);
15
        if (['.js', '.ts'].includes(path.extname(filePath).toLowerCase())
16
            && outside) {
17
          return {
18
            decision: 'block',               // ← 拦截
19
            stopReason: '脚本必须写入 custom_scripts 目录',
20
            continue: false,
21
          };
22
        }
23
        return { continue: true };
24
      },
25
    ],
26
  }],
27
}; // 通过 query({ prompt, options: { hooks } }) 使用

四、两种调用形态：CLI 与 Server#

7 个示例也展示了智能体应用的两种主流形态：

1
# quick-start：跑一次对话
2
npx tsx quick-start.ts
3

4
# profile-builder：研究一个人并生成 docx 简历
5
npx tsx profile-builder.ts "张三"
6

7
# research-assistant：交互式研究，产出带图表的 PDF
8
uv run python research_agent/agent.py  # 启动后在 REPL 输入研究问题

1
浏览器 (React)
2
   │  ① subscribe { chatId }
3
   │  ② chat { content }
4
   ▼
5
WebSocket Server ──► ChatSession（一个聊天 = 一个会话）
6
   │                    │  query() 流式输出
7
   │                    ▼
8
   │              SDK Agent 运行时
9
   │  ③ 广播 assistant_message / tool_use / result
10
   ▼
11
浏览器实时渲染「公开文本、工具事件与执行结果」

五、mail-assistant：运行时生成脚本#

最后一个示例值得单独讲，因为它把 Agent 的边界推到了「让 AI 自己扩展自己」：

1. 智能体（模型）运行在 agent/ 工作区，能读懂 CODEBUDDY.md 里声明的子智能体（如 inbox-searcher，自带“假设驱动迭代搜索”方法论）与技能（skills/action-creator、listener-creator，为它提供「造插件」的模板）；
2. 当模型被允许写代码时，示例用 PreToolUse 钩子检查通过 Write/Edit/MultiEdit 写入的 .ts 路径，约定保存到 agent/custom_scripts/——这个目录同时被服务端的 Actions/Listeners Manager 用文件 watcher 热加载；
3. 于是：用户说「把超过 30 天的促销邮件归档」→ 模型调用 action-creator 技能现场写一个 action 脚本 → 文件落盘后由 watcher 尝试加载。Action 需要被调用才执行；只有另外创建并启用符合接口的 Listener，才会在匹配事件到来时触发，不能把两种扩展混为一谈。

1
用户一句话 ──► 模型写代码 ──► custom_scripts/ 落盘
2
                                   │  watcher 热重载
3
                                   ▼
4
                Actions（点一下执行）/ Listeners（事件自动触发）
5
                                   │
6
              IMAP IDLE 收新邮件 ──► 自动处理 ──► SQLite / FTS5 检索

配套的还有 SQLite 邮件库（含 FTS5 全文索引）、HTTP/REST 与 WebSocket 两类通信（邮件同步通过 IMAP，WS 推聊天与 UI 状态）、React + Tailwind 前端。它不是「邮件 + 一个聊天框」，而是「一个会持续值守、并且能自己学会新任务的员工」。

六、按需求选择示例#

七、结语#

把七个示例连起来看，Agent SDK 想传达的产品哲学很清楚：

把「智能体的运行与治理」做成基础设施，让开发者专注于「业务、体验与边界」。

• SDK 接管了部分运行循环；工具权限、钩子、角色分工和业务错误处理仍需要应用自己设计；
• 可观测性被内置：消息流可以用来记录工具调用与结果；完整审计还需要持久化、关联 ID、错误处理和日志脱敏；
• 需要扩展时，可以接入 MCP 工具、Skill 或自定义 Actions/Listeners。

核对资料#

• SDK 权限规则