CodeBuddy · 腾讯云课程资料

CodeBuddy Agent SDK

面向开发者的 AI 编程、上下文工程与多 Agent 协作。

返回专题 →智能体教程 →

来源：腾讯云培训认证中心 · CodeBuddy 架构师认证课程 · ch8

第 八 章 · Chapter 8

CodeBuddy Agent SDK

本 章 学 什 么

  • 理解 SDK 定位：从「手动用 CodeBuddy」升级到「用代码编排 CodeBuddy」

  • 掌握两大核心 API：query() 单次任务自动化 / Session 多轮对话

  • 理解钩子安全机制：PreToolUse 拦截工具调用，控制行为边界

  • 看懂多智能体架构（主智能体协调 + 子智能体并行）

CodeBuddy Agent SDK 不是一个"聊天界面"，它是一个"开发接口"——你的代码负责发任务、传参数、配工具范围；CodeBuddy 负责推理、调工具、执行步骤；然后把结果流式返回给你。

从手动用 CodeBuddy，升级到用代码编排 CodeBuddy。

8.1 query() API 与核心组件

SDK 定位与架构

SDK 的工作原理：把 CodeBuddy Code CLI 当作子进程启动，通过 stdin/stdout 跟它通信，让智能体自主执行任务。SDK 不是简单地"请求模型回答个问题"，而是把 CodeBuddy Code 的 Agent 能力包装成代码可调的接口。

环境准备

装 Bun（或 Node.js 18+）和 CodeBuddy CLI 并完成认证

安装依赖

npm install @tencent-ai/agent-sdk typescript @types/node tsx zod

克隆示例仓库

git clone https://cnb.cool/codebuddy/agent-sdk-demos

设置 API Key

export CODEBUDDY_API_KEY=你的key复制

运行链路——示例仓库 + 运行时 + 已认证 CLI + API Key + 具体示例目录，缺任何一个连接都会失败。

7 个演示项目（从简单到复杂递进，建议按顺序学）：

  • 快速入门——最简 SDK 调用示例

  • V2 会话——Session API 多轮对话

  • 档案生成器——搜索 → 整理 → 生成脚本 → 输出文档

  • 智能聊天——SDK + Web 应用集成

  • 研究助理——多智能体协作

  • 表格助手——Excel 创建与分析

  • 邮件助理——IMAP 邮件客户端

query() · 单次任务自动化

SDK 用 query() 函数返回一个消息的异步可迭代对象——传 prompt 和 options，用 for await 循环一条条处理消息。

选项 作用
maxTurns 最大对话轮数，默认 100——防止任务无限循环
cwd 工作目录，必须存在——决定 Agent 在哪个目录跑
model 模型选择，支持 GLM、hunyuan 等
allowedTools 允许用的工具数组——安全边界的一部分

三类消息类型

消息 含义
system 系统级消息和提示
assistant CodeBuddy 的响应——包含实际文本内容
result 工具执行结果

提取 AI 回复的标准写法：判断 message.type === 'assistant'，遍历 message.content 找 type === 'text' 的内容块，取 text 字段。

可用工具与钩子机制

可用工具覆盖文件操作（Read/Write/Edit/MultiEdit）、搜索（Glob/Grep/WebSearch）、执行（Bash/Task）、实用工具（TodoWrite/WebFetch）和规划（ExitPlanMode）——你配什么 Agent 就能用什么。

钩 子 机 制 · 安 全 考 点

钩子可以拦截和控制工具使用。PreToolUse 钩子在工具执行前触发——例：强制 .js/.ts 文件只能写到 custom_scripts 目录。返回 continue: true 放行，decision: block 拒绝。matcher 支持正则匹配工具名。 三件事一起记：工具决定 Agent 能做什么 / 钩子决定哪些动作被允许 / 消息解析决定程序怎么读结果。

8.2 Session API · 多轮对话

query() vs Session

维度 query() Session
上下文管理 需要手动管理 原生支持多轮对话
会话恢复 不支持 通过 session_id 恢复
运行方式 启动本地子进程 直接连接云服务
适用场景 单次任务自动化、CI/CD 多轮对话交互、交互式调试

query() 像"一次性任务执行器"，适合 CI/CD、自动审查、批处理；Session 像"持续对话通道"，适合聊天应用、交互式调试、多轮问答。

术语对照 · 考点

CodeBuddy SDK 把这套能力叫 Session API，通用 Agent 框架（Anthropic Agent SDK、LangChain）里同样能力常叫 Memory（记忆管理）——叫法不同，本质一样：让 Agent 在多轮对话里持久化上下文和状态。考试出现"Memory 能力"，对应 CodeBuddy 就是 Session API。

核心特性与四种运行模式

三个关键词：上下文（多轮保留交互历史）、会话（通过 ID 继续或恢复）、状态（整个生命周期内维护 Agent 状态）。

运行模式 用途
basic 基础会话
multi-turn 多轮对话（核心）
one-shot 单次查询
resume 会话恢复（跨会话保持上下文）

