Agent SDK 集成开发

引言

CodeBuddy 的 Agent 能力不仅能在 IDE 和 CLI 中使用，还能通过 SDK 嵌入到你自己的应用中。

Agent SDK 提供 TypeScript 和 Python 两种语言的编程接口，让你可以将 CodeBuddy 的对话、工具调用、子代理等能力集成到任何应用。

核心价值：不是"用 CodeBuddy"，而是"把 CodeBuddy 的能力放进你的产品"。

---

一、SDK 概览

1.1 支持的语言

语言	包名	安装
TypeScript	@tencent-ai/codebuddy-sdk	npm install @tencent-ai/codebuddy-sdk
Python	codebuddy-sdk	pip install codebuddy-sdk

1.2 核心能力

• 流式消息传输：实时获取 Agent 的输出
• 多轮对话：维护对话上下文
• 权限控制：精细控制 Agent 可使用的工具
• Hook 系统：在工具执行前后插入自定义逻辑
• 自定义子 Agent：创建专门化的 Agent
• MCP 集成：连接外部工具和数据源

---

二、快速开始

2.1 TypeScript 示例

import { CodeBuddyAgent } from '@tencent-ai/codebuddy-sdk';

const agent = new CodeBuddyAgent({
  apiKey: process.env.CODEBUDDY_API_KEY,
  model: 'hunyuan-turbos',
});

// 发送消息，获取流式响应
const stream = await agent.chat('帮我分析这个项目的代码质量');

for await (const chunk of stream) {
  process.stdout.write(chunk.text);
}

2.2 Python 示例

from codebuddy import Agent

agent = Agent(
    api_key=os.environ["CODEBUDDY_API_KEY"],
    model="hunyuan-turbos",
)

# 发送消息
response = agent.chat("帮我分析这个项目的代码质量")
print(response.text)

---

三、权限控制

3.1 四种权限模式

模式	说明	适用场景
default	默认权限，需要用户确认	交互式应用
acceptEdits	自动接受文件编辑	CI/CD 流程
plan	只允许规划，不允许执行	需求分析
bypassPermissions	跳过所有权限检查	受信环境

3.2 自定义权限回调

const agent = new CodeBuddyAgent({
  canUseTool: (toolName, args) => {
    // 自定义权限逻辑
    if (toolName === 'terminal' && args.command.includes('rm')) {
      return { allowed: false, reason: '禁止删除操作' };
    }
    return { allowed: true };
  }
});

---

四、Hook 系统

4.1 六种 Hook 事件

const agent = new CodeBuddyAgent({
  hooks: {
    onPreToolUse: (tool, args) => {
      console.log(`即将调用 ${tool}`, args);
    },
    onPostToolUse: (tool, args, result) => {
      console.log(`${tool} 执行完成`, result);
    },
    onError: (error) => {
      console.error('Agent 错误:', error);
    },
    onStart: () => console.log('Agent 启动'),
    onEnd: () => console.log('Agent 结束'),
    onMessage: (message) => console.log('新消息:', message),
  }
});

---

五、使用场景

5.1 个人开发者

将 Agent 嵌入个人工具：

• 智能写作助手
• 代码审查机器人
• 自动化脚本生成器

5.2 AI Infra 团队

构建 AI 基础设施：

• 多 Agent 编排平台
• 智能客服系统
• 自动化运维平台

5.3 传统系统智能化

为已有系统添加 AI 能力：

• ERP 系统的智能助手
• CRM 系统的客户分析
• CMS 系统的内容生成

---

六、常见陷阱

陷阱 1：API Key 安全

❌ 在前端代码中硬编码 API Key
✅ 通过后端代理调用，API Key 存在服务端

陷阱 2：上下文溢出

❌ 无限累积对话历史
✅ 定期清理或压缩上下文

---

七、总结

问题	答案
Agent SDK 是什么？	将 CodeBuddy Agent 能力嵌入应用的 SDK
支持哪些语言？	TypeScript + Python
核心能力？	流式对话、权限控制、Hook、子代理
适用场景？	自定义 AI 应用、系统智能化