1# Model Configuration
2 
3Three model paths for the Copilot SDK. Each session needs different configuration.
4 
5## Path 1: GitHub Default
6 
7No configuration needed. SDK uses the default model.
8 
9```typescript
10const session = await client.createSession({});
11// or simply: client.createSession()
12```
13 
14Best for: quick prototyping, no model preference.
15 
16## Path 2: GitHub Specific Model
17 
18Specify a model name. Discover available models with `listModels()`.
19 
20```typescript
21const models = await client.listModels();
22// Pick from available models
23const session = await client.createSession({
24  model: "o4-mini",
25});
26```
27 
28## Path 3: Azure BYOM (Bring Your Own Model)
29 
30Use your own Azure AI deployment. For local development use `DefaultAzureCredential`; for production use `ManagedIdentityCredential` — see [auth-best-practices.md](auth-best-practices.md).
31 
32> ⚠️ **Warning:** The Copilot SDK encrypts prompt content. Only models that support decrypting encrypted content work with BYOM. Using unsupported models returns "400 Encrypted content is not supported" or silently times out.
33 
34### Supported Models
35 
36| Family | Models |
37|--------|--------|
38| **o-series** | o3, o3-mini, o4-mini (cheapest) |
39| **gpt-5 family** | gpt-5, gpt-5-mini, gpt-5.1, gpt-5.1-mini, gpt-5.1-nano, gpt-5.2-codex, codex-mini |
40| ❌ **NOT supported** | gpt-4o, gpt-4.1, gpt-4.1-nano, and other non-o/non-gpt-5 models |
41 
42### Required API Settings
43 
44| Setting | Value | Notes |
45|---------|-------|-------|
46| `wireApi` | `"completions"` | ⚠️ Do NOT use `"responses"` — breaks multi-turn tool calls (`store: false` causes 400) |
47| `azure.apiVersion` | `"2025-04-01-preview"` or later | ⚠️ Must be nested under `azure:`, NOT top-level |
48 
49### Provider Config
50 
51| Endpoint type | `type` | `baseUrl` pattern |
52|---|---|---|
53| Azure OpenAI | `azure` | `https://<resource>.openai.azure.com` |
54| Azure AI Foundry | `openai` | `https://<resource>.services.ai.azure.com/api/projects/<project>/openai/v1/` |
55 
56### Code Pattern
57 
58> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](auth-best-practices.md) for production patterns.
59 
60```typescript
61import { DefaultAzureCredential } from "@azure/identity";
62 
63const credential = new DefaultAzureCredential();
64const { token } = await credential.getToken("https://cognitiveservices.azure.com/.default");
65 
66const session = await client.createSession({
67    model: process.env.MODEL_NAME || "o4-mini",
68    provider: {
69        type: "azure",
70        baseUrl: process.env.AZURE_OPENAI_ENDPOINT,
71        bearerToken: token,
72        wireApi: "completions",
73        azure: { apiVersion: "2025-04-01-preview" },
74    },
75});
76```
77 
78### Environment Variables
79 
80| Variable | Value | Required |
81|----------|-------|----------|
82| `AZURE_OPENAI_ENDPOINT` | `https://<resource>.openai.azure.com` | Yes |
83| `MODEL_NAME` | Model deployment name | Yes |
84| `AZURE_CLIENT_ID` | Managed identity client ID | Yes (Container Apps with user-assigned MI) |
85 
86### Token Refresh
87 
88> ⚠️ **Warning:** `bearerToken` is static — no auto-refresh.
89 
90- Tokens valid ~1 hour
91- **Production**: get fresh token per request
92- Long-running sessions fail after expiry
93 
94### Discovering Azure Deployments
95 
96`listModels()` returns GitHub models only. For Azure deployments:
97 
98```bash
99az cognitiveservices account deployment list --name <resource> --resource-group <rg>
100```
101 
102## Template Environment Variables
103 
104The template uses env vars for model path selection:
105 
106| Variable | Values | Effect |
107|----------|--------|--------|
108| `MODEL_PROVIDER` | unset or `azure` | Selects GitHub or Azure BYOM |
109| `MODEL_NAME` | model/deployment name | Selects specific model |
110| `AZURE_OPENAI_ENDPOINT` | Azure endpoint URL | Required for BYOM |
111 
112## Errors
113 
114| Error | Cause | Fix |
115|-------|-------|-----|
116| `400 Encrypted content is not supported` | Model doesn't support SDK encryption | Use o-series or gpt-5 family only |
117| `400` with tool calls / multi-turn | `wireApi: "responses"` with `store: false` | Use `wireApi: "completions"` instead |
118| `CAPIError: 404 Resource not found` | `apiVersion` at top level instead of nested | Use `azure: { apiVersion: "..." }` |
119| Silent timeout | Unsupported model (e.g., gpt-4o, gpt-4.1) | Switch to o4-mini or gpt-5 family |
120| `model is required` | Missing `model` in BYOM config | Set `MODEL_NAME` env var |
121| `401 Unauthorized` | Token expired or wrong scope | Refresh via `DefaultAzureCredential` |
122| `404 Not Found` | Wrong endpoint or deployment name | Verify URL and deployment exists |
123| `500` in Container Apps | Missing `AZURE_CLIENT_ID` env var | Set to managed identity client ID in Bicep |
124