Copilot SDK Reference
Template
azd init --template azure-samples/copilot-sdk-serviceArchitecture: API (Express/TS) + Web UI (React/Vite), deployed as 2 Container Apps. Chat endpoint streams token-level deltas via assistant.message_delta SSE events. Azure BYOM gets a fresh bearer token per-request (no expiry issues).
Documentation
| Resource | URL |
|---|---|
| Overview & Getting Started | https://github.com/github/copilot-sdk |
| Getting Started Guide | https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md |
| Node.js SDK | https://github.com/github/copilot-sdk/tree/main/nodejs |
| Python SDK | https://github.com/github/copilot-sdk/tree/main/python |
| Go SDK | https://github.com/github/copilot-sdk/tree/main/go |
| .NET SDK | https://github.com/github/copilot-sdk/tree/main/dotnet |
| Debugging | https://github.com/github/copilot-sdk/blob/main/docs/debugging.md |
| Compatibility | https://github.com/github/copilot-sdk/blob/main/docs/compatibility.md |
Getting Current Examples
Use github-mcp-server-get_file_contents with owner: "github", repo: "copilot-sdk" to read files directly from the repo and get current SDK documentation and code examples.
If the context7 MCP server is available, it can also be used to query SDK docs:
- Call
context7-resolve-library-idwithlibraryName: "copilot-sdk"to find the library ID - Call
context7-query-docswith the resolved ID and a query matching the user's goal - Select the most relevant snippets for the user's scenario
💡 Tip: If context7 is not installed, instruct the user to add it. For a quick one-off use:
npx -y @upstash/context7-mcp@latest. To persist it, add@upstash/context7-mcpas an entry in their MCP server configuration file.
Three Model Paths
| Path | Config | Auth |
|---|---|---|
| GitHub default | No model param | GITHUB_TOKEN |
| GitHub specific | model: "<name>" | GITHUB_TOKEN |
| Azure BYOM | model + provider with bearerToken | DefaultAzureCredential (local dev) / ManagedIdentityCredential (production) |
Model discovery:
- GitHub models: call
listModels()on the SDK client - Azure deployments:
az cognitiveservices account deployment list
Full BYOM config details: Azure Model Configuration.
⚠️ Warning:
modelis required when using a provider — SDK throws if missing.
Template Customization
Read AGENTS.md FIRST — it lists every source file with its purpose. Then:
- Adapt routes — update endpoints, system message, and tool definitions
- Customize the UI — the template UI is just an example
- Keep template infra — do NOT regenerate Dockerfile, Bicep, or
azure.yaml - If using multi-tool AI sessions, increase
proxy_read_timeoutinnginx.conf.templateto 300s (default 60s causes 504)
Existing project: See Existing Project Integration for adding Copilot SDK to your codebase.
Testing
| Check | Command |
|---|---|
| Run locally | azd app run — starts API + UI |
| Health check | curl -s http://localhost:3000/health |
| Test endpoint | curl -s -X POST http://localhost:3000/api/<endpoint> -H "Content-Type: application/json" -d '{"input":"test"}' |
Errors
| Error | Fix |
|---|---|
docker info fails | Install Docker Desktop and start it |
gh auth token fails | Run gh auth login then gh auth refresh --scopes copilot |
ECONNREFUSED on JSON-RPC | Set autoStart or start CLI manually |
Model not available | Check model name; for BYOM verify provider config |
| Session hangs | Set a max turns limit or add a hook to break |
504 Gateway Timeout | Increase proxy_read_timeout in nginx.conf.template to 300s |