版本要求：本文档针对 CodeBuddy Agent SDK v0.1.0 及以上版本。
功能状态：SDK 当前处于 Preview 阶段，接口和行为可能在未来版本中调整。
重要：环境隔离
SDK 默认不加载任何文件系统配置，包括 settings.json、CODEBUDDY.md、MCP 服务器、子代理、斜杠命令、Rules 和 Skills。这是与 CLI 直接使用的关键区别，确保 SDK 应用的行为完全由代码控制，具有可预测性和一致性。
如需加载这些配置，请使用 settingSources 选项显式指定。
CodeBuddy Agent SDK 允许您在应用程序中以编程方式控制 CodeBuddy Agent。支持 TypeScript/JavaScript 和 Python，可实现自动化任务执行、自定义权限控制、构建 AI 驱动的开发工具等场景。
CodeBuddy Agent SDK 让您能够以编程方式访问 CodeBuddy 的全部能力，而不仅仅是通过命令行交互。
程序化控制：在您的应用程序中嵌入 AI 编程助手，实现自动化工作流
自定义交互：构建符合您需求的用户界面和交互方式
批量处理：对多个文件或项目执行批量 AI 操作
集成现有系统：将 AI 能力无缝集成到 CI/CD、IDE 插件或其他开发工具中
权限管控：通过 canUseTool 回调实现企业级权限策略
行为定制：使用 Hook 系统拦截和修改 Agent 行为
资源限制：控制 token 消耗、执行时间和费用预算
会话管理：持久化和恢复对话上下文
自定义 Agent：创建专门化的子 Agent 处理特定领域任务
MCP 集成：接入自定义工具和服务
多模型支持：灵活切换和配置不同的 AI 模型
IDE 插件：为 VS Code、JetBrains 等 IDE 构建智能编程助手
代码审查工具：自动化代码质量检查和安全扫描
文档生成器：自动生成 API 文档、README 和代码注释
CI/CD 集成：在流水线中执行智能代码分析和修复
测试生成：自动生成单元测试和集成测试
重构助手：批量执行代码重构和迁移任务
内部开发平台：构建企业级 AI 编程平台
知识库问答：基于代码库的智能问答系统
培训工具：交互式编程学习和代码评审系统
消息流式传输：实时接收系统消息、助手响应和工具调用结果
多轮对话：支持跨多次推理调用的对话上下文保持
会话管理：通过会话 ID 继续或恢复现有对话
权限控制：细粒度的工具访问权限管理
Hook 系统：在工具执行前后插入自定义逻辑
自定义 Agent：定义专门化的子 Agent 处理特定任务
MCP 集成：支持配置自定义 MCP 服务器扩展功能
TypeScript
Python
npm install @tencent-ai/agent-sdk# 或yarn add @tencent-ai/agent-sdk# 或pnpm add @tencent-ai/agent-sdk
语言 | 版本要求 |
TypeScript/JavaScript | Node.js >= 18.20 |
Python | Python >= 3.10 |
如果您已经在终端中通过 codebuddy 命令完成了交互式登录，SDK 会自动使用该认证信息，无需额外配置。
如果未登录或需要使用不同的凭据，可以通过 API Key 认证：
export CODEBUDDY_API_KEY="your-api-key"
获取 API Key：
版本 | 获取地址 |
海外版 | |
中国版 |
注意：
使用 CODEBUDDY_API_KEY 时，必须根据版本正确配置 CODEBUDDY_INTERNET_ENVIRONMENT 环境变量：
海外版：不设置（默认）
中国版：export CODEBUDDY_INTERNET_ENVIRONMENT=internal
iOA 版：export CODEBUDDY_INTERNET_ENVIRONMENT=ioa
专享版：export CODEBUDDY_INTERNET_ENVIRONMENT=cloudhosted
私有化部署：export CODEBUDDY_INTERNET_ENVIRONMENT=selfhosted
详见 身份和访问管理文档。
也可以在代码中通过 env 选项传递：
TypeScript
Python
const q = query({ prompt: '...', options: { // 仅专享版或私有化部署用户需要设置，填写您的企业服务地址： // endpoint: 'https://your-company.copilot.qq.com', env: { CODEBUDDY_API_KEY: process.env.MY_API_KEY, // 中国版用户需要设置： // CODEBUDDY_INTERNET_ENVIRONMENT: 'internal' // iOA 版用户需要设置： // CODEBUDDY_INTERNET_ENVIRONMENT: 'ioa' // 专享版用户需要设置： // CODEBUDDY_INTERNET_ENVIRONMENT: 'cloudhosted' // 私有化部署用户需要设置： // CODEBUDDY_INTERNET_ENVIRONMENT: 'selfhosted' } }});
目前仅介绍 Client Credentials 授权方式，适用于服务端应用和 CI/CD 场景。
前提条件：企业用户需要先购买旗舰版才能使用 OAuth 认证。详见 旗舰版购买指南。
企业用户需要先通过 OAuth 2.0 Client Credentials 流程获取 access token，然后传入 SDK。
第 1 步：创建应用获取凭据
参考 企业开发者快速入门 创建应用并获取 Client ID 和 Client Secret。
第 2 步：获取 token 并调用 SDK
TypeScript
Python
async function getOAuthToken(clientId: string, clientSecret: string): Promise<string> {
const response = await fetch('https://copilot.tencent.com/oauth2/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'client_credentials',
client_id: clientId,
client_secret: clientSecret,
}),
});
const data = await response.json();
return data.access_token;
}
// 获取 token 并调用 SDK
const token = await getOAuthToken('your-client-id', 'your-client-secret');
for await (const msg of query({
prompt: 'Hello',
options: {
env: { CODEBUDDY_AUTH_TOKEN: token },
},
})) {
console.log(msg);
}
详细的认证配置说明请参阅 身份认证。
变量名 | 说明 | 是否必需 |
| CodeBuddy CLI 可执行文件路径 | 可选 |
如果未设置，SDK 会自动尝试查找 CLI。
最基础的用法是发送一个提示词并处理响应：
TypeScript
Python
import { query } from '@tencent-ai/agent-sdk';
async function main() {
const q = query({
prompt: '请解释什么是递归函数',
options: {
permissionMode: 'bypassPermissions'
}
});
for await (const message of q) {
if (message.type === 'assistant') {
for (const block of message.message.content) {
if (block.type === 'text') {
console.log(block.text);
}
}
}
}
}
main();
查询完成后，会收到一个 result 消息，包含执行统计信息：
TypeScript
Python
for await (const message of q) { if (message.type === 'result') { if (message.subtype === 'success') { console.log('完成！耗时：', message.duration_ms, 'ms'); console.log('费用：', message.total_cost_usd, 'USD'); } else { console.log('执行出错'); } }}
SDK 返回多种类型的消息：
TypeScript
Python
for await (const message of q) {
switch (message.type) {
case 'system':
// 会话初始化消息
console.log('会话 ID:', message.session_id);
console.log('可用工具：', message.tools);
break;
case 'assistant':
// AI 助手响应
for (const block of message.message.content) {
if (block.type === 'text') {
console.log('[文本]', block.text);
} else if (block.type === 'tool_use') {
console.log('[工具调用]', block.name, block.input);
} else if (block.type === 'tool_result') {
console.log('[工具结果]', block.content);
}
}
break;
case 'result':
// 查询完成
console.log('执行完成，耗时：', message.duration_ms, 'ms');
break;
}
}
通过 permissionMode 控制工具调用的权限行为：
模式 | 说明 |
| 默认模式，所有操作需确认 |
| 自动批准文件编辑，Bash 仍需确认 |
| 规划模式，仅允许读取操作 |
| 跳过所有权限检查（谨慎使用） |
TypeScript
Python
const q = query({ prompt: '分析项目结构', options: { permissionMode: 'plan' // 只读模式 }});
指定 Agent 的工作目录：
TypeScript
Python
const q = query({ prompt: '读取 package.json', options: { cwd: '/path/to/project' }});
指定使用的 AI 模型：
TypeScript
Python
const q = query({ prompt: '...', options: { model: 'deepseek-v3.1', fallbackModel: 'deepseek-v3.1' }});
限制执行范围：
TypeScript
Python
const q = query({ prompt: '...', options: { maxTurns:20 // 最大对话轮数 }});
SDK 默认不加载任何文件系统配置，提供完全干净的运行环境。这是与 CLI 直接使用的关键区别。
可预测性：SDK 应用的行为完全由代码控制，不受用户或项目配置文件影响
隔离性：避免用户的个人偏好或项目设置干扰 SDK 应用的逻辑
安全性：敏感配置（如 hooks、权限规则）不会意外泄露到 SDK 环境
一致性：在不同机器上运行时，行为保持一致
场景 | Settings | Memory | MCP | Subagent | Commands | Rules | Skills |
SDK 调用（默认） | ✖ 不加载 | ✖ 不加载 | ✖ 不加载 | ✖ 不加载 | ✖ 不加载 | ✖ 不加载 | ✖ 不加载 |
CLI 直接运行 | ✔ 加载全部 | ✔ 加载全部 | ✔ 加载全部 | ✔ 加载全部 | ✔ 加载全部 | ✔ 加载全部 | ✔ 加载全部 |
配置文件位置参考：
配置类型 | 用户级位置 | 项目级位置 | 说明 |
Settings |
|
| 权限、hooks、环境变量等 |
Memory |
|
| 项目指令和上下文 |
MCP |
|
| MCP 服务器配置 |
Subagent |
|
| 自定义子代理 |
Commands |
|
| 自定义斜杠命令 |
Rules |
|
| 模块化规则文件 |
Skills |
|
| AI 自动调用的技能 |
如需加载文件系统配置，使用 settingSources 显式指定：
TypeScript
Python
const q = query({
prompt: '...',
options: {
// 加载项目配置（.codebuddy/settings.json, CODEBUDDY.md）
settingSources: ['project'],
// 或加载全部配置
// settingSources: ['user', 'project', 'local']
}
});
值 | 说明 | 位置 |
| 全局用户设置 |
|
| 项目共享设置 |
|
| 项目本地设置 |
|
CI/CD 环境：
TypeScript
Python
// 只加载项目配置，忽略用户和本地配置const q = query({ prompt: '运行测试', options: { settingSources: ['project'], permissionMode: 'bypassPermissions' }});
完全程序化控制：
TypeScript
Python
// 默认行为：不加载任何配置// 所有行为通过 options 显式定义const q = query({ prompt: '...', options: { agents: { /* 自定义 agent */ }, mcpServers: { /* 自定义 MCP */ }, allowedTools: ['Read', 'Grep', 'Glob'] }});
通过 canUseTool 回调实现细粒度权限控制：
TypeScript
Python
import { query } from '@tencent-ai/agent-sdk';
const q = query({
prompt: '分析项目结构',
options: {
canUseTool: async (toolName, input, options) => {
// 只允许读取类工具
const readOnlyTools = ['Read', 'Glob', 'Grep'];
if (readOnlyTools.includes(toolName)) {
return {
behavior: 'allow',
updatedInput: input
};
}
// 拒绝其他工具
return {
behavior: 'deny',
message: `工具 ${toolName} 不允许使用`
};
}
}
});
结合权限回调拦截危险命令：
TypeScript
Python
const dangerousCommands = ['rm -rf', 'sudo', 'chmod 777'];
const q = query({
prompt: '清理临时文件',
options: {
canUseTool: async (toolName, input) => {
if (toolName === 'Bash') {
const command = input.command as string;
for (const dangerous of dangerousCommands) {
if (command.includes(dangerous)) {
return {
behavior: 'deny',
message: `危险命令被拦截: ${dangerous}`,
interrupt: true // 中断整个会话
};
}
}
}
return { behavior: 'allow', updatedInput: input };
}
}
});
对于需要多轮交互的场景，使用 Session（TypeScript）或 Client（Python）API：
TypeScript
Python
import { unstable_v2_createSession } from '@tencent-ai/agent-sdk';
async function main() {
const session = unstable_v2_createSession({
model: 'deepseek-v3.1'
});
// 第一轮对话
await session.send('分析这个项目的架构');
for await (const message of session.stream()) {
console.log(message);
}
// 第二轮对话（保持上下文）
await session.send('请详细解释第三点');
for await (const message of session.stream()) {
console.log(message);
}
session.close();
}
在运行过程中中断执行：
TypeScript
Python
const q = query({ prompt: '执行长时间任务...' });
let count = 0;
for await (const message of q) {
if (message.type === 'assistant') {
for (const block of message.message.content) {
if (block.type === 'tool_use') {
count++;
if (count >= 10) {
await q.interrupt(); // 中断执行
break;
}
}
}
}
}
Hook 允许在工具执行前后插入自定义逻辑。
在工具执行前拦截和处理：
TypeScript
Python
const q = query({
prompt: '清理临时文件',
options: {
hooks: {
PreToolUse: [{
matcher: 'Bash', // 只匹配 Bash 工具
hooks: [
async (input, toolUseId) => {
console.log('即将执行命令：', input.command);
// 可以阻止执行
if (input.command.includes('rm')) {
return {
decision: 'block',
reason: '删除命令被阻止'
};
}
return { continue: true };
}
]
}]
}
}
});
事件 | 触发时机 |
| 工具执行前 |
| 工具执行成功后 |
| 工具执行失败后 |
| 用户提交提示词 |
| 会话开始 |
| 会话结束 |
| 创建隔离 |
| 删除隔离 |
定义专门化的子 Agent：
TypeScript
Python
const q = query({ prompt: '使用 code-reviewer 审查代码', options: { agents: { 'code-reviewer': { description: '专业代码审查助手', tools: ['Read', 'Glob', 'Grep'], // 只允许读取 disallowedTools: ['Bash', 'Write', 'Edit'], prompt: `您是代码审查专家，请检查：1. 代码规范2. 潜在 bug3. 性能问题4. 安全漏洞`, model: 'deepseek-v3.1' } } }});
集成自定义 MCP 服务器：
TypeScript
Python
const q = query({ prompt: '查询数据库', options: { mcpServers: { 'database': { type: 'stdio', command: 'node', args: ['./mcp-servers/db-server.js'], env: { DB_HOST: 'localhost', DB_PORT: '5432' } } } }});
AI 可能会通过 AskUserQuestion 工具向用户提问，可以在权限回调中处理：
TypeScript
Python
const q = query({
prompt: '配置数据库连接',
options: {
canUseTool: async (toolName, input) => {
if (toolName === 'AskUserQuestion') {
const questions = input.questions as any[];
const answers: Record<string, string> = {};
for (const q of questions) {
console.log(`问题: ${q.question}`);
// 这里可以接入实际的用户交互
answers[q.question] = q.options[0].label;
}
return {
behavior: 'allow',
updatedInput: { ...input, answers }
};
}
return { behavior: 'allow', updatedInput: input };
}
}
})
TypeScript
Python
import { query, AbortError } from '@tencent-ai/agent-sdk';
try {
const q = query({ prompt: '...' });
for await (const message of q) {
// ...
}
} catch (error) {
if (error instanceof AbortError) {
console.log('操作被中止');
} else {
console.error('发生错误：', error);
}
}
权限控制：在生产环境中使用 canUseTool 实现细粒度权限,避免使用 bypassPermissions
资源限制：使用 maxTurns 限制执行范围，防止意外的资源消耗
错误处理：始终处理 result 消息中的错误状态
Hook 超时：为 Hook 设置合理的超时时间
TypeScript SDK 参考 - TypeScript API 详细参考
Python SDK 参考 - Python API 详细参考
Hook 参考指南 - 详细的 Hook 配置说明
MCP 集成 - MCP 服务器配置指南
子 Agent 系统 - 子 Agent 详细说明
