Repository Public
1---2title: Get Agent3url: https://platform.claude.com/docs/en/api/beta/agents/retrieve4---56# Get Agent78**GET** `/v1/agents/{agent_id}`910Get Agent1112## Path parameters1314- `agent_id: string`1516## Query parameters1718- `version: optional number`1920 Agent version. Omit for the most recent version. Must be at least 1 if specified.2122 format: int322324## Headers2526- `"anthropic-beta": optional array of AnthropicBeta`2728 Optional header to specify the beta version(s) you want to use.2930 - `string`3132 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 43 more`3334 - `"message-batches-2024-09-24"`3536 - `"prompt-caching-2024-07-31"`3738 - `"computer-use-2024-10-22"`3940 - `"computer-use-2025-01-24"`4142 - `"pdfs-2024-09-25"`4344 - `"token-counting-2024-11-01"`4546 - `"token-efficient-tools-2025-02-19"`4748 - `"output-128k-2025-02-19"`4950 - `"files-api-2025-04-14"`5152 - `"mcp-client-2025-04-04"`5354 - `"mcp-client-2025-11-20"`5556 - `"dev-full-thinking-2025-05-14"`5758 - `"interleaved-thinking-2025-05-14"`5960 - `"code-execution-2025-05-22"`6162 - `"extended-cache-ttl-2025-04-11"`6364 - `"context-1m-2025-08-07"`6566 - `"context-management-2025-06-27"`6768 - `"model-context-window-exceeded-2025-08-26"`6970 - `"skills-2025-10-02"`7172 - `"fast-mode-2026-02-01"`7374 - `"output-300k-2026-03-24"`7576 - `"user-profiles-2026-03-24"`7778 - `"user-profiles-2026-08-18"`7980 - `"user-profiles-2026-09-04"`8182 - `"advisor-tool-2026-03-01"`8384 - `"managed-agents-2026-04-01"`8586 - `"cache-diagnosis-2026-04-07"`8788 - `"dreaming-2026-04-21"`8990 - `"thinking-token-count-2026-05-13"`9192 - `"server-side-fallback-2026-06-01"`9394 - `"server-side-fallback-2026-07-01"`9596 - `"fallback-credit-2026-06-01"`9798 - `"fallback-credit-2026-07-01"`99100 - `"agent-memory-2026-07-22"`101102 - `"mid-conversation-tool-changes-2026-07-01"`103104 - `"compact-2026-01-12"`105106 - `"computer-use-2025-11-24"`107108 - `"mcp-tunnels-2026-06-22"`109110 - `"structured-outputs-2025-11-13"`111112 - `"task-budgets-2026-03-13"`113114 - `"thinking-display-updates-2026-08-18"`115116 - `"ce-user-management-2026-07-13"`117118 - `"mid-conversation-output-config-2026-07-01"`119120 - `"thinking-binding-controls-2026-08-01"`121122 - `"mid-conversation-system-clear-at-2026-08-21"`123124 - `"compact-2026-09-04"`125126- `"anthropic-workspace-id": optional string`127128## Returns129130- `BetaManagedAgentsAgent object`131132 A Managed Agents `agent`.133134 - `type: "agent"`135136 - `id: string`137138 - `archived_at: string or null`139140 A timestamp in RFC 3339 format141142 format: date-time143144 - `created_at: string`145146 A timestamp in RFC 3339 format147148 format: date-time149150 - `description: string or null`151152 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`153154 - `type: "url"`155156 - `name: string`157158 - `url: string`159160 - `metadata: map[string]`161162 - `model: BetaManagedAgentsModelConfig`163164 Model identifier and configuration.165166 - `id: BetaManagedAgentsModel`167168 The model that will power your agent.169170 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.171172 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`173174 The model that will power your agent.175176 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.177178 - `"claude-fable-5-1"`179180 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows181182 - `"claude-sonnet-5"`183184 High-performance model for coding and agents185186 - `"claude-fable-5"`187188 Next generation of intelligence for the hardest knowledge work and coding problems189190 - `"claude-opus-5"`191192 Powerful intelligence for long-running agents and coding193194 - `"claude-opus-4-8"`195196 Powerful intelligence for long-running agents and coding197198 - `"claude-opus-4-7"`199200 Powerful intelligence for long-running agents and coding201202 - `"claude-opus-4-6"`203204 Powerful intelligence for long-running agents and coding205206 - `"claude-sonnet-4-6"`207208 Best combination of speed and intelligence209210 - `"claude-haiku-4-5"`211212 Fastest model with near-frontier intelligence213214 - `"claude-haiku-4-5-20251001"`215216 Fastest model with near-frontier intelligence217218 - `"claude-opus-4-5"`219220 Powerful intelligence for long-running agents and coding221222 - `"claude-opus-4-5-20251101"`223224 Powerful intelligence for long-running agents and coding225226 - `"claude-sonnet-4-5"`227228 High-performance model for agents and coding229230 - `"claude-sonnet-4-5-20250929"`231232 High-performance model for agents and coding233234 - `string`235236 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`237238 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.239240 - `BetaManagedAgentsEffortLow object`241242 Low effort. Favors latency over reasoning depth.243244 - `type: "low"`245246 - `BetaManagedAgentsEffortMedium object`247248 Medium effort. Balances latency and reasoning depth.249250 - `type: "medium"`251252 - `BetaManagedAgentsEffortHigh object`253254 High effort. Favors reasoning depth.255256 - `type: "high"`257258 - `BetaManagedAgentsEffortXhigh object`259260 Extra-high effort. Not all models accept this level.261262 - `type: "xhigh"`263264 - `BetaManagedAgentsEffortMax object`265266 Maximum effort. Favors reasoning depth over latency.267268 - `type: "max"`269270 - `inference_geo: optional string`271272 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.273274 - `speed: optional "standard" or "fast"`275276 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.277278 - `"standard"`279280 - `"fast"`281282 - `multiagent: BetaManagedAgentsMultiagent or null`283284 Resolved coordinator topology with a concrete agent roster.285286 - `type: "coordinator"`287288 - `agents: array of BetaManagedAgentsAgentReference or BetaManagedAgentsAdvisor`289290 Agents the coordinator may spawn as session threads, each resolved to a specific version.291292 - `BetaManagedAgentsAgentReference object`293294 A resolved agent reference with a concrete version.295296 - `type: "agent"`297298 - `id: string`299300 - `version: number`301302 format: int32303304 - `BetaManagedAgentsAdvisor object`305306 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.307308 - `type: "advisor"`309310 - `model: string`311312 The advisor model id.313314 - `name: string`315316 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`317318 - `BetaManagedAgentsAnthropicSkill object`319320 A resolved Anthropic-managed skill.321322 - `type: "anthropic"`323324 - `skill_id: string`325326 - `version: string`327328 - `BetaManagedAgentsCustomSkill object`329330 A resolved user-created custom skill.331332 - `type: "custom"`333334 - `skill_id: string`335336 - `version: string`337338 - `system: string or null`339340 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`341342 - `BetaManagedAgentsAgentToolset20260401 object`343344 - `type: "agent_toolset_20260401"`345346 - `configs: array of BetaManagedAgentsAgentToolConfig`347348 - `BetaManagedAgentsBashToolConfig object`349350 Configuration for the bash tool.351352 - `type: "bash"`353354 - `enabled: boolean`355356 - `name: "bash"`357358 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`359360 Permission policy for tool execution.361362 - `BetaManagedAgentsAlwaysAllowPolicy object`363364 Tool calls are automatically approved without user confirmation.365366 - `type: "always_allow"`367368 - `BetaManagedAgentsAlwaysAskPolicy object`369370 Tool calls require user confirmation before execution.371372 - `type: "always_ask"`373374 - `BetaManagedAgentsAutoPolicy object`375376 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.377378 - `type: "auto"`379380 - `BetaManagedAgentsEditToolConfig object`381382 Configuration for the edit tool.383384 - `type: "edit"`385386 - `enabled: boolean`387388 - `name: "edit"`389390 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`391392 Permission policy for tool execution.393394 - `BetaManagedAgentsAlwaysAllowPolicy object`395396 Tool calls are automatically approved without user confirmation.397398 - `BetaManagedAgentsAlwaysAskPolicy object`399400 Tool calls require user confirmation before execution.401402 - `BetaManagedAgentsAutoPolicy object`403404 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.405406 - `BetaManagedAgentsReadToolConfig object`407408 Configuration for the read tool.409410 - `type: "read"`411412 - `enabled: boolean`413414 - `name: "read"`415416 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`417418 Permission policy for tool execution.419420 - `BetaManagedAgentsAlwaysAllowPolicy object`421422 Tool calls are automatically approved without user confirmation.423424 - `BetaManagedAgentsAlwaysAskPolicy object`425426 Tool calls require user confirmation before execution.427428 - `BetaManagedAgentsAutoPolicy object`429430 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.431432 - `BetaManagedAgentsWriteToolConfig object`433434 Configuration for the write tool.435436 - `type: "write"`437438 - `enabled: boolean`439440 - `name: "write"`441442 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`443444 Permission policy for tool execution.445446 - `BetaManagedAgentsAlwaysAllowPolicy object`447448 Tool calls are automatically approved without user confirmation.449450 - `BetaManagedAgentsAlwaysAskPolicy object`451452 Tool calls require user confirmation before execution.453454 - `BetaManagedAgentsAutoPolicy object`455456 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.457458 - `BetaManagedAgentsGlobToolConfig object`459460 Configuration for the glob tool.461462 - `type: "glob"`463464 - `enabled: boolean`465466 - `name: "glob"`467468 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`469470 Permission policy for tool execution.471472 - `BetaManagedAgentsAlwaysAllowPolicy object`473474 Tool calls are automatically approved without user confirmation.475476 - `BetaManagedAgentsAlwaysAskPolicy object`477478 Tool calls require user confirmation before execution.479480 - `BetaManagedAgentsAutoPolicy object`481482 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.483484 - `BetaManagedAgentsGrepToolConfig object`485486 Configuration for the grep tool.487488 - `type: "grep"`489490 - `enabled: boolean`491492 - `name: "grep"`493494 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`495496 Permission policy for tool execution.497498 - `BetaManagedAgentsAlwaysAllowPolicy object`499500 Tool calls are automatically approved without user confirmation.501502 - `BetaManagedAgentsAlwaysAskPolicy object`503504 Tool calls require user confirmation before execution.505506 - `BetaManagedAgentsAutoPolicy object`507508 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.509510 - `BetaManagedAgentsWebFetchToolConfig object`511512 Configuration for the web_fetch tool.513514 - `type: "web_fetch"`515516 - `enabled: boolean`517518 - `name: "web_fetch"`519520 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`521522 Permission policy for tool execution.523524 - `BetaManagedAgentsAlwaysAllowPolicy object`525526 Tool calls are automatically approved without user confirmation.527528 - `BetaManagedAgentsAlwaysAskPolicy object`529530 Tool calls require user confirmation before execution.531532 - `BetaManagedAgentsAutoPolicy object`533534 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.535536 - `allowed_domains: optional array of string`537538 - `blocked_domains: optional array of string`539540 - `max_content_tokens: optional number or null`541542 format: int32543544 - `BetaManagedAgentsWebSearchToolConfig object`545546 Configuration for the web_search tool.547548 - `type: "web_search"`549550 - `enabled: boolean`551552 - `name: "web_search"`553554 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`555556 Permission policy for tool execution.557558 - `BetaManagedAgentsAlwaysAllowPolicy object`559560 Tool calls are automatically approved without user confirmation.561562 - `BetaManagedAgentsAlwaysAskPolicy object`563564 Tool calls require user confirmation before execution.565566 - `BetaManagedAgentsAutoPolicy object`567568 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.569570 - `allowed_domains: optional array of string`571572 - `blocked_domains: optional array of string`573574 - `user_location: optional BetaManagedAgentsUserLocation or null`575576 Approximate user location for search result localization.577578 - `type: "approximate"`579580 Location precision. Only "approximate" is supported.581582 - `city: optional string or null`583584 City name.585586 minLength: 1, maxLength: 255587588 - `country: optional string or null`589590 Two-letter ISO 3166-1 country code, uppercase.591592 - `region: optional string or null`593594 Region or state name.595596 minLength: 1, maxLength: 255597598 - `timezone: optional string or null`599600 IANA timezone identifier, e.g. "America/Los_Angeles".601602 minLength: 1, maxLength: 255603604 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`605606 Resolved default configuration for agent tools.607608 - `enabled: boolean`609610 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`611612 Permission policy for tool execution.613614 - `BetaManagedAgentsAlwaysAllowPolicy object`615616 Tool calls are automatically approved without user confirmation.617618 - `BetaManagedAgentsAlwaysAskPolicy object`619620 Tool calls require user confirmation before execution.621622 - `BetaManagedAgentsAutoPolicy object`623624 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.625626 - `BetaManagedAgentsMCPToolset object`627628 - `type: "mcp_toolset"`629630 - `configs: array of BetaManagedAgentsMCPToolConfig`631632 - `enabled: boolean`633634 - `name: string`635636 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`637638 Permission policy for tool execution.639640 - `BetaManagedAgentsAlwaysAllowPolicy object`641642 Tool calls are automatically approved without user confirmation.643644 - `BetaManagedAgentsAlwaysAskPolicy object`645646 Tool calls require user confirmation before execution.647648 - `BetaManagedAgentsAutoPolicy object`649650 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.651652 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`653654 Resolved default configuration for all tools from an MCP server.655656 - `enabled: boolean`657658 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`659660 Permission policy for tool execution.661662 - `BetaManagedAgentsAlwaysAllowPolicy object`663664 Tool calls are automatically approved without user confirmation.665666 - `BetaManagedAgentsAlwaysAskPolicy object`667668 Tool calls require user confirmation before execution.669670 - `BetaManagedAgentsAutoPolicy object`671672 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.673674 - `mcp_server_name: string`675676 - `BetaManagedAgentsCustomTool object`677678 A custom tool as returned in API responses.679680 - `type: "custom"`681682 - `description: string`683684 - `input_schema: BetaManagedAgentsCustomToolInputSchema`685686 JSON Schema for custom tool input parameters.687688 - `type: "object"`689690 - `properties: optional map[unknown] or null`691692 - `required: optional array of string or null`693694 - `name: string`695696 - `updated_at: string`697698 A timestamp in RFC 3339 format699700 format: date-time701702 - `version: number`703704 The agent's current version. Starts at 1 and increments when the agent is modified.705706 format: int32707708## Example709710```bash711curl https://api.anthropic.com/v1/agents/$AGENT_ID \712 -H 'anthropic-version: 2023-06-01' \713 -H 'anthropic-beta: managed-agents-2026-04-01' \714 -H "X-Api-Key: $ANTHROPIC_API_KEY"715```716717### Response (200)718719```json720{721 "id": "agent_011CZkYpogX7uDKUyvBTophP",722 "archived_at": null,723 "created_at": "2026-03-15T10:00:00Z",724 "description": "A general-purpose starter agent.",725 "mcp_servers": [726 {727 "name": "example-mcp",728 "type": "url",729 "url": "https://example-server.modelcontextprotocol.io/sse"730 }731 ],732 "metadata": {733 "foo": "bar"734 },735 "model": {736 "id": "claude-opus-5",737 "effort": {738 "type": "low"739 },740 "inference_geo": "inference_geo",741 "speed": "standard"742 },743 "multiagent": {744 "agents": [745 {746 "id": "agent_011CZkYqphY8vELVzwCUpqiQ",747 "type": "agent",748 "version": 1749 }750 ],751 "type": "coordinator"752 },753 "name": "My First Agent",754 "skills": [755 {756 "skill_id": "xlsx",757 "type": "anthropic",758 "version": "1"759 },760 {761 "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",762 "type": "custom",763 "version": "2"764 }765 ],766 "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",767 "tools": [768 {769 "configs": [770 {771 "enabled": true,772 "name": "bash",773 "permission_policy": {774 "type": "always_allow"775 },776 "type": "bash"777 }778 ],779 "default_config": {780 "enabled": true,781 "permission_policy": {782 "type": "always_ask"783 }784 },785 "type": "agent_toolset_20260401"786 }787 ],788 "type": "agent",789 "updated_at": "2026-03-15T10:00:00Z",790 "version": 1791}792```793