Return the complete agent configuration for an agent ID.
Endpoint
GET /agents/{agent_id}
Returns 200 and the complete Agent object.
Path parametersagent_idstring (required)Agent ID. Treat it as an opaque stringThis endpoint has no query parameters. If agent_id is malformed, does not exist, has been deleted, or belongs to another workspace, the API returns 404. | Request example |
Response fieldsOmitted optional fields can benull.id stringAgent ID. Treat it as an opaque stringobject stringAgent object type, fixed as agentcreated_at integerCreation time as a Unix timestamp in secondsupdated_at integerLast modification time as a Unix timestamp in seconds; not a version numbername string / nullDisplay namemetadata object / nullMetadata, saved string key-value pairsmodel stringSaved model IDreasoning object / nullReasoning configuration. Either subfield can be null.
Properties effort string / nullReasoning effort: none, minimal, low, medium, high, xhigh, maxsummary string / nullReasoning summary: concise, detailed, autoobject / nullText output configuration.
Properties format objectOutput format.
Properties type string / nullOutput format type, fixed as textstring / nullOutput verbosity, low, medium, highstring / nullSaved custom instructionstools array / nullSaved tool configuration; each branch returns only its own fields
Properties function objectFunction tool configuration; returns name, description, and parametersmcp objectMCP tool configuration; returns server_label, transport, allowed_tools, required, and connection_origin; transport is http or stdioweb_search objectWeb search tool configuration; returns type and the saved configurationobject / nullSubagent configuration.
Properties enabled booleanWhether subagent tools are enabledmax_concurrent_subagents integer / nullMaximum number of concurrent subagents; no default is applied | Response example |
Error codes
Business errors return an error object with type, code, message, and param. Common errors:
| HTTP status | Error type / code | Solution |
|---|---|---|
401 | authentication_error / invalid_api_key | Send a valid Authorization: Bearer $DASHSCOPE_API_KEY header |
404 | not_found_error / not_found_error | Use an agent ID that exists and has not been deleted in the current workspace |
500 | server_error / server_error | Retry later. If it keeps failing, submit a ticket with x-request-id |