Agent SDK reference - Python changedagent-sdk/python
Nearest release: v2.1.287, published under an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 1 Oct 2026 16:55 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 1 Oct 2026 17:07 UTC.
Upstream edited
Recorded here
Lines+33added
Lines−0removed
From line
441
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits39to this page, all time
### `ContextUsageResponse`
The whole hunk
from line 441, old and new numbered
/
from line 441
441441 async def set_model(self, model: str | None = None) -> None
442442 async def rewind_files(self, user_message_id: str) -> None
443443 async def get_mcp_status(self) -> McpStatusResponse
444 async def get_context_usage(self) -> ContextUsageResponse
444445 async def reconnect_mcp_server(self, server_name: str) -> None
445446 async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None
446447 async def stop_task(self, task_id: str) -> None
from line 463
462463| `set_model(model)` | Change the model for the current session. Pass `None` to reset to [Claude Code's default model](/docs/en/model-config) |
463464| `rewind_files(user_message_id)` | Restore files to their state at the specified user message. Requires `enable_file_checkpointing=True`. See [File checkpointing](/docs/en/agent-sdk/file-checkpointing) |
464465| `get_mcp_status()` | Get the status of all configured MCP servers. Returns [`McpStatusResponse`](#mcpstatusresponse) |
466| `get_context_usage()` | Get a breakdown of context window usage by category, skill, and tool. The same data `/context` shows in an interactive session. Returns [`ContextUsageResponse`](#contextusageresponse). To compute the breakdown, Claude Code makes several token-counting API requests that don't appear in the message stream; see [how these requests are handled](#contextusageresponse) |
465467| `reconnect_mcp_server(server_name)` | Retry connecting to an MCP server that failed or was disconnected |
466468| `toggle_mcp_server(server_name, enabled)` | Enable or disable an MCP server mid-session. Disabling a stdio, SSE, or HTTP server removes its tools |
467469| `stop_task(task_id)` | Stop a running background task. A [`TaskNotificationMessage`](#tasknotificationmessage) with status `"stopped"` follows in the message stream |
from line 1447
14451447| `config` | [`McpServerStatusConfig`](#mcpserverstatusconfig) (optional) | Server configuration. Same shape as [`McpServerConfig`](#mcpserverconfig) (stdio, SSE, HTTP, or SDK), plus a `claudeai-proxy` variant for servers connected through claude.ai |
14461448| `scope` | `str` (optional) | Configuration scope |
14471449| `tools` | `list` (optional) | Tools provided by this server, each with `name`, `description`, and `annotations` fields |
1450
1451### `ContextUsageResponse`
1452
1453Response from [`ClaudeSDKClient.get_context_usage()`](#methods). This is the same payload Claude Code renders for the `/context` command in an interactive session, so alongside the token counts it carries display fields such as `color` and `gridRows` that Claude Code uses to draw the `/context` usage grid.
1454
1455Claude Code builds this payload by sending several requests to the [token-counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) API. These requests don't appear in the message stream, so cost tracking that reads the stream won't see them. On the Anthropic API, token counting isn't billed.
1456
1457```python theme={null}
1458class ContextUsageResponse(TypedDict):
1459 categories: list[ContextUsageCategory]
1460 totalTokens: int
1461 maxTokens: int
1462 rawMaxTokens: int
1463 percentage: float
1464 model: str
1465 isAutoCompactEnabled: bool
1466 memoryFiles: list[dict[str, Any]]
1467 mcpTools: list[dict[str, Any]]
1468 agents: list[dict[str, Any]]
1469 gridRows: list[list[dict[str, Any]]]
1470 autoCompactThreshold: NotRequired[int]
1471 deferredBuiltinTools: NotRequired[list[dict[str, Any]]]
1472 systemTools: NotRequired[list[dict[str, Any]]]
1473 systemPromptSections: NotRequired[list[dict[str, Any]]]
1474 slashCommands: NotRequired[dict[str, Any]]
1475 skills: NotRequired[dict[str, Any]] # skill usage with frontmatter breakdown
1476 messageBreakdown: NotRequired[dict[str, Any]] # message tokens by type
1477 apiUsage: NotRequired[dict[str, Any] | None]
1478```
1479
1480Each `ContextUsageCategory` entry carries `name`, `tokens`, `color`, and an optional `isDeferred` flag. `totalTokens` is the session's current context usage, and `maxTokens` is the window that usage is measured against. That window is the model's context window, or the lower auto-compaction window when one applies, and `rawMaxTokens` carries the same value as `maxTokens`. `apiUsage` holds the usage from the latest API response, not a running total for the session. Claude Code leaves the optional `deferredBuiltinTools`, `systemTools`, and `systemPromptSections` keys unset, so expect them to be absent even though the type declares them.
14481481
14491482### `SdkPluginConfig`
14501483
No line in this hunk matches that.