Sign in
DigitalOcean-public.v2-new_GradientAI Platform

Update an Agent

To update an agent, send a PUT request to /v2/gen-ai/agents/{uuid}. The response body is a JSON object containing the agent.

put/v2/gen-ai/agents/{uuid}

Path parameters

uuidstring required

Unique agent id

Request body

agent_log_insights_enabledboolean
anthropic_key_uuidstring

Optional anthropic key uuid for use with anthropic models

conversation_logs_enabledboolean

Optional update of conversation logs enabled

descriptionstring

Agent description

instructionstring

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

kinteger

How many results should be considered from an attached knowledge base

max_tokensinteger

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_uuidstring

Identifier for the foundation model.

namestring

Agent name

open_ai_key_uuidstring

Optional OpenAI key uuid for use with OpenAI models

project_idstring

The id of the DigitalOcean project this agent will belong to

provide_citationsboolean
retrieval_method'RETRIEVAL_METHOD_UNKNOWN' | 'RETRIEVAL_METHOD_REWRITE' | 'RETRIEVAL_METHOD_STEP_BACK' | 'RETRIEVAL_METHOD_SUB_QUERIES' | 'RETRIEVAL_METHOD_NONE'
  • 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
tagsstring[]

A set of abitrary tags to organize your agent

temperaturenumber float

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.

top_pnumber float

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.

uuidstring

Unique agent id

Example request

{
  "agent_log_insights_enabled": true,
  "anthropic_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "conversation_logs_enabled": true,
  "description": "\"My Agent Description\"",
  "instruction": "\"You are an agent who thinks deeply about the world\"",
  "k": 5,
  "max_tokens": 100,
  "model_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "\"My New Agent Name\"",
  "open_ai_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "project_id": "\"12345678-1234-1234-1234-123456789012\"",
  "provide_citations": true,
  "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
  "tags": [
    "example string"
  ],
  "temperature": 0.7,
  "top_p": 0.9,
  "uuid": "\"12345678-1234-1234-1234-123456789012\""
}

Response

A successful response.

Example response

{
  "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"
      }
    ],
    "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",
        "name": "example name",
        "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,
        "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": "12345",
        "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,
      "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,
          "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"
    },
    "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": "12345",
          "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,
        "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",
    "workspace": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "created_by_email": "example@example.com",
      "deleted_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "evaluation_test_cases": [
        {
          "archived_at": "2023-01-01T00:00:00Z",
          "created_at": "2023-01-01T00:00:00Z",
          "created_by_user_email": "example@example.com",
          "created_by_user_id": "12345",
          "dataset": {
            "created_at": "2023-01-01T00:00:00Z",
            "dataset_name": "example name",
            "dataset_uuid": "123e4567-e89b-12d3-a456-426614174000",
            "file_size": "12345",
            "has_ground_truth": true,
            "row_count": 123
          },
          "dataset_name": "example name",
          "dataset_uuid": "123e4567-e89b-12d3-a456-426614174000",
          "description": "example string",
          "latest_version_number_of_runs": 123,
          "metrics": [
            {
              "description": "example string",
              "inverted": true,
              "metric_name": "example name",
              "metric_type": "METRIC_TYPE_UNSPECIFIED",
              "metric_uuid": "123e4567-e89b-12d3-a456-426614174000",
              "metric_value_type": "METRIC_VALUE_TYPE_UNSPECIFIED",
              "range_max": 123,
              "range_min": 123
            }
          ],
          "name": "example name",
          "star_metric": {
            "metric_uuid": "123e4567-e89b-12d3-a456-426614174000",
            "name": "example name",
            "success_threshold": 123,
            "success_threshold_pct": 123
          },
          "test_case_uuid": "123e4567-e89b-12d3-a456-426614174000",
          "total_runs": 123,
          "updated_at": "2023-01-01T00:00:00Z",
          "updated_by_user_email": "example@example.com",
          "updated_by_user_id": "12345",
          "version": 123
        }
      ],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}

Changes

