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 bodymodelstring (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.
Properties effort string / null (optional)Reasoning effort: none, minimal, low, medium, high, xhigh, maxsummary string / null (optional)Reasoning summary: concise, detailed, autoobject / 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.
Properties
function 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
mcp server_label string (required)MCP server label, must be unique within the agenttransport object (required)Transport configuration; see the branches below
Properties 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 argumentsarray<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
web_search type string (required)Tool type, fixed as web_searchobject / 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 |
Response fieldsReturns the complete updated agent object. Optional fields that were never set 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, stored string key-value pairsmodel stringStored 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 / nullStored custom instructionstools array / nullStored 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 |
|---|---|---|
400 | invalid_request_error / invalid_request_error | Fix field types, enums, lengths, and cross-field constraints as described; omit model instead of sending null |
400 | invalid_request_error / string_above_max_length | Shorten instructions to 1,048,576 characters or fewer |
401 | authentication_error / invalid_api_key | Send a valid Authorization: Bearer $DASHSCOPE_API_KEY header |
404 | invalid_request_error / model_not_found | Use a model ID that is available in the current workspace |
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 |