DigitalOcean API (unofficial showcase)
POST/v2/gen-ai/agents

Create an agent

Creates a new agent in the specified project and region. Configure the agent with fields such as name, instruction, and model_uuid, and optionally attach knowledge bases or MCP servers. A 200 response returns the newly created agent object.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

19 body fields

Optional agent configuration, including model, deployment, and integration settings.

anthropic_key_uuidstringoptional
Optional Anthropic API key ID to use with Anthropic models
descriptionstringoptional
A text description of the agent, not used in inference
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.
knowledge_base_uuidarray<string>optional
Ids of the knowledge base(s) to attach to the agent
mcp_serversarray<object>optional
MCP (Model Context Protocol) servers to attach to the agent
model_provider_key_uuidstringoptional
The identifier of the model provider API key to use.
model_router_uuidstringoptional
The identifier of the model router to use.
model_uuidstringoptional
Identifier for the foundation model.
namestringoptional
Agent name
open_ai_key_uuidstringoptional
Optional OpenAI API key ID to use with OpenAI models
project_idstringoptional
The id of the DigitalOcean project this agent will belong to
reasoning_effortstringoptional
The reasoning effort setting for the agent.
regionstringoptional
The DigitalOcean region to deploy your agent in
router_preset_slugstringoptional
The slug identifying the model router preset.
tagsarray<string>optional
Agent tag to organize related resources
thinking_token_budgetintegeroptional
web_fetch_enabledbooleanoptional
Whether the agent can use the built-in web_fetch tool to retrieve content from public web pages.
web_search_enabledbooleanoptional
Whether the agent can use the built-in web_search tool to search the public web for current information.
workspace_uuidstringoptional
Identifier for the workspace

6 status codes
200Returns the newly created agent object.
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 a referenced 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

A 401 is returned when authentication credentials are invalid. A 404 indicates that a referenced resource was not found; verify supplied identifiers such as model_uuid and knowledge_base_uuid. A 429 indicates that the API rate limit has been exceeded, and a 500 indicates a server error.