Skip to main content

Retrieve agent

Return the complete agent configuration for an agent ID.

Endpoint

GET /agents/{agent_id} Returns 200 and the complete Agent object.

Path parameters

agent_id string (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

curl -sS "$BASE_URL/agents/agent_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1"

Response fields

Omitted optional fields can be null.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.
effort string / nullReasoning effort: none, minimal, low, medium, high, xhigh, maxsummary string / nullReasoning summary: concise, detailed, auto
text object / nullText output configuration.
format objectOutput format.
type string / nullOutput format type, fixed as text
verbosity string / nullOutput verbosity, low, medium, high
instructions string / nullSaved custom instructionstools array / nullSaved tool configuration; each branch returns only its own fields
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 configuration
multi_agent object / nullSubagent configuration.
enabled booleanWhether subagent tools are enabledmax_concurrent_subagents integer / nullMaximum number of concurrent subagents; no default is applied

Response example

{
  "id": "agent_xxx",
  "object": "agent",
  "created_at": 1794117521,
  "updated_at": 1794117521,
  "name": "quickstart-agent",
  "metadata": null,
  "model": "qwen3.8-max",
  "reasoning": null,
  "text": null,
  "instructions": "Answer briefly.",
  "tools": null,
  "multi_agent": null
}

Error codes

Business errors return an error object with type, code, message, and param. Common errors:
HTTP statusError type / codeSolution
401authentication_error / invalid_api_keySend a valid Authorization: Bearer $DASHSCOPE_API_KEY header
404not_found_error / not_found_errorUse an agent ID that exists and has not been deleted in the current workspace
500server_error / server_errorRetry later. If it keeps failing, submit a ticket with x-request-id