官方教程中文版SDK 与自定义 Agent
SDK 与自定义 Agent
按 GitHub 官方 SDK 文档梳理 Copilot SDK、custom agents、hooks 和 OpenTelemetry 可观测性。
Copilot SDK 不是普通 API wrapper（API 包装层）。它让你把 Copilot 变成应用里的 agent runtime（代理运行时）：创建 session、注册工具、监听事件、定义 custom agents、插入 hooks、接入 OpenTelemetry。
这一组解决一个判断：什么时候继续用 IDE Chat / Agent mode 就够，什么时候应该做成 SDK 应用或自定义 agent。
GitHub 官方文档标注 Copilot SDK 目前处于 public preview。生产化前必须保留版本、日志、回滚和权限边界。
1. 能力地图
flowchart TD
Need["业务需要 AI agent"] --> Simple{"默认 Copilot 入口能解决?"}
Simple -->|是| Default["IDE / CLI / Cloud Agent"]
Simple -->|否| SDK["Copilot SDK"]
SDK --> Session["Session"]
SDK --> Tools["Tools / MCP"]
SDK --> Agents["Custom agents"]
SDK --> Hooks["Hooks"]
SDK --> Trace["OpenTelemetry"]
Agents --> Sub["Sub-agent delegation"]
Hooks --> Control["权限 / 审计 / 错误处理"]
style SDK fill:#dbeafe,stroke:#2563eb,stroke-width:2px
style Hooks fill:#fef3c7,stroke:#d97706,stroke-width:2px
style Trace fill:#dcfce7,stroke:#16a34a,stroke-width:2px2. 本组页面
Copilot SDK 入门
理解 public preview、CLI 认证、CopilotClient、session 和 streaming。
自定义 Agent
用 customAgents 定义专业 agent，并理解 sub-agent delegation。
SDK Hooks
用 hooks 做权限、审计、上下文注入和错误处理。
可观测性
用 OpenTelemetry、trace context 和 tool spans 观察 agent 行为。
3. 什么时候值得上 SDK
适合：
- 把 Copilot 嵌进自己的产品或内部平台。
- 控制工具、权限、事件、hooks 和 trace。
- 构建专业 agent，而不是只写 prompt。
- 把 agent 行为接入审计、监控和业务日志。
暂时不要：
- 只是让 Copilot 改一个仓库。
- 只是团队内部多写几条规则。
- 没有 owner、日志、权限边界和回滚。
- 还没有证明默认 Copilot 入口不够用。
4. 推荐落地顺序
- 先用 IDE Agent mode 或 Copilot CLI 跑通流程。
- 再把稳定重复任务抽象成 SDK session。
- 注册最小工具集，不要先接生产写接口。
- 用 hooks 限制工具和记录事件。
- 接 OpenTelemetry，再小范围试点。
- 最后才做 custom agents 和 sub-agent orchestration。
深读：SDK 化会放大工程责任
默认 Copilot 出错时，通常是一个开发者会话的问题。SDK 应用出错时，可能影响用户、队列、工具、内部 API 和成本。
因此 SDK 应用必须按产品工程治理：权限、日志、告警、回滚、版本和成本都要跟上。
本组自检
- 是否证明默认入口不够用？
- 是否知道 SDK 应用会调用哪些工具和外部系统？
- 是否有 hooks 拦截危险工具和记录事件？
- 是否有 trace 可以定位 session、tool call 和失败？
通过标准：SDK 应用不是 demo，而是有权限、观测、试点和回滚的受控 agent。
官方来源
- Getting started with Copilot SDK —— GitHub 官方 SDK quickstart。
- Custom agents and sub-agent orchestration —— GitHub 官方 custom agents 和 sub-agent 流程。
- Quickstart for hooks —— GitHub 官方 SDK hooks。
- OpenTelemetry instrumentation for Copilot SDK —— GitHub 官方可观测性说明。