Changed in 6 of the 8 revisions of this API.11458

  • cb3bf9b214592See the full diff
    • ○

      api tag DigitalOcean-public.v2-new_GradientAI Platform added

      api-tag-added

    • ○

      api tag GradientAI Platform removed

      api-tag-removed

    This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 9aca3802735e9See the full diff
    • ○

      added the new optional request property agent_log_insights_enabled

      new-optional-request-property

    • ○

      added the optional property agent/knowledge_bases/items/last_indexing_job/total_items_failed to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/knowledge_bases/items/last_indexing_job/total_items_indexed to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/knowledge_bases/items/last_indexing_job/total_items_skipped to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/logging_config/insights_enabled to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/logging_config/insights_enabled_at to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/template/knowledge_bases/items/last_indexing_job/total_items_failed to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/template/knowledge_bases/items/last_indexing_job/total_items_indexed to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/template/knowledge_bases/items/last_indexing_job/total_items_skipped to the response with the 200 status

      response-optional-property-added

  • f8e8c290636c118See the full diff
    • ●

      added the new METRIC_VALUE_TYPE_PERCENTAGE enum value to the agent/workspace/evaluation_test_cases/items/metrics/items/metric_value_type response property for the response status 200

      response-property-enum-value-added

    • ○

      api operation id update_agent removed and replaced with genai_update_agent

      api-operation-id-removed

    • ○

      the endpoint scheme security bearer_auth was added to the API

      api-security-added

    • ○

      api tag GradientAI Platform added

      api-tag-added

    • ○

      api tag GenAIAPI removed

      api-tag-removed

    • ○

      added the new optional request property conversation_logs_enabled

      new-optional-request-property

    • ○

      request body became optional

      request-body-became-optional

    • ○

      added the non-success response with the status 401

      response-non-success-status-added

    • ○

      added the non-success response with the status 404

      response-non-success-status-added

    • ○

      added the non-success response with the status 429

      response-non-success-status-added

    • ○

      added the non-success response with the status 500

      response-non-success-status-added

    • ○

      added the optional property agent/conversation_logs_enabled to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/logging_config to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/version_hash to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/workspace/evaluation_test_cases/items/dataset to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/workspace/evaluation_test_cases/items/metrics/items/inverted to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/workspace/evaluation_test_cases/items/metrics/items/range_max to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/workspace/evaluation_test_cases/items/metrics/items/range_min to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/workspace/evaluation_test_cases/items/star_metric/success_threshold to the response with the 200 status

      response-optional-property-added

    This revision also has 70 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 5fc9af728e821129See the full diff
    • ▲

      request body became required

      request-body-became-required

    • ●

      the optional response header ratelimit-limit removed for the status 200

      optional-response-header-removed

    • ●

      the optional response header ratelimit-remaining removed for the status 200

      optional-response-header-removed

    • ●

      the optional response header ratelimit-reset removed for the status 200

      optional-response-header-removed

    • ●

      removed the request property conversation_logs_enabled

      request-property-removed

    • ●

      removed the optional property agent/conversation_logs_enabled from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property agent/logging_config from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property agent/version_hash from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property agent/workspace/evaluation_test_cases/items/dataset from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property agent/workspace/evaluation_test_cases/items/metrics/items/inverted from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property agent/workspace/evaluation_test_cases/items/metrics/items/range_max from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property agent/workspace/evaluation_test_cases/items/metrics/items/range_min from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property agent/workspace/evaluation_test_cases/items/star_metric/success_threshold from the response with the 200 status

      response-optional-property-removed

    • ○

      api operation id genai_update_agent removed and replaced with update_agent

      api-operation-id-removed

    • ○

      the endpoint scheme security bearer_auth was removed from the API

      api-security-removed

    • ○

      api tag GenAIAPI added

      api-tag-added

    • ○

      api tag GradientAI Platform removed

      api-tag-removed

    • ○

      removed the non-success response with the status 401

      response-non-success-status-removed

    • ○

      removed the non-success response with the status 404

      response-non-success-status-removed

    • ○

      removed the non-success response with the status 429

      response-non-success-status-removed

    • ○

      removed the non-success response with the status 500

      response-non-success-status-removed

    • ○

      removed the METRIC_VALUE_TYPE_PERCENTAGE enum value from the agent/workspace/evaluation_test_cases/items/metrics/items/metric_value_type response property for the response status 200

      response-property-enum-value-removed

    This revision also has 436 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • f8e8c290636c118See the full diff
    • ●

      added the new METRIC_VALUE_TYPE_PERCENTAGE enum value to the agent/workspace/evaluation_test_cases/items/metrics/items/metric_value_type response property for the response status 200

      response-property-enum-value-added

    • ○

      api operation id update_agent removed and replaced with genai_update_agent

      api-operation-id-removed

    • ○

      the endpoint scheme security bearer_auth was added to the API

      api-security-added

    • ○

      api tag GradientAI Platform added

      api-tag-added

    • ○

      api tag GenAIAPI removed

      api-tag-removed

    • ○

      added the new optional request property conversation_logs_enabled

      new-optional-request-property

    • ○

      request body became optional

      request-body-became-optional

    • ○

      added the non-success response with the status 401

      response-non-success-status-added

    • ○

      added the non-success response with the status 404

      response-non-success-status-added

    • ○

      added the non-success response with the status 429

      response-non-success-status-added

    • ○

      added the non-success response with the status 500

      response-non-success-status-added

    • ○

      added the optional property agent/conversation_logs_enabled to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/logging_config to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/version_hash to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/workspace/evaluation_test_cases/items/dataset to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/workspace/evaluation_test_cases/items/metrics/items/inverted to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/workspace/evaluation_test_cases/items/metrics/items/range_max to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/workspace/evaluation_test_cases/items/metrics/items/range_min to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/workspace/evaluation_test_cases/items/star_metric/success_threshold to the response with the 200 status

      response-optional-property-added

    This revision also has 70 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • e8b3cbc80e182See the full diff
    • ○

      added the optional property agent/knowledge_bases/items/last_indexing_job/status to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property agent/template/knowledge_bases/items/last_indexing_job/status to the response with the 200 status

      response-optional-property-added