Skip to content
DigitalOcean Gradient™ AI Agentic Cloud SDK Docs
  • Auto
  • Light
  • Dark

Update

API Reference
Agents
Update an Agent
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.

Path ParametersExpand Collapse
uuid: string
Body ParametersExpand Collapse
agent_log_insights_enabled: optional boolean
anthropic_key_uuid: optional string

Optional anthropic key uuid for use with anthropic models

conversation_logs_enabled: optional boolean

Optional update of conversation logs enabled

description: optional string

Agent description

instruction: optional string

Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices.

k: optional number

How many results should be considered from an attached knowledge base

formatint64
max_tokens: optional 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.

formatint64
model_uuid: optional string

Identifier for the foundation model.

name: optional string

Agent name

open_ai_key_uuid: optional string

Optional OpenAI key uuid for use with OpenAI models

project_id: optional string

The id of the DigitalOcean project this agent will belong to

provide_citations: optional boolean
retrieval_method: optional 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
tags: optional array of string

A set of abitrary tags to organize your agent

temperature: optional 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.

formatfloat
top_p: optional 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.

formatfloat
uuid: optional string

Unique agent id

ReturnsExpand Collapse
agent: optional APIAgent

An Agent

curl https://api.digitalocean.com/v2/gen-ai/agents/$UUID \
    -X PUT \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $DIGITALOCEAN_ACCESS_TOKEN"
{
  "agent": {
    "anthropic_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "api_key_infos": [
      {
        "created_at": "2023-01-01T00:00:00Z",
        "created_by": "12345",
        "deleted_at": "2023-01-01T00:00:00Z",
        "name": "example name",
        "secret_key": "example string",
        "uuid": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "api_keys": [
      {
        "api_key": "example string"
      }
    ],
    "chatbot": {
      "button_background_color": "example string",
      "logo": "example string",
      "name": "example name",
      "primary_color": "example string",
      "secondary_color": "example string",
      "starting_message": "example string"
    },
    "chatbot_identifiers": [
      {
        "agent_chatbot_identifier": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "child_agents": [],
    "conversation_logs_enabled": true,
    "created_at": "2023-01-01T00:00:00Z",
    "deployment": {
      "created_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "status": "STATUS_UNKNOWN",
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "VISIBILITY_UNKNOWN"
    },
    "description": "example string",
    "functions": [
      {
        "api_key": "example string",
        "created_at": "2023-01-01T00:00:00Z",
        "created_by": "12345",
        "description": "example string",
        "faas_name": "example name",
        "faas_namespace": "example name",
        "input_schema": {},
        "name": "example name",
        "output_schema": {},
        "updated_at": "2023-01-01T00:00:00Z",
        "url": "example string",
        "uuid": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "guardrails": [
      {
        "agent_uuid": "123e4567-e89b-12d3-a456-426614174000",
        "created_at": "2023-01-01T00:00:00Z",
        "default_response": "example string",
        "description": "example string",
        "guardrail_uuid": "123e4567-e89b-12d3-a456-426614174000",
        "is_attached": true,
        "is_default": true,
        "metadata": {},
        "name": "example name",
        "priority": 123,
        "type": "GUARDRAIL_TYPE_UNKNOWN",
        "updated_at": "2023-01-01T00:00:00Z",
        "uuid": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "if_case": "example string",
    "instruction": "example string",
    "k": 123,
    "knowledge_bases": [
      {
        "added_to_agent_at": "2023-01-01T00:00:00Z",
        "created_at": "2023-01-01T00:00:00Z",
        "database_id": "123e4567-e89b-12d3-a456-426614174000",
        "embedding_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
        "is_public": true,
        "last_indexing_job": {
          "completed_datasources": 123,
          "created_at": "2023-01-01T00:00:00Z",
          "data_source_uuids": [
            "example string"
          ],
          "finished_at": "2023-01-01T00:00:00Z",
          "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
          "phase": "BATCH_JOB_PHASE_UNKNOWN",
          "started_at": "2023-01-01T00:00:00Z",
          "status": "INDEX_JOB_STATUS_UNKNOWN",
          "tokens": 123,
          "total_datasources": 123,
          "total_items_failed": "12345",
          "total_items_indexed": "12345",
          "total_items_skipped": "12345",
          "updated_at": "2023-01-01T00:00:00Z",
          "uuid": "123e4567-e89b-12d3-a456-426614174000"
        },
        "name": "example name",
        "project_id": "123e4567-e89b-12d3-a456-426614174000",
        "region": "example string",
        "tags": [
          "example string"
        ],
        "updated_at": "2023-01-01T00:00:00Z",
        "user_id": "user_id",
        "uuid": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "logging_config": {
      "galileo_project_id": "123e4567-e89b-12d3-a456-426614174000",
      "galileo_project_name": "example name",
      "insights_enabled": true,
      "insights_enabled_at": "2023-01-01T00:00:00Z",
      "log_stream_id": "123e4567-e89b-12d3-a456-426614174000",
      "log_stream_name": "example name"
    },
    "max_tokens": 123,
    "model": {
      "agreement": {
        "description": "example string",
        "name": "example name",
        "url": "example string",
        "uuid": "123e4567-e89b-12d3-a456-426614174000"
      },
      "created_at": "2023-01-01T00:00:00Z",
      "inference_name": "example name",
      "inference_version": "example string",
      "is_foundational": true,
      "metadata": {},
      "name": "example name",
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "example string",
      "usecases": [
        "MODEL_USECASE_AGENT",
        "MODEL_USECASE_GUARDRAIL"
      ],
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "version": {
        "major": 123,
        "minor": 123,
        "patch": 123
      }
    },
    "name": "example name",
    "openai_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [
        {
          "agreement": {
            "description": "example string",
            "name": "example name",
            "url": "example string",
            "uuid": "123e4567-e89b-12d3-a456-426614174000"
          },
          "created_at": "2023-01-01T00:00:00Z",
          "inference_name": "example name",
          "inference_version": "example string",
          "is_foundational": true,
          "metadata": {},
          "name": "example name",
          "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
          "provider": "MODEL_PROVIDER_DIGITALOCEAN",
          "updated_at": "2023-01-01T00:00:00Z",
          "upload_complete": true,
          "url": "example string",
          "usecases": [
            "MODEL_USECASE_AGENT",
            "MODEL_USECASE_GUARDRAIL"
          ],
          "uuid": "123e4567-e89b-12d3-a456-426614174000",
          "version": {
            "major": 123,
            "minor": 123,
            "patch": 123
          }
        }
      ],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "parent_agents": [],
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "provide_citations": true,
    "region": "example string",
    "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
    "route_created_at": "2023-01-01T00:00:00Z",
    "route_created_by": "12345",
    "route_name": "example name",
    "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tags": [
      "example string"
    ],
    "temperature": 123,
    "template": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "guardrails": [
        {
          "priority": 123,
          "uuid": "123e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [
        {
          "added_to_agent_at": "2023-01-01T00:00:00Z",
          "created_at": "2023-01-01T00:00:00Z",
          "database_id": "123e4567-e89b-12d3-a456-426614174000",
          "embedding_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
          "is_public": true,
          "last_indexing_job": {
            "completed_datasources": 123,
            "created_at": "2023-01-01T00:00:00Z",
            "data_source_uuids": [
              "example string"
            ],
            "finished_at": "2023-01-01T00:00:00Z",
            "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
            "phase": "BATCH_JOB_PHASE_UNKNOWN",
            "started_at": "2023-01-01T00:00:00Z",
            "status": "INDEX_JOB_STATUS_UNKNOWN",
            "tokens": 123,
            "total_datasources": 123,
            "total_items_failed": "12345",
            "total_items_indexed": "12345",
            "total_items_skipped": "12345",
            "updated_at": "2023-01-01T00:00:00Z",
            "uuid": "123e4567-e89b-12d3-a456-426614174000"
          },
          "name": "example name",
          "project_id": "123e4567-e89b-12d3-a456-426614174000",
          "region": "example string",
          "tags": [
            "example string"
          ],
          "updated_at": "2023-01-01T00:00:00Z",
          "user_id": "user_id",
          "uuid": "123e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "long_description": "\"Enhance your customer service with an AI agent designed to provide consistent, helpful, and accurate support across multiple channels. This template creates an agent that can answer product questions, troubleshoot common issues, process simple requests, and maintain a friendly, on-brand voice throughout customer interactions. Reduce response times, handle routine inquiries efficiently, and ensure your customers feel heard and helped.\"",
      "max_tokens": 123,
      "model": {
        "agreement": {
          "description": "example string",
          "name": "example name",
          "url": "example string",
          "uuid": "123e4567-e89b-12d3-a456-426614174000"
        },
        "created_at": "2023-01-01T00:00:00Z",
        "inference_name": "example name",
        "inference_version": "example string",
        "is_foundational": true,
        "metadata": {},
        "name": "example name",
        "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
        "provider": "MODEL_PROVIDER_DIGITALOCEAN",
        "updated_at": "2023-01-01T00:00:00Z",
        "upload_complete": true,
        "url": "example string",
        "usecases": [
          "MODEL_USECASE_AGENT",
          "MODEL_USECASE_GUARDRAIL"
        ],
        "uuid": "123e4567-e89b-12d3-a456-426614174000",
        "version": {
          "major": 123,
          "minor": 123,
          "patch": 123
        }
      },
      "name": "example name",
      "short_description": "\"This template has been designed with question-answer and conversational use cases in mind. It comes with validated agent instructions, fine-tuned model settings, and preconfigured guardrails defined for customer support-related use cases.\"",
      "summary": "example string",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "template_type": "AGENT_TEMPLATE_TYPE_STANDARD",
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "top_p": 123,
    "updated_at": "2023-01-01T00:00:00Z",
    "url": "example string",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "version_hash": "example string"
  }
}
Returns Examples
{
  "agent": {
    "anthropic_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "api_key_infos": [
      {
        "created_at": "2023-01-01T00:00:00Z",
        "created_by": "12345",
        "deleted_at": "2023-01-01T00:00:00Z",
        "name": "example name",
        "secret_key": "example string",
        "uuid": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "api_keys": [
      {
        "api_key": "example string"
      }
    ],
    "chatbot": {
      "button_background_color": "example string",
      "logo": "example string",
      "name": "example name",
      "primary_color": "example string",
      "secondary_color": "example string",
      "starting_message": "example string"
    },
    "chatbot_identifiers": [
      {
        "agent_chatbot_identifier": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "child_agents": [],
    "conversation_logs_enabled": true,
    "created_at": "2023-01-01T00:00:00Z",
    "deployment": {
      "created_at": "2023-01-01T00:00:00Z",
      "name": "example name",
      "status": "STATUS_UNKNOWN",
      "updated_at": "2023-01-01T00:00:00Z",
      "url": "example string",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "visibility": "VISIBILITY_UNKNOWN"
    },
    "description": "example string",
    "functions": [
      {
        "api_key": "example string",
        "created_at": "2023-01-01T00:00:00Z",
        "created_by": "12345",
        "description": "example string",
        "faas_name": "example name",
        "faas_namespace": "example name",
        "input_schema": {},
        "name": "example name",
        "output_schema": {},
        "updated_at": "2023-01-01T00:00:00Z",
        "url": "example string",
        "uuid": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "guardrails": [
      {
        "agent_uuid": "123e4567-e89b-12d3-a456-426614174000",
        "created_at": "2023-01-01T00:00:00Z",
        "default_response": "example string",
        "description": "example string",
        "guardrail_uuid": "123e4567-e89b-12d3-a456-426614174000",
        "is_attached": true,
        "is_default": true,
        "metadata": {},
        "name": "example name",
        "priority": 123,
        "type": "GUARDRAIL_TYPE_UNKNOWN",
        "updated_at": "2023-01-01T00:00:00Z",
        "uuid": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "if_case": "example string",
    "instruction": "example string",
    "k": 123,
    "knowledge_bases": [
      {
        "added_to_agent_at": "2023-01-01T00:00:00Z",
        "created_at": "2023-01-01T00:00:00Z",
        "database_id": "123e4567-e89b-12d3-a456-426614174000",
        "embedding_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
        "is_public": true,
        "last_indexing_job": {
          "completed_datasources": 123,
          "created_at": "2023-01-01T00:00:00Z",
          "data_source_uuids": [
            "example string"
          ],
          "finished_at": "2023-01-01T00:00:00Z",
          "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
          "phase": "BATCH_JOB_PHASE_UNKNOWN",
          "started_at": "2023-01-01T00:00:00Z",
          "status": "INDEX_JOB_STATUS_UNKNOWN",
          "tokens": 123,
          "total_datasources": 123,
          "total_items_failed": "12345",
          "total_items_indexed": "12345",
          "total_items_skipped": "12345",
          "updated_at": "2023-01-01T00:00:00Z",
          "uuid": "123e4567-e89b-12d3-a456-426614174000"
        },
        "name": "example name",
        "project_id": "123e4567-e89b-12d3-a456-426614174000",
        "region": "example string",
        "tags": [
          "example string"
        ],
        "updated_at": "2023-01-01T00:00:00Z",
        "user_id": "user_id",
        "uuid": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "logging_config": {
      "galileo_project_id": "123e4567-e89b-12d3-a456-426614174000",
      "galileo_project_name": "example name",
      "insights_enabled": true,
      "insights_enabled_at": "2023-01-01T00:00:00Z",
      "log_stream_id": "123e4567-e89b-12d3-a456-426614174000",
      "log_stream_name": "example name"
    },
    "max_tokens": 123,
    "model": {
      "agreement": {
        "description": "example string",
        "name": "example name",
        "url": "example string",
        "uuid": "123e4567-e89b-12d3-a456-426614174000"
      },
      "created_at": "2023-01-01T00:00:00Z",
      "inference_name": "example name",
      "inference_version": "example string",
      "is_foundational": true,
      "metadata": {},
      "name": "example name",
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z",
      "upload_complete": true,
      "url": "example string",
      "usecases": [
        "MODEL_USECASE_AGENT",
        "MODEL_USECASE_GUARDRAIL"
      ],
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "version": {
        "major": 123,
        "minor": 123,
        "patch": 123
      }
    },
    "name": "example name",
    "openai_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [
        {
          "agreement": {
            "description": "example string",
            "name": "example name",
            "url": "example string",
            "uuid": "123e4567-e89b-12d3-a456-426614174000"
          },
          "created_at": "2023-01-01T00:00:00Z",
          "inference_name": "example name",
          "inference_version": "example string",
          "is_foundational": true,
          "metadata": {},
          "name": "example name",
          "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
          "provider": "MODEL_PROVIDER_DIGITALOCEAN",
          "updated_at": "2023-01-01T00:00:00Z",
          "upload_complete": true,
          "url": "example string",
          "usecases": [
            "MODEL_USECASE_AGENT",
            "MODEL_USECASE_GUARDRAIL"
          ],
          "uuid": "123e4567-e89b-12d3-a456-426614174000",
          "version": {
            "major": 123,
            "minor": 123,
            "patch": 123
          }
        }
      ],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "parent_agents": [],
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "provide_citations": true,
    "region": "example string",
    "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
    "route_created_at": "2023-01-01T00:00:00Z",
    "route_created_by": "12345",
    "route_name": "example name",
    "route_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tags": [
      "example string"
    ],
    "temperature": 123,
    "template": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "guardrails": [
        {
          "priority": 123,
          "uuid": "123e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [
        {
          "added_to_agent_at": "2023-01-01T00:00:00Z",
          "created_at": "2023-01-01T00:00:00Z",
          "database_id": "123e4567-e89b-12d3-a456-426614174000",
          "embedding_model_uuid": "123e4567-e89b-12d3-a456-426614174000",
          "is_public": true,
          "last_indexing_job": {
            "completed_datasources": 123,
            "created_at": "2023-01-01T00:00:00Z",
            "data_source_uuids": [
              "example string"
            ],
            "finished_at": "2023-01-01T00:00:00Z",
            "knowledge_base_uuid": "123e4567-e89b-12d3-a456-426614174000",
            "phase": "BATCH_JOB_PHASE_UNKNOWN",
            "started_at": "2023-01-01T00:00:00Z",
            "status": "INDEX_JOB_STATUS_UNKNOWN",
            "tokens": 123,
            "total_datasources": 123,
            "total_items_failed": "12345",
            "total_items_indexed": "12345",
            "total_items_skipped": "12345",
            "updated_at": "2023-01-01T00:00:00Z",
            "uuid": "123e4567-e89b-12d3-a456-426614174000"
          },
          "name": "example name",
          "project_id": "123e4567-e89b-12d3-a456-426614174000",
          "region": "example string",
          "tags": [
            "example string"
          ],
          "updated_at": "2023-01-01T00:00:00Z",
          "user_id": "user_id",
          "uuid": "123e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "long_description": "\"Enhance your customer service with an AI agent designed to provide consistent, helpful, and accurate support across multiple channels. This template creates an agent that can answer product questions, troubleshoot common issues, process simple requests, and maintain a friendly, on-brand voice throughout customer interactions. Reduce response times, handle routine inquiries efficiently, and ensure your customers feel heard and helped.\"",
      "max_tokens": 123,
      "model": {
        "agreement": {
          "description": "example string",
          "name": "example name",
          "url": "example string",
          "uuid": "123e4567-e89b-12d3-a456-426614174000"
        },
        "created_at": "2023-01-01T00:00:00Z",
        "inference_name": "example name",
        "inference_version": "example string",
        "is_foundational": true,
        "metadata": {},
        "name": "example name",
        "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
        "provider": "MODEL_PROVIDER_DIGITALOCEAN",
        "updated_at": "2023-01-01T00:00:00Z",
        "upload_complete": true,
        "url": "example string",
        "usecases": [
          "MODEL_USECASE_AGENT",
          "MODEL_USECASE_GUARDRAIL"
        ],
        "uuid": "123e4567-e89b-12d3-a456-426614174000",
        "version": {
          "major": 123,
          "minor": 123,
          "patch": 123
        }
      },
      "name": "example name",
      "short_description": "\"This template has been designed with question-answer and conversational use cases in mind. It comes with validated agent instructions, fine-tuned model settings, and preconfigured guardrails defined for customer support-related use cases.\"",
      "summary": "example string",
      "tags": [
        "example string"
      ],
      "temperature": 123,
      "template_type": "AGENT_TEMPLATE_TYPE_STANDARD",
      "top_p": 123,
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "top_p": 123,
    "updated_at": "2023-01-01T00:00:00Z",
    "url": "example string",
    "user_id": "12345",
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "version_hash": "example string"
  }
}