API 用法：createSession 创建会话 / session.send 发消息 / session.stream 接收流式响应 / resumeSession 恢复会话 / unstable_v2_prompt 单次查询便捷函数。

认证配置——设置 CODEBUDDY_API_KEY。中国版从 copilot.tencent.com 获取，并设 CODEBUDDY_INTERNET_ENVIRONMENT=internal。密钥别写进代码仓库，通过环境变量管理。

独立任务选 query()，持续交互选 Session。

8.3 档案生成器实战

输入一个人名，最终拿到一份 Word 简历——搜索 / 整理 / 生成脚本 / 执行脚本全由 Agent 自动搞定。这就是 SDK + 工具调用 + 文件生成的完整闭环。

工作原理四步

  • 用 WebSearch 搜索这个人的职业背景

  • 收集当前职位、过往经历、教育背景和技能

  • 生成一个用 docx 库创建简历的 JS 文件

  • 执行脚本，生成 .docx 文件

这是典型的 Agent 工作流：拿信息 → 整理信息 → 生成代码 → 跑代码出文件。不光"生成文本"，还有"调工具"和"跑脚本"——这是 Agent 和普通对话的本质区别。

cd profile-builder npm install npm start "人名"

输出保存到 agent/custom_scripts/resume.docx复制

技术要点——SDK 调 WebSearch 搜 LinkedIn / 公司页面 / 新闻 / GitHub；钩子确保文件只能写到 custom_scripts 目录。

Agent SDK 的价值不是回答一句话就完了，而是能把搜索、分析、写文件、跑脚本这些步骤串成一条自动化流水线。

8.4 智能聊天应用实战

技术架构

React 前端（Vite）+ Express 后端 + WebSocket 实时通信。前端 localhost:5173，后端 localhost:3001，npm run dev 同时启动两端。

这套架构很典型——前端负责页面，后端调 SDK，WebSocket 把 AI 流式消息实时推给前端。用户看到的不是"等半天一次性返回"，而是 AI 执行过程在不断更新。

生产部署四件事 · 必考

事项 原因
① 隔离 Agent SDK 移到单独容器/服务——智能体能访问 Bash、文件、网络，别跟核心业务混跑
② 持久化存储 用数据库替换内存 ChatStore——内存数据重启就没了
③ 会话记录同步 持久化 SDK 对话记录
④ 身份验证 用户认证和授权——不能谁都能触发高权限操作

结论：Demo 可以本地跑，上生产要做隔离、持久化和认证。

8.5 多智能体研究助理

这是 Agent 架构里的分工协作——主智能体协调，子智能体并行执行，通过 Task 工具委派。

四个角色

角色 职责 工具 输出
主智能体 协调流程、把请求拆成 2-4 个子主题、用 Task 委派 Task 调度规划
研究员 多个并行搜索网络 WebSearch + Write files/research_notes/
数据分析师 提取指标、生成图表 Glob/Read/Bash/Write files/charts/
报告撰写者 整合所有发现成 PDF 报告 Skill/Write/Glob/Read/Bash files/reports/

多智能体不是一堆 AI 随便聊天，而是有主智能体协调、有子智能体分工、有明确的文件输出位置——角色清晰、边界清晰，才是可控的多智能体系统。

内置斜杠命令

研究助理预设了 5 个斜杠命令，相当于预定义的研究入口——不用写长 prompt，一条命令触发一类流程：

命令 功能
/research 开始研究
/competitive-analysis 竞品分析
/market-trends 行业趋势
/fact-check 事实核查
/summarize 总结发现

钩子跟踪与日志 · 可观测性

多智能体系统一旦复杂，就必须能追踪过程——钩子不只能做安全拦截，还能做可观测性。

  • pre_tool_use 记录工具调用前的信息（谁、什么、何时、输入）

  • post_tool_use 记录执行后的结果（输出、状态）

  • parent_tool_use_id 把工具调用归到对应的子智能体

两种日志输出

日志 格式 用途
transcript.txt 人类可读：[RESEARCHER-1] → WebSearch 输入 query 回放和排查
tool_calls.jsonl 结构化 JSON：event/agent_id/tool_name/success/output_size 统计、监控、后续分析

多智能体系统里日志不是可选的，而是调试和评估的基础。

8.6 更多案例

案例 能力 注意
表格助手 AI 驱动 Excel 创建、分析、操作（带公式、格式、多工作表）；React 前端 + Express 后端 + Python 脚本生成；支持上传 .xlsx/.xls/PDF/Word 分析 SDK 跟办公文档处理结合
邮件助理 IMAP 邮件客户端，AI 驱动；看收件箱、智能搜索、AI 辅助；支持 Gmail / QQ 邮箱 只能本地用，凭据是纯文本存储——不能直接当生产系统
Python 支持 研究助理用 Python（uv sync + uv run python）；表格助手支持 Python 脚本（openpyxl） SDK 不只限 JS/TS，也支持 Python 生态

