DigitalOcean API (unofficial showcase)
PUT/v2/gen-ai/agents/{uuid}

Update an agent configuration

Replaces the configuration of an existing agent. Supply the fields you want to change, such as name, instruction, or model_uuid; all listed body fields are optional. The response includes the updated agent object.

1 parameter · 27 body fields
uuidstringrequired
The unique identifier of the agent to update.

Optional agent configuration fields to modify; omit fields you do not want to change.

agent_log_insights_enabledbooleanoptional
Whether to enable agent log insights.
allowed_domainsarray<string>optional
Optional list of allowed domains for the chatbot - Must use fully qualified domain name (FQDN) such as https://example.com
anthropic_key_uuidstringoptional
Optional anthropic key uuid for use with anthropic models
clear_mcp_serversbooleanoptional
When true, removes all MCP servers from the agent. Use this instead of sending an empty mcp_servers array.
conversation_logs_enabledbooleanoptional
Optional update of conversation logs enabled
descriptionstringoptional
Agent description
instructionstringoptional
Agent instruction. Instructions help your agent to perform its job effectively. See [Write Effective Agent Instructions](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/#agent-instructions) for best practices.
kintegeroptional
How many results should be considered from an attached knowledge base
max_tokensintegeroptional
Specifies the maximum number of tokens the model can process in a single input or output, set as a number between 1 and 512. This determines the length of each response.
mcp_serversarray<object>optional
MCP (Model Context Protocol) servers to attach to the agent
model_provider_key_uuidstringoptional
Optional Model Provider uuid for use with provider models
model_router_uuidstringoptional
The UUID of the model router to use.
model_uuidstringoptional
Identifier for the foundation model.
namestringoptional
Agent name
open_ai_key_uuidstringoptional
Optional OpenAI key uuid for use with OpenAI models
project_idstringoptional
The id of the DigitalOcean project this agent will belong to
provide_citationsbooleanoptional
reasoning_effortstringoptional
retrieval_methodstringoptional
- RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown - RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite - RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back - RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries - RETRIEVAL_METHOD_NONE: The retrieval method is none
Allowed:RETRIEVAL_METHOD_UNKNOWNRETRIEVAL_METHOD_REWRITERETRIEVAL_METHOD_STEP_BACKRETRIEVAL_METHOD_SUB_QUERIESRETRIEVAL_METHOD_NONEDefault:RETRIEVAL_METHOD_UNKNOWN
router_preset_slugstringoptional
tagsarray<string>optional
A set of abitrary tags to organize your agent
temperaturenumberoptional
Controls the model’s creativity, specified as a number between 0 and 1. Lower values produce more predictable and conservative responses, while higher values encourage creativity and variation.
thinking_token_budgetintegeroptional
top_pnumberoptional
Defines the cumulative probability threshold for word selection, specified as a number between 0 and 1. Higher values allow for more diverse outputs, while lower values ensure focused and coherent responses.
uuidstringoptional
Unique agent id
web_fetch_enabledbooleanoptional
Optional. Set to true to let the agent use the built-in web_fetch tool to retrieve content from public web pages, or false to disable it.
web_search_enabledbooleanoptional
Optional. Set to true to let the agent use the built-in web_search tool to search the public web for current information, or false to disable it.

6 status codes
200Returns an object containing the updated agent.
agentobjectoptional
An Agent
401Returned when authentication fails because the credentials are invalid.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
404Returned when the agent resource is not found.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429Returned when the API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500Returned when a server error occurs.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

Invalid credentials return a 401, and a 404 is returned when the agent resource is not found. Exceeding the API rate limit returns a 429, and a server error returns a 500. The uuid path parameter must identify an existing agent; max_tokens must be between 1 and 512, and values in allowed_domains must be fully qualified domain names.