# Agents ## Create **post** `/v2/gen-ai/agents` To create a new agent, send a POST request to `/v2/gen-ai/agents`. The response body contains a JSON object with the newly created agent object. ### Returns - **agent:** `APIAgent` An Agent ## Retrieve **get** `/v2/gen-ai/agents/{uuid}` To retrieve details of an agent, GET request to `/v2/gen-ai/agents/{uuid}`. The response body is a JSON object containing the agent. ### Returns - **agent:** `APIAgent` An Agent ## Update **put** `/v2/gen-ai/agents/{uuid}` To update an agent, send a PUT request to `/v2/gen-ai/agents/{uuid}`. The response body is a JSON object containing the agent. ### Returns - **agent:** `APIAgent` An Agent ## List **get** `/v2/gen-ai/agents` To list all agents, send a GET request to `/v2/gen-ai/agents`. ### Returns - **agents:** `array of object` Agents - **chatbot:** `object` A Chatbot - **button\_background\_color:** `string` - **logo:** `string` - **name:** `string` Name of chatbot - **primary\_color:** `string` - **secondary\_color:** `string` - **starting\_message:** `string` - **chatbot\_identifiers:** `array of object` Chatbot identifiers - **agent\_chatbot\_identifier:** `string` Agent chatbot identifier - **created\_at:** `string` Creation date / time - **deployment:** `object` Description of deployment - **created\_at:** `string` Creation date / time - **name:** `string` Name - **status:** `"STATUS_UNKNOWN" OR "STATUS_WAITING_FOR_DEPLOYMENT" OR "STATUS_DEPLOYING" OR 6 more` - `"STATUS_UNKNOWN"` - `"STATUS_WAITING_FOR_DEPLOYMENT"` - `"STATUS_DEPLOYING"` - `"STATUS_RUNNING"` - `"STATUS_FAILED"` - `"STATUS_WAITING_FOR_UNDEPLOYMENT"` - `"STATUS_UNDEPLOYING"` - `"STATUS_UNDEPLOYMENT_FAILED"` - `"STATUS_DELETED"` - **updated\_at:** `string` Last modified - **url:** `string` Access your deployed agent here - **uuid:** `string` Unique id - **visibility:** `APIDeploymentVisibility` - VISIBILITY_UNKNOWN: The status of the deployment is unknown - VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests - VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state - VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet - VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys - **description:** `string` Description of agent - **if\_case:** `string` Instructions to the agent on how to use the route - **instruction:** `string` 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. - **k:** `number` How many results should be considered from an attached knowledge base - **max\_tokens:** `number` 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. - **model:** `APIAgentModel` Description of a Model - **name:** `string` Agent name - **project\_id:** `string` The DigitalOcean project ID associated with the agent - **provide\_citations:** `boolean` Whether the agent should provide in-response citations - **region:** `string` Region code - **retrieval\_method:** `APIRetrievalMethod` - 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 - **route\_created\_at:** `string` Creation of route date / time - **route\_created\_by:** `string` Id of user that created the route - **route\_name:** `string` Route name - **route\_uuid:** `string` Route uuid - **tags:** `array of string` A set of abitrary tags to organize your agent - **temperature:** `number` 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. - **template:** `object` Represents an AgentTemplate entity - **created\_at:** `string` The agent template's creation date - **description:** `string` Deprecated - Use summary instead - **guardrails:** `array of object` List of guardrails associated with the agent template - **priority:** `number` Priority of the guardrail - **uuid:** `string` Uuid of the guardrail - **instruction:** `string` Instructions for the agent template - **k:** `number` The 'k' value for the agent template - **knowledge\_bases:** `array of APIKnowledgeBase` List of knowledge bases associated with the agent template - **long\_description:** `string` The long description of the agent template - **max\_tokens:** `number` The max_tokens setting for the agent template - **model:** `APIAgentModel` Description of a Model - **name:** `string` Name of the agent template - **short\_description:** `string` The short description of the agent template - **summary:** `string` The summary of the agent template - **tags:** `array of string` List of tags associated with the agent template - **temperature:** `number` The temperature setting for the agent template - **template\_type:** `"AGENT_TEMPLATE_TYPE_STANDARD" OR "AGENT_TEMPLATE_TYPE_ONE_CLICK"` - AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template - AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template - `"AGENT_TEMPLATE_TYPE_STANDARD"` - `"AGENT_TEMPLATE_TYPE_ONE_CLICK"` - **top\_p:** `number` The top_p setting for the agent template - **updated\_at:** `string` The agent template's last updated date - **uuid:** `string` Unique id - **top\_p:** `number` 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. - **updated\_at:** `string` Last modified - **url:** `string` Access your agent under this url - **user\_id:** `string` Id of user that created the agent - **uuid:** `string` Unique agent id - **version\_hash:** `string` The latest version of the agent - **links:** `APILinks` Links to other pages - **meta:** `APIMeta` Meta information about the data set ## Delete **delete** `/v2/gen-ai/agents/{uuid}` To delete an agent, send a DELETE request to `/v2/gen-ai/agents/{uuid}`. ### Returns - **agent:** `APIAgent` An Agent ## Update Status **put** `/v2/gen-ai/agents/{uuid}/deployment_visibility` Check whether an agent is public or private. To update the agent status, send a PUT request to `/v2/gen-ai/agents/{uuid}/deployment_visibility`. ### Returns - **agent:** `APIAgent` An Agent ## Domain Types ### API Agent - **APIAgent:** `object` An Agent - **anthropic\_api\_key:** `APIAnthropicAPIKeyInfo` Anthropic API Key Info - **api\_key\_infos:** `array of APIAgentAPIKeyInfo` Api key infos - **api\_keys:** `array of object` Api keys - **api\_key:** `string` Api key - **chatbot:** `object` A Chatbot - **button\_background\_color:** `string` - **logo:** `string` - **name:** `string` Name of chatbot - **primary\_color:** `string` - **secondary\_color:** `string` - **starting\_message:** `string` - **chatbot\_identifiers:** `array of object` Chatbot identifiers - **agent\_chatbot\_identifier:** `string` Agent chatbot identifier - **child\_agents:** `array of APIAgent` Child agents - **conversation\_logs\_enabled:** `boolean` Whether conversation logs are enabled for the agent - **created\_at:** `string` Creation date / time - **deployment:** `object` Description of deployment - **created\_at:** `string` Creation date / time - **name:** `string` Name - **status:** `"STATUS_UNKNOWN" OR "STATUS_WAITING_FOR_DEPLOYMENT" OR "STATUS_DEPLOYING" OR 6 more` - `"STATUS_UNKNOWN"` - `"STATUS_WAITING_FOR_DEPLOYMENT"` - `"STATUS_DEPLOYING"` - `"STATUS_RUNNING"` - `"STATUS_FAILED"` - `"STATUS_WAITING_FOR_UNDEPLOYMENT"` - `"STATUS_UNDEPLOYING"` - `"STATUS_UNDEPLOYMENT_FAILED"` - `"STATUS_DELETED"` - **updated\_at:** `string` Last modified - **url:** `string` Access your deployed agent here - **uuid:** `string` Unique id - **visibility:** `APIDeploymentVisibility` - VISIBILITY_UNKNOWN: The status of the deployment is unknown - VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests - VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state - VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet - VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys - **description:** `string` Description of agent - **functions:** `array of object` - **api\_key:** `string` Api key - **created\_at:** `string` Creation date / time - **created\_by:** `string` Created by user id from DO - **description:** `string` Agent description - **faas\_name:** `string` - **faas\_namespace:** `string` - **input\_schema:** `unknown` - **name:** `string` Name - **output\_schema:** `unknown` - **updated\_at:** `string` Last modified - **url:** `string` Download your agent here - **uuid:** `string` Unique id - **guardrails:** `array of object` The guardrails the agent is attached to - **agent\_uuid:** `string` - **created\_at:** `string` - **default\_response:** `string` - **description:** `string` - **guardrail\_uuid:** `string` - **is\_attached:** `boolean` - **is\_default:** `boolean` - **metadata:** `unknown` - **name:** `string` - **priority:** `number` - **type:** `"GUARDRAIL_TYPE_UNKNOWN" OR "GUARDRAIL_TYPE_JAILBREAK" OR "GUARDRAIL_TYPE_SENSITIVE_DATA" OR "GUARDRAIL_TYPE_CONTENT_MODERATION"` - `"GUARDRAIL_TYPE_UNKNOWN"` - `"GUARDRAIL_TYPE_JAILBREAK"` - `"GUARDRAIL_TYPE_SENSITIVE_DATA"` - `"GUARDRAIL_TYPE_CONTENT_MODERATION"` - **updated\_at:** `string` - **uuid:** `string` - **if\_case:** `string` - **instruction:** `string` 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. - **k:** `number` - **knowledge\_bases:** `array of APIKnowledgeBase` Knowledge bases - **logging\_config:** `object` - **galileo\_project\_id:** `string` Galileo project identifier - **galileo\_project\_name:** `string` Name of the Galileo project - **log\_stream\_id:** `string` Identifier for the log stream - **log\_stream\_name:** `string` Name of the log stream - **max\_tokens:** `number` - **model:** `APIAgentModel` Description of a Model - **name:** `string` Agent name - **openai\_api\_key:** `APIOpenAIAPIKeyInfo` OpenAI API Key Info - **parent\_agents:** `array of APIAgent` Parent agents - **project\_id:** `string` - **provide\_citations:** `boolean` Whether the agent should provide in-response citations - **region:** `string` Region code - **retrieval\_method:** `APIRetrievalMethod` - 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 - **route\_created\_at:** `string` Creation of route date / time - **route\_created\_by:** `string` - **route\_name:** `string` Route name - **route\_uuid:** `string` - **tags:** `array of string` Agent tag to organize related resources - **temperature:** `number` - **template:** `object` Represents an AgentTemplate entity - **created\_at:** `string` The agent template's creation date - **description:** `string` Deprecated - Use summary instead - **guardrails:** `array of object` List of guardrails associated with the agent template - **priority:** `number` Priority of the guardrail - **uuid:** `string` Uuid of the guardrail - **instruction:** `string` Instructions for the agent template - **k:** `number` The 'k' value for the agent template - **knowledge\_bases:** `array of APIKnowledgeBase` List of knowledge bases associated with the agent template - **long\_description:** `string` The long description of the agent template - **max\_tokens:** `number` The max_tokens setting for the agent template - **model:** `APIAgentModel` Description of a Model - **name:** `string` Name of the agent template - **short\_description:** `string` The short description of the agent template - **summary:** `string` The summary of the agent template - **tags:** `array of string` List of tags associated with the agent template - **temperature:** `number` The temperature setting for the agent template - **template\_type:** `"AGENT_TEMPLATE_TYPE_STANDARD" OR "AGENT_TEMPLATE_TYPE_ONE_CLICK"` - AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template - AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template - `"AGENT_TEMPLATE_TYPE_STANDARD"` - `"AGENT_TEMPLATE_TYPE_ONE_CLICK"` - **top\_p:** `number` The top_p setting for the agent template - **updated\_at:** `string` The agent template's last updated date - **uuid:** `string` Unique id - **top\_p:** `number` - **updated\_at:** `string` Last modified - **url:** `string` Access your agent under this url - **user\_id:** `string` Id of user that created the agent - **uuid:** `string` Unique agent id - **version\_hash:** `string` The latest version of the agent - **workspace:** `APIWorkspace` ### API Agent API Key Info - **APIAgentAPIKeyInfo:** `object` Agent API Key Info - **created\_at:** `string` Creation date - **created\_by:** `string` Created by - **deleted\_at:** `string` Deleted date - **name:** `string` Name - **secret\_key:** `string` - **uuid:** `string` Uuid ### API Agent Model - **APIAgentModel:** `object` Description of a Model - **agreement:** `APIAgreement` Agreement Description - **created\_at:** `string` Creation date / time - **inference\_name:** `string` Internally used name - **inference\_version:** `string` Internally used version - **is\_foundational:** `boolean` True if it is a foundational model provided by do - **metadata:** `unknown` Additional meta data - **name:** `string` Name of the model - **parent\_uuid:** `string` Unique id of the model, this model is based on - **provider:** `"MODEL_PROVIDER_DIGITALOCEAN" OR "MODEL_PROVIDER_ANTHROPIC" OR "MODEL_PROVIDER_OPENAI"` - `"MODEL_PROVIDER_DIGITALOCEAN"` - `"MODEL_PROVIDER_ANTHROPIC"` - `"MODEL_PROVIDER_OPENAI"` - **updated\_at:** `string` Last modified - **upload\_complete:** `boolean` Model has been fully uploaded - **url:** `string` Download url - **usecases:** `array of "MODEL_USECASE_UNKNOWN" OR "MODEL_USECASE_AGENT" OR "MODEL_USECASE_FINETUNED" OR 4 more` Usecases of the model - `"MODEL_USECASE_UNKNOWN"` - `"MODEL_USECASE_AGENT"` - `"MODEL_USECASE_FINETUNED"` - `"MODEL_USECASE_KNOWLEDGEBASE"` - `"MODEL_USECASE_GUARDRAIL"` - `"MODEL_USECASE_REASONING"` - `"MODEL_USECASE_SERVERLESS"` - **uuid:** `string` Unique id - **version:** `APIModelVersion` Version Information about a Model ### API Anthropic API Key Info - **APIAnthropicAPIKeyInfo:** `object` Anthropic API Key Info - **created\_at:** `string` Key creation date - **created\_by:** `string` Created by user id from DO - **deleted\_at:** `string` Key deleted date - **name:** `string` Name - **updated\_at:** `string` Key last updated date - **uuid:** `string` Uuid ### API Deployment Visibility - **APIDeploymentVisibility:** `"VISIBILITY_UNKNOWN" OR "VISIBILITY_DISABLED" OR "VISIBILITY_PLAYGROUND" OR 2 more` - VISIBILITY_UNKNOWN: The status of the deployment is unknown - VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests - VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state - VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet - VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys - `"VISIBILITY_UNKNOWN"` - `"VISIBILITY_DISABLED"` - `"VISIBILITY_PLAYGROUND"` - `"VISIBILITY_PUBLIC"` - `"VISIBILITY_PRIVATE"` ### API OpenAI API Key Info - **APIOpenAIAPIKeyInfo:** `object` OpenAI API Key Info - **created\_at:** `string` Key creation date - **created\_by:** `string` Created by user id from DO - **deleted\_at:** `string` Key deleted date - **models:** `array of APIAgentModel` Models supported by the openAI api key - **name:** `string` Name - **updated\_at:** `string` Key last updated date - **uuid:** `string` Uuid ### API Retrieval Method - **APIRetrievalMethod:** `"RETRIEVAL_METHOD_UNKNOWN" OR "RETRIEVAL_METHOD_REWRITE" OR "RETRIEVAL_METHOD_STEP_BACK" OR 2 more` - 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 - `"RETRIEVAL_METHOD_UNKNOWN"` - `"RETRIEVAL_METHOD_REWRITE"` - `"RETRIEVAL_METHOD_STEP_BACK"` - `"RETRIEVAL_METHOD_SUB_QUERIES"` - `"RETRIEVAL_METHOD_NONE"` ### API Workspace - **APIWorkspace:** `object` - **agents:** `array of APIAgent` Agents - **created\_at:** `string` Creation date - **created\_by:** `string` The id of user who created this workspace - **created\_by\_email:** `string` The email of the user who created this workspace - **deleted\_at:** `string` Deleted date - **description:** `string` Description of the workspace - **evaluation\_test\_cases:** `array of APIEvaluationTestCase` Evaluations - **name:** `string` Name of the workspace - **updated\_at:** `string` Update date - **uuid:** `string` Unique id