共同模式：设置 API Key → 安装依赖 → npm run dev 或 uv run。示例展示的是能力，生产系统还得补齐工程和安全要求。

8.7 练习与自测

练习重点是把 SDK 调通、把钩子配对、把安全边界想清楚——不要求项目多复杂，关键是理解调用链路和工具控制。

三个层级的练习

  • **档案生成器跑通（必做）。**克隆 agent-sdk-demos 仓库，配置 CODEBUDDY_API_KEY，运行 npm start "人名"，确认 custom_scripts/resume.docx 生成成功。验收：文件存在且内容结构完整（职业概要 / 工作经历 / 教育背景 / 核心技能），终端能看到 WebSearch 工具被调用的过程

  • 钩子拦截实验（推荐）。在档案生成器代码里，把 PreToolUse 钩子的 custom_scripts 路径改为其他目录，然后运行看 Agent 是否还能正常写入。*记录差异——这个实验让你理解钩子不只是"建议"，而是真正的安全边界*

  • **query() vs Session 对比（进阶）。**用 query() 做一次单次任务（如代码审查），再用 Session API 做一次多轮对话（如需求讨论 + 代码修改 + 验证）。对比两者在上下文管理、工具使用、运行方式上的差异。重点体验 Session 的 resumeSession 能力

自测清单

以下问题都能答上来，说明 Agent SDK 主线已经掌握：

能力维度 自测问题
两大 API 能说出 query() 和 Session 的核心区别（单次任务 vs 多轮对话、子进程 vs 云服务）？/ 知道什么时候该选哪个？
钩子安全 能解释 PreToolUse 钩子的工作原理？/ 能写出一个限制文件写入目录的钩子？/ 知道 HITL（Human-in-the-Loop）怎么用钩子实现？
ReAct 与多智能体 能解释 ReAct 模式的"推理→行动→循环"流程？/ 能说出主智能体和子智能体的分工原则（主智能体不亲自执行）？

8.8 核心收获

高频考点速查

ReAct 模式（Reasoning + Acting）

Agent 执行多步骤任务的核心机制：Reasoning（先想下一步该做什么）→ Acting（执行操作——调工具、读数据、改文件）→ 循环（做完一步重新推理下一步，直到任务完成）。例：数据分析 Agent「查数据库 → 数据清洗 → 生成报告 → 发送通知」。 Agent 不是一次性生成答案，而是在"推理"和"行动"之间循环——这是和普通对话最本质的区别。

Agent SDK vs 直接调用 LLM API · 高频考点

维度 直接调 LLM API Agent SDK
能力范围 单轮问答，输入→输出 工具调用 + 记忆管理 + 多步骤推理
状态管理 无状态，每次独立 Session API 支持多轮上下文、会话恢复
工具集成 需要自行实现 内置 Read / Write / Bash / WebSearch 等工具
本质 文本生成接口 带工具、带状态、能多步骤执行的智能体开发框架

Agent System Prompt 设计四要素

  • 角色定位——Agent 是谁，专注什么领域

  • 工具使用边界——哪些工具能用、哪些不能

  • 任务执行策略——遇到不确定怎么处理

  • 输出格式要求——结果的结构和格式

设计 Agent 时，System Prompt 不是随便写句"你是专家"就完了——四个要素缺一不可。

Pipeline · Human-in-the-Loop · RAG · 异常处理

概念 含义
Pipeline 流水线 多 Agent 串行工作，上游输出 = 下游输入。例：数据采集 → 分析 → 报告生成。研究助理本质就是 Pipeline
Human-in-the-Loop Agent 执行高风险操作（删数据、发外部消息、改生产配置）前强制暂停等人工确认，用 PreToolUse 钩子拦截敏感工具实现
RAG 处理长文档 文档超出上下文窗口时：分块 → 向量化存储 → 检索相关块注入上下文。每次只看相关 2-3 页，回答更准、Token 消耗大幅降低
异常处理 可重试（网络超时、服务临时不可用）→ 自动重试 2-3 次 + 指数退避；需人工介入（权限不足、认证失败、资源不存在）→ 停止执行反馈用户

本章小结

  • 两大 API——query() 单次任务自动化（CI/CD、自动审查、批量生成），Session 多轮对话交互（聊天、调试、持续问答）

  • 钩子安全——PreToolUse 拦截工具调用，控制文件写入范围。Agent 能力越强，边界越重要

  • 多智能体——主智能体协调 + 子智能体并行执行，通过 Task 工具委派。角色清晰、边界清晰、文件输出位置明确

  • 案例路径——快速入门 → 档案 → 聊天 → 研究 → 表格 → 邮件，渐进式学习

下一模块进入**「多 Agent 协同架构」**——把 Agent 自动化、MCP 接入、Speckit 规约、任务拆分、交付验证全串起来，看几个 Agent 一起干活时怎么分工、调度、传上下文、处理冲突。