---
title: "SDK 与自定义 Agent"
description: "按 GitHub 官方 SDK 文档梳理 Copilot SDK、custom agents、hooks 和 OpenTelemetry 可观测性。"
verifiedAt: "2026-05-06"
---

Copilot SDK 不是普通 API wrapper（API 包装层）。它让你把 Copilot 变成应用里的 agent runtime（代理运行时）：创建 session、注册工具、监听事件、定义 custom agents、插入 hooks、接入 OpenTelemetry。

这一组解决一个判断：什么时候继续用 IDE Chat / Agent mode 就够，什么时候应该做成 SDK 应用或自定义 agent。

> [!WARNING]
> GitHub 官方文档标注 Copilot SDK 目前处于 public preview。生产化前必须保留版本、日志、回滚和权限边界。

## 1. 能力地图

```mermaid
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:2px
```

## 2. 本组页面

<Cards>
  <Card title="Copilot SDK 入门" description="理解 public preview、CLI 认证、CopilotClient、session 和 streaming。" href="/docs/github-copilot/official/09-sdk-and-custom-agents/sdk-getting-started" />
  <Card title="自定义 Agent" description="用 customAgents 定义专业 agent，并理解 sub-agent delegation。" href="/docs/github-copilot/official/09-sdk-and-custom-agents/custom-agents" />
  <Card title="SDK Hooks" description="用 hooks 做权限、审计、上下文注入和错误处理。" href="/docs/github-copilot/official/09-sdk-and-custom-agents/sdk-hooks" />
  <Card title="可观测性" description="用 OpenTelemetry、trace context 和 tool spans 观察 agent 行为。" href="/docs/github-copilot/official/09-sdk-and-custom-agents/observability" />
</Cards>

## 3. 什么时候值得上 SDK

适合：

- 把 Copilot 嵌进自己的产品或内部平台。
- 控制工具、权限、事件、hooks 和 trace。
- 构建专业 agent，而不是只写 prompt。
- 把 agent 行为接入审计、监控和业务日志。

暂时不要：

- 只是让 Copilot 改一个仓库。
- 只是团队内部多写几条规则。
- 没有 owner、日志、权限边界和回滚。
- 还没有证明默认 Copilot 入口不够用。

## 4. 推荐落地顺序

1. 先用 IDE Agent mode 或 Copilot CLI 跑通流程。
2. 再把稳定重复任务抽象成 SDK session。
3. 注册最小工具集，不要先接生产写接口。
4. 用 hooks 限制工具和记录事件。
5. 接 OpenTelemetry，再小范围试点。
6. 最后才做 custom agents 和 sub-agent orchestration。

<details>
<summary>深读：SDK 化会放大工程责任</summary>

默认 Copilot 出错时，通常是一个开发者会话的问题。SDK 应用出错时，可能影响用户、队列、工具、内部 API 和成本。

因此 SDK 应用必须按产品工程治理：权限、日志、告警、回滚、版本和成本都要跟上。
</details>

## 本组自检

1. 是否证明默认入口不够用？
2. 是否知道 SDK 应用会调用哪些工具和外部系统？
3. 是否有 hooks 拦截危险工具和记录事件？
4. 是否有 trace 可以定位 session、tool call 和失败？

通过标准：SDK 应用不是 demo，而是有权限、观测、试点和回滚的受控 agent。

## 官方来源

- [Getting started with Copilot SDK](https://docs.github.com/en/copilot/how-tos/copilot-sdk/sdk-getting-started) —— GitHub 官方 SDK quickstart。
- [Custom agents and sub-agent orchestration](https://docs.github.com/en/copilot/how-tos/copilot-sdk/use-copilot-sdk/custom-agents) —— GitHub 官方 custom agents 和 sub-agent 流程。
- [Quickstart for hooks](https://docs.github.com/en/copilot/how-tos/copilot-sdk/use-hooks/quickstart) —— GitHub 官方 SDK hooks。
- [OpenTelemetry instrumentation for Copilot SDK](https://docs.github.com/en/copilot/how-tos/copilot-sdk/observability/opentelemetry) —— GitHub 官方可观测性说明。

## 接下来去哪

<Cards>
  <Card title="Copilot SDK 入门" description="先跑通最小 session。" href="/docs/github-copilot/official/09-sdk-and-custom-agents/sdk-getting-started" />
  <Card title="实战 Playbooks" description="SDK 之前也要会判断真实任务是否值得产品化。" href="/docs/github-copilot/official/10-practical-playbooks" />
</Cards>
