Skip to main content

Update agent

Update an agent configuration; omitted top-level fields keep their values, and supplied objects or arrays replace the whole field.

Endpoint

POST /agents/{agent_id} Returns 200 and the complete updated Agent object. Update uses top-level replacement: omitted fields keep their current values, supplied objects or arrays replace the whole field, and null clears nullable fields. Update is not a recursive JSON Merge Patch; metadata:{"a":"new"} removes old keys that are not in the new object. model can be omitted, but an explicit null returns 400. On conflict, the service rereads and merges the latest value, up to 3 attempts, then returns 500. No public version or ETag conditional-update field is provided. {} does not change business fields and does not guarantee that updated_at changes.

Request body

model string (optional)Model ID, omitted keeps the current value; explicit null returns 400; after a change the model must be available in the current workspace, or the API returns 404 model_not_found. For available models, see Available models.name string / null (optional)Display name, up to 128 characters; null clears itinstructions string / null (optional)Custom instructions, up to 1,048,576 characters; null clears themmetadata object / null (optional)Metadata, string key-value pairs; replaced as a whole, null clears, {} replaces with an empty objectreasoning object / null (optional)Reasoning configuration, replaced as a whole; null clears.
effort string / null (optional)Reasoning effort: none, minimal, low, medium, high, xhigh, maxsummary string / null (optional)Reasoning summary: concise, detailed, auto
text object / null (optional)Text configuration, replaced as a whole; null clears. Only fixed text output is supportedtools array / null (optional)Tool list, replaced as a whole; null clears, [] replaces with an empty list.
name string (required)Function name, must be unique within the agentdescription string / null (required)Function description, can be nullparameters object (required)Function input JSON Schema; must declare type: object
server_label string (required)MCP server label, must be unique within the agenttransport object (required)Transport configuration; see the branches below
type string (required)Transport type, http or stdioserver_url string / null (conditional)MCP server URLheaders object<string,string> / null (optional)Additional HTTP headers; do not put secrets herecommand string (conditional)Command to start the servercwd string (conditional)Working directory; must be an absolute path whose segments are not . or ..args array<string> / null (optional)Command arguments
allowed_tools array<string> / null (optional)Allowed tool names; null means no filterrequired boolean (optional)Whether MCP initialization must succeedconnection_origin string / null (optional)Connection origin, service or environment, defaults to service
type string (required)Tool type, fixed as web_search
multi_agent object / null (optional)Multi-agent configuration, replaced as a whole; null clears, default concurrency is not filled inTool fields: each tool must provide a type. The current supported types are function, mcp, and web_search. Update only saves the configuration; it does not mean the tool can execute.Unknown top-level fields do not produce an error and may be filtered out and recorded; do not assume a field is applied just because the request succeeds.Update validates the patch before looking up the resource. If the patch is invalid and the resource does not exist at the same time, the API can return 400 first.

Request example

curl -sS -X POST "$BASE_URL/agents/agent_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example-agent",
    "metadata": {"purpose": "qa"},
    "reasoning": {"effort": "medium", "summary": "auto"},
    "tools": [{"type": "web_search"}]
  }'

Response fields

Returns the complete updated agent object. Optional fields that were never set 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, stored string key-value pairsmodel stringStored 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 / nullStored custom instructionstools array / nullStored 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": 1794117600,
  "name": "example-agent",
  "metadata": {"purpose": "qa"},
  "model": "qwen3.8-max",
  "reasoning": {"effort": "medium", "summary": "auto"},
  "text": null,
  "instructions": "Answer briefly and include steps when necessary.",
  "tools": [
    {
      "type": "web_search"
    }
  ],
  "multi_agent": null
}

Error codes

Business errors return an error object with type, code, message, and param. Common errors:
HTTP statusError type / codeSolution
400invalid_request_error / invalid_request_errorFix field types, enums, lengths, and cross-field constraints as described; omit model instead of sending null
400invalid_request_error / string_above_max_lengthShorten instructions to 1,048,576 characters or fewer
401authentication_error / invalid_api_keySend a valid Authorization: Bearer $DASHSCOPE_API_KEY header
404invalid_request_error / model_not_foundUse a model ID that is available in the current workspace
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