Copilot Agent SDK Examples (Python)

A lightweight repository demonstrating how to build agent workflows with the GitHub Copilot SDK in Python.

---

About GitHub Copilot SDK

GitHub Copilot SDK (currently in technical preview) is a programmable layer that exposes the same agentic engine powering GitHub Copilot CLI — directly inside your own applications.

Before the SDK existed, building agentic workflows meant wiring your own planner, tool loop, context management, model routing, and permission boundaries from scratch. The Copilot SDK removes that burden by packaging a production-tested execution loop covering planning, tool invocation, state management, and streaming — so you can focus on your application logic rather than orchestration infrastructure.

Think of it as the difference between building a car engine and installing one. The SDK gives you the engine; you decide what the car does.

How it works

The SDK communicates with the Copilot CLI in server mode over JSON-RPC:

Your Application
      ↓
  SDK Client  (Python / Node.js / Go / .NET)
      ↓
  JSON-RPC
      ↓
Copilot CLI  (server mode — planning, tool use, model routing)

Your code creates a CopilotClient, opens a Session, and sends prompts. The Copilot engine handles the planning loop — deciding which tools to call, in what order, and when to return a final result. You define the tools; Copilot decides when and how to use them.

What the SDK provides

• CopilotClient and Session — lifecycle management for the agent runtime and conversation context.
• Tool definitions (types.Tool) — wrap any Python function in SDK metadata to make it callable by the model.
• ToolResult packaging — structure tool outputs for model consumption.
• Permission and hook system — intercept tool calls before/after execution (on_pre_tool_use, on_post_tool_use) to add logging, guardrails, or approval gates.
• Streaming support — receive response chunks incrementally via assistant.message_delta events.
• Multi-model routing — choose different models per session; query available models at runtime.
• Native MCP support — connect MCP servers for standard tooling (file system, Git, web, custom APIs).
• BYOK (Bring Your Own Key) — use your own API keys from OpenAI, Azure AI Foundry, Anthropic, and others instead of a Copilot subscription.

What it's not

The SDK is not a chat interface or a standalone AI service. It's a programmable execution platform — you control the entry point, the tools available, and how results are used. GitHub handles authentication, model management, session state, and the agent planning loop.

⚠️ The SDK is currently in technical preview and may have breaking changes. It is not yet recommended for production use.

Official docs

• github/copilot-sdk — root repository with multi-language SDKs
• Python SDK README — installation, API reference, and examples

---

Key concepts

1. Agent — a model-driven controller that plans and calls tools to complete a goal autonomously.
2. Tool — a Python function wrapped in SDK metadata and made callable from model decisions.
3. RunState — shared state carried across tool calls (e.g., file paths, metadata, transcript text).
4. Session loop — the execution cycle where the agent receives instructions, selects and runs tools, and produces a final result.
5. Hooks — lifecycle callbacks (on_pre_tool_use, on_post_tool_use) for logging, approval gates, or side effects.

---

Repository design

• agents/ — each agent gets its own folder with an independent runtime and output path.
• agents/<agent_name>/agent.py — contains run(...) and core tool definitions.
• agents/<agent_name>/__main__.py — optional CLI entrypoint (python -m agents.<agent_name>).
• agents/<agent_name>/outputs/ — agent-specific output data.
• architecture.md — high-level architecture notes.

---

Agents in this repository

Agent	Purpose	Path	Run command
youtube_summarization	Download YouTube audio, transcribe with Whisper, summarize via Copilot tools	agents/youtube_summarization/	python -m agents.youtube_summarization <youtube_url>

More agents can be added following the same pattern — see How to add your own agent.

---

How to add your own agent

1. Create agents/<your_agent>/.
2. Add agent.py with a run(...) entrypoint and tool definitions.
3. Add __main__.py with CLI glue if needed.
4. Register the agent in agents/README.md and the table above.

---

Get started

python -m venv .venv
source .venv/bin/activate
pip install yt-dlp openai-whisper torch copilot-sdk

Ensure the Copilot CLI is installed and available in your PATH — the SDK requires it to run.

---

Explore the agents folder

Each agent under agents/ is self-contained and demonstrates a different Copilot SDK flow. Start with agents/youtube_summarization/agent.py to see a complete example of tool definition, session setup, and result handling.