1# Copilot SDK Reference
2 
3## Template
4 
5```bash
6azd init --template azure-samples/copilot-sdk-service
7```
8 
9**Architecture:** 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).
10 
11## Documentation
12 
13| Resource | URL |
14|----------|-----|
15| Overview & Getting Started | https://github.com/github/copilot-sdk |
16| Getting Started Guide | https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md |
17| Node.js SDK | https://github.com/github/copilot-sdk/tree/main/nodejs |
18| Python SDK | https://github.com/github/copilot-sdk/tree/main/python |
19| Go SDK | https://github.com/github/copilot-sdk/tree/main/go |
20| .NET SDK | https://github.com/github/copilot-sdk/tree/main/dotnet |
21| Debugging | https://github.com/github/copilot-sdk/blob/main/docs/debugging.md |
22| Compatibility | https://github.com/github/copilot-sdk/blob/main/docs/compatibility.md |
23 
24## Getting Current Examples
25 
26Use `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.
27 
28If the **context7** MCP server is available, it can also be used to query SDK docs:
29 
301. Call `context7-resolve-library-id` with `libraryName: "copilot-sdk"` to find the library ID
312. Call `context7-query-docs` with the resolved ID and a query matching the user's goal
323. Select the most relevant snippets for the user's scenario
33 
34> 💡 **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-mcp` as an entry in their MCP server configuration file.
35 
36## Three Model Paths
37 
38| Path | Config | Auth |
39|------|--------|------|
40| GitHub default | No `model` param | `GITHUB_TOKEN` |
41| GitHub specific | `model: "<name>"` | `GITHUB_TOKEN` |
42| Azure BYOM | `model` + `provider` with `bearerToken` | `DefaultAzureCredential` (local dev) / `ManagedIdentityCredential` (production) |
43 
44**Model discovery:**
45- GitHub models: call `listModels()` on the SDK client
46- Azure deployments: `az cognitiveservices account deployment list`
47 
48Full BYOM config details: [Azure Model Configuration](azure-model-config.md).
49 
50> ⚠️ **Warning:** `model` is **required** when using a provider — SDK throws if missing.
51 
52## Template Customization
53 
54Read `AGENTS.md` FIRST — it lists every source file with its purpose. Then:
55 
561. Adapt routes — update endpoints, system message, and tool definitions
572. Customize the UI — the template UI is just an example
583. Keep template infra — do NOT regenerate Dockerfile, Bicep, or `azure.yaml`
594. If using multi-tool AI sessions, increase `proxy_read_timeout` in `nginx.conf.template` to 300s (default 60s causes 504)
60 
61**Existing project:** See [Existing Project Integration](existing-project-integration.md) for adding Copilot SDK to your codebase.
62 
63## Testing
64 
65| Check | Command |
66|-------|---------|
67| Run locally | `azd app run` — starts API + UI |
68| Health check | `curl -s http://localhost:3000/health` |
69| Test endpoint | `curl -s -X POST http://localhost:3000/api/<endpoint> -H "Content-Type: application/json" -d '{"input":"test"}'` |
70 
71## Errors
72 
73| Error | Fix |
74|-------|-----|
75| `docker info` fails | Install Docker Desktop and start it |
76| `gh auth token` fails | Run `gh auth login` then `gh auth refresh --scopes copilot` |
77| `ECONNREFUSED` on JSON-RPC | Set autoStart or start CLI manually |
78| `Model not available` | Check model name; for BYOM verify provider config |
79| Session hangs | Set a max turns limit or add a hook to break |
80| `504 Gateway Timeout` | Increase `proxy_read_timeout` in `nginx.conf.template` to 300s |
81