Agents

API Reference

Agents

Create an Agent

post/v2/gen-ai/agents

Delete an Agent

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

List Agents

get/v2/gen-ai/agents

Retrieve an Existing Agent

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

Update an Agent

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

Update Agent Status

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

ModelsExpand Collapse

APIAgent = object { anthropic_api_key, api_key_infos, api_keys, 37 more }

An Agent

anthropic_api_key: optional APIAnthropicAPIKeyInfo

Anthropic API Key Info

api_key_infos: optional array of APIAgentAPIKeyInfo

Api key infos

api_keys: optional array of object { api_key }

Api keys

api_key: optional string

Api key

chatbot: optional object { button_background_color, logo, name, 3 more }

A Chatbot

button_background_color: optional string

logo: optional string

Name of chatbot

primary_color: optional string

secondary_color: optional string

starting_message: optional string

chatbot_identifiers: optional array of object { agent_chatbot_identifier }

Chatbot identifiers

agent_chatbot_identifier: optional string

Agent chatbot identifier

child_agents: optional array of APIAgent

Child agents

conversation_logs_enabled: optional boolean

Whether conversation logs are enabled for the agent

created_at: optional string

Creation date / time

formatdate-time

deployment: optional object { created_at, name, status, 4 more }

Description of deployment

created_at: optional string

Creation date / time

formatdate-time

Name

status: optional "STATUS_UNKNOWN" or "STATUS_WAITING_FOR_DEPLOYMENT" or "STATUS_DEPLOYING" or 6 more

Accepts one of the following:

"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: optional string

Last modified

formatdate-time

url: optional string

Access your deployed agent here

uuid: optional string

Unique id

visibility: optional 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: optional string

Description of agent

functions: optional array of object { api_key, created_at, created_by, 9 more }

api_key: optional string

Api key

created_at: optional string

Creation date / time

formatdate-time

created_by: optional string

Created by user id from DO

formatuint64

description: optional string

Agent description

faas_name: optional string

faas_namespace: optional string

input_schema: optional unknown

Name

output_schema: optional unknown

updated_at: optional string

Last modified

formatdate-time

url: optional string

Download your agent here

uuid: optional string

Unique id

guardrails: optional array of object { agent_uuid, created_at, default_response, 10 more }

The guardrails the agent is attached to

agent_uuid: optional string

created_at: optional string

default_response: optional string

description: optional string

guardrail_uuid: optional string

is_attached: optional boolean

is_default: optional boolean

metadata: optional unknown

priority: optional number

type: optional "GUARDRAIL_TYPE_UNKNOWN" or "GUARDRAIL_TYPE_JAILBREAK" or "GUARDRAIL_TYPE_SENSITIVE_DATA" or "GUARDRAIL_TYPE_CONTENT_MODERATION"

Accepts one of the following:

"GUARDRAIL_TYPE_UNKNOWN"

"GUARDRAIL_TYPE_JAILBREAK"

"GUARDRAIL_TYPE_SENSITIVE_DATA"

"GUARDRAIL_TYPE_CONTENT_MODERATION"

updated_at: optional string

uuid: optional string

if_case: optional string

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

knowledge_bases: optional array of APIKnowledgeBase

Knowledge bases

logging_config: optional object { galileo_project_id, galileo_project_name, insights_enabled, 3 more }

galileo_project_id: optional string

Galileo project identifier

galileo_project_name: optional string

Name of the Galileo project

insights_enabled: optional boolean

Whether insights are enabled

insights_enabled_at: optional string

Timestamp when insights were enabled

formatdate-time

log_stream_id: optional string

Identifier for the log stream

log_stream_name: optional string

Name of the log stream

max_tokens: optional number

model: optional APIAgentModel

Description of a Model

Agent name

openai_api_key: optional APIOpenAIAPIKeyInfo

OpenAI API Key Info

parent_agents: optional array of APIAgent

Parent agents

project_id: optional string

provide_citations: optional boolean

Whether the agent should provide in-response citations

region: optional string

Region code

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

route_created_at: optional string

Creation of route date / time

formatdate-time

route_created_by: optional string

route_name: optional string

Route name

route_uuid: optional string

tags: optional array of string

Agent tag to organize related resources

temperature: optional number

Represents an AgentTemplate entity

created_at: optional string

The agent template's creation date

formatdate-time

description: optional string

Deprecated - Use summary instead

guardrails: optional array of object { priority, uuid }

List of guardrails associated with the agent template

priority: optional number

Priority of the guardrail

formatint32

uuid: optional string

Uuid of the guardrail

instruction: optional string

Instructions for the agent template

k: optional number

The 'k' value for the agent template

formatint64

knowledge_bases: optional array of APIKnowledgeBase

List of knowledge bases associated with the agent template

long_description: optional string

The long description of the agent template

max_tokens: optional number

The max_tokens setting for the agent template

formatint64

model: optional APIAgentModel

Description of a Model

Name of the agent template

short_description: optional string

The short description of the agent template

summary: optional string

The summary of the agent template

tags: optional array of string

List of tags associated with the agent template

temperature: optional number

The temperature setting for the agent template

formatfloat

template_type: optional "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

Accepts one of the following:

"AGENT_TEMPLATE_TYPE_STANDARD"

"AGENT_TEMPLATE_TYPE_ONE_CLICK"

top_p: optional number

The top_p setting for the agent template

formatfloat

updated_at: optional string

The agent template's last updated date

formatdate-time

uuid: optional string

Unique id

top_p: optional number

updated_at: optional string

Last modified

formatdate-time

url: optional string

Access your agent under this url

user_id: optional string

Id of user that created the agent

formatuint64

uuid: optional string

Unique agent id

version_hash: optional string

The latest version of the agent

workspace: optional APIWorkspace

APIAgentAPIKeyInfo = object { created_at, created_by, deleted_at, 3 more }

Agent API Key Info

created_at: optional string

Creation date

formatdate-time

created_by: optional string

Created by

formatuint64

deleted_at: optional string

Deleted date

formatdate-time

Name

secret_key: optional string

uuid: optional string

Uuid

APIAgentModel = object { agreement, created_at, inference_name, 12 more }

Description of a Model

agreement: optional APIAgreement

Agreement Description

created_at: optional string

Creation date / time

formatdate-time

inference_name: optional string

Internally used name

inference_version: optional string

Internally used version

is_foundational: optional boolean

True if it is a foundational model provided by do

metadata: optional unknown

Additional meta data

Name of the model

parent_uuid: optional string

Unique id of the model, this model is based on

provider: optional "MODEL_PROVIDER_DIGITALOCEAN" or "MODEL_PROVIDER_ANTHROPIC" or "MODEL_PROVIDER_OPENAI"

Accepts one of the following:

"MODEL_PROVIDER_DIGITALOCEAN"

"MODEL_PROVIDER_ANTHROPIC"

"MODEL_PROVIDER_OPENAI"

updated_at: optional string

Last modified

formatdate-time

upload_complete: optional boolean

Model has been fully uploaded

url: optional string

Download url

usecases: optional array of "MODEL_USECASE_UNKNOWN" or "MODEL_USECASE_AGENT" or "MODEL_USECASE_FINETUNED" or 4 more

Usecases of the model

Accepts one of the following:

"MODEL_USECASE_UNKNOWN"

"MODEL_USECASE_AGENT"

"MODEL_USECASE_FINETUNED"

"MODEL_USECASE_KNOWLEDGEBASE"

"MODEL_USECASE_GUARDRAIL"

"MODEL_USECASE_REASONING"

"MODEL_USECASE_SERVERLESS"

uuid: optional string

Unique id

version: optional APIModelVersion

Version Information about a Model

APIAnthropicAPIKeyInfo = object { created_at, created_by, deleted_at, 3 more }

Anthropic API Key Info

created_at: optional string

Key creation date

formatdate-time

created_by: optional string

Created by user id from DO

formatuint64

deleted_at: optional string

Key deleted date

formatdate-time

Name

updated_at: optional string

Key last updated date

formatdate-time

uuid: optional string

Uuid

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"

APIOpenAIAPIKeyInfo = object { created_at, created_by, deleted_at, 4 more }

OpenAI API Key Info

created_at: optional string

Key creation date

formatdate-time

created_by: optional string

Created by user id from DO

formatuint64

deleted_at: optional string

Key deleted date

formatdate-time

models: optional array of APIAgentModel

Models supported by the openAI api key

Name

updated_at: optional string

Key last updated date

formatdate-time

uuid: optional string

Uuid

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"

APIWorkspace = object { agents, created_at, created_by, 7 more }

agents: optional array of APIAgent

Agents

created_at: optional string

Creation date

formatdate-time

created_by: optional string

The id of user who created this workspace

formatuint64

created_by_email: optional string

The email of the user who created this workspace

deleted_at: optional string

Deleted date

formatdate-time

description: optional string

Description of the workspace

evaluation_test_cases: optional array of APIEvaluationTestCase

Evaluations

Name of the workspace

updated_at: optional string

Update date

formatdate-time

uuid: optional string

Unique id

AgentsAPI Keys

Create an Agent API Key

post/v2/gen-ai/agents/{agent_uuid}/api_keys

Delete API Key for an Agent

delete/v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}

List Agent API Keys

get/v2/gen-ai/agents/{agent_uuid}/api_keys

Regenerate API Key for an Agent

put/v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}/regenerate

Update API Key for an Agent

put/v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}

AgentsChat

AgentsChatCompletions

Creates a model response for the given chat conversation.

post/chat/completions?agent=true

AgentsEvaluation Datasets

Create Evaluation Dataset

post/v2/gen-ai/evaluation_datasets

Create Presigned URLs for Evaluation Dataset File Upload

post/v2/gen-ai/evaluation_datasets/file_upload_presigned_urls

AgentsEvaluation Metrics

List Evaluation Metrics

get/v2/gen-ai/evaluation_metrics

List Datacenter Regions

get/v2/gen-ai/regions

AgentsEvaluation MetricsAnthropic

AgentsEvaluation MetricsAnthropicKeys

Create Anthropic API Key

post/v2/gen-ai/anthropic/keys

Delete Anthropic API Key

delete/v2/gen-ai/anthropic/keys/{api_key_uuid}

List Anthropic API Keys

get/v2/gen-ai/anthropic/keys

List agents by Anthropic key

get/v2/gen-ai/anthropic/keys/{uuid}/agents

Get Anthropic API Key

get/v2/gen-ai/anthropic/keys/{api_key_uuid}

Update Anthropic API Key

put/v2/gen-ai/anthropic/keys/{api_key_uuid}

AgentsEvaluation MetricsModels

List Available Models

get/v2/gen-ai/models

AgentsEvaluation MetricsOpenAI

AgentsEvaluation MetricsOpenAIKeys

Create OpenAI API Key

post/v2/gen-ai/openai/keys

Delete OpenAI API Key

delete/v2/gen-ai/openai/keys/{api_key_uuid}

List OpenAI API Keys

get/v2/gen-ai/openai/keys

List agents by OpenAI key

get/v2/gen-ai/openai/keys/{uuid}/agents

Get OpenAI API Key

get/v2/gen-ai/openai/keys/{api_key_uuid}

Update OpenAI API Key

put/v2/gen-ai/openai/keys/{api_key_uuid}

AgentsEvaluation MetricsWorkspaces

Create a Workspace

post/v2/gen-ai/workspaces

Delete a Workspace

delete/v2/gen-ai/workspaces/{workspace_uuid}

List Workspaces

get/v2/gen-ai/workspaces

List Evaluation Test Cases by Workspace

get/v2/gen-ai/workspaces/{workspace_uuid}/evaluation_test_cases

Retrieve an Existing Workspace

get/v2/gen-ai/workspaces/{workspace_uuid}

Update a Workspace

put/v2/gen-ai/workspaces/{workspace_uuid}

AgentsEvaluation MetricsWorkspacesAgents

List agents by Workspace

get/v2/gen-ai/workspaces/{workspace_uuid}/agents

Move Agents to a Workspace

put/v2/gen-ai/workspaces/{workspace_uuid}/agents

AgentsEvaluation Runs

Run an Evaluation Test Case

post/v2/gen-ai/evaluation_runs

Retrieve Results of an Evaluation Run

get/v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results

Retrieve Information About an Existing Evaluation Run

get/v2/gen-ai/evaluation_runs/{evaluation_run_uuid}

Retrieve Results of an Evaluation Run Prompt

get/v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results/{prompt_id}

ModelsExpand Collapse

APIEvaluationMetric = object { description, inverted, metric_name, 5 more }

description: optional string

inverted: optional boolean

If true, the metric is inverted, meaning that a lower value is better.

metric_name: optional string

metric_type: optional "METRIC_TYPE_UNSPECIFIED" or "METRIC_TYPE_GENERAL_QUALITY" or "METRIC_TYPE_RAG_AND_TOOL"

Accepts one of the following:

"METRIC_TYPE_UNSPECIFIED"

"METRIC_TYPE_GENERAL_QUALITY"

"METRIC_TYPE_RAG_AND_TOOL"

metric_uuid: optional string

metric_value_type: optional "METRIC_VALUE_TYPE_UNSPECIFIED" or "METRIC_VALUE_TYPE_NUMBER" or "METRIC_VALUE_TYPE_STRING" or "METRIC_VALUE_TYPE_PERCENTAGE"

Accepts one of the following:

"METRIC_VALUE_TYPE_UNSPECIFIED"

"METRIC_VALUE_TYPE_NUMBER"

"METRIC_VALUE_TYPE_STRING"

"METRIC_VALUE_TYPE_PERCENTAGE"

range_max: optional number

The maximum value for the metric.

formatfloat

range_min: optional number

The minimum value for the metric.

formatfloat

APIEvaluationMetricResult = object { error_description, metric_name, metric_value_type, 3 more }

error_description: optional string

Error description if the metric could not be calculated.

metric_name: optional string

Metric name

metric_value_type: optional "METRIC_VALUE_TYPE_UNSPECIFIED" or "METRIC_VALUE_TYPE_NUMBER" or "METRIC_VALUE_TYPE_STRING" or "METRIC_VALUE_TYPE_PERCENTAGE"

Accepts one of the following:

"METRIC_VALUE_TYPE_UNSPECIFIED"

"METRIC_VALUE_TYPE_NUMBER"

"METRIC_VALUE_TYPE_STRING"

"METRIC_VALUE_TYPE_PERCENTAGE"

number_value: optional number

The value of the metric as a number.

formatdouble

reasoning: optional string

Reasoning of the metric result.

string_value: optional string

The value of the metric as a string.

APIEvaluationPrompt = object { ground_truth, input, input_tokens, 5 more }

ground_truth: optional string

The ground truth for the prompt.

input: optional string

input_tokens: optional string

The number of input tokens used in the prompt.

formatuint64

output: optional string

output_tokens: optional string

The number of output tokens used in the prompt.

formatuint64

prompt_chunks: optional array of object { chunk_usage_pct, chunk_used, index_uuid, 2 more }

The list of prompt chunks.

chunk_usage_pct: optional number

The usage percentage of the chunk.

formatdouble

chunk_used: optional boolean

Indicates if the chunk was used in the prompt.

index_uuid: optional string

The index uuid (Knowledge Base) of the chunk.

source_name: optional string

The source name for the chunk, e.g., the file name or document title.

text: optional string

Text content of the chunk.

prompt_id: optional number

Prompt ID

formatint64

prompt_level_metric_results: optional array of APIEvaluationMetricResult

The metric results for the prompt.

APIEvaluationRun = object { agent_deleted, agent_name, agent_uuid, 19 more }

agent_deleted: optional boolean

Whether agent is deleted

agent_name: optional string

Agent name

agent_uuid: optional string

Agent UUID.

agent_version_hash: optional string

Version hash

agent_workspace_uuid: optional string

Agent workspace uuid

created_by_user_email: optional string

created_by_user_id: optional string

error_description: optional string

The error description

evaluation_run_uuid: optional string

Evaluation run UUID.

evaluation_test_case_workspace_uuid: optional string

Evaluation test case workspace uuid

finished_at: optional string

Run end time.

formatdate-time

pass_status: optional boolean

The pass status of the evaluation run based on the star metric.

queued_at: optional string

Run queued time.

formatdate-time

run_level_metric_results: optional array of APIEvaluationMetricResult

run_name: optional string

Run name.

star_metric_result: optional APIEvaluationMetricResult

started_at: optional string

Run start time.

formatdate-time

status: optional "EVALUATION_RUN_STATUS_UNSPECIFIED" or "EVALUATION_RUN_QUEUED" or "EVALUATION_RUN_RUNNING_DATASET" or 6 more

Evaluation Run Statuses

Accepts one of the following:

"EVALUATION_RUN_STATUS_UNSPECIFIED"

"EVALUATION_RUN_QUEUED"

"EVALUATION_RUN_RUNNING_DATASET"

"EVALUATION_RUN_EVALUATING_RESULTS"

"EVALUATION_RUN_CANCELLING"

"EVALUATION_RUN_CANCELLED"

"EVALUATION_RUN_SUCCESSFUL"

"EVALUATION_RUN_PARTIALLY_SUCCESSFUL"

"EVALUATION_RUN_FAILED"

test_case_description: optional string

Test case description.

test_case_name: optional string

Test case name.

test_case_uuid: optional string

Test-case UUID.

test_case_version: optional number

Test-case-version.

formatint64

ModelsExpand Collapse

APIEvaluationTestCase = object { archived_at, created_at, created_by_user_email, 15 more }

archived_at: optional string

created_at: optional string

created_by_user_email: optional string

created_by_user_id: optional string

dataset: optional object { created_at, dataset_name, dataset_uuid, 3 more }

created_at: optional string

Time created at.

formatdate-time

dataset_name: optional string

Name of the dataset.

dataset_uuid: optional string

UUID of the dataset.

file_size: optional string

The size of the dataset uploaded file in bytes.

formatuint64

has_ground_truth: optional boolean

Does the dataset have a ground truth column?

row_count: optional number

Number of rows in the dataset.

formatint64

dataset_name: optional string

dataset_uuid: optional string

description: optional string

latest_version_number_of_runs: optional number

metrics: optional array of APIEvaluationMetric

star_metric: optional APIStarMetric

test_case_uuid: optional string

total_runs: optional number

updated_at: optional string

updated_by_user_email: optional string

updated_by_user_id: optional string

version: optional number

APIStarMetric = object { metric_uuid, name, success_threshold, success_threshold_pct }

metric_uuid: optional string

success_threshold: optional number

The success threshold for the star metric. This is a value that the metric must reach to be considered successful.

formatfloat

success_threshold_pct: optional number

The success threshold for the star metric. This is a percentage value between 0 and 100.

formatint32

ModelsExpand Collapse

APILinkKnowledgeBaseOutput = object { agent }

Information about a linked knowledge base

agent: optional APIAgent

An Agent

AgentsVersions

List Agent Versions

get/v2/gen-ai/agents/{uuid}/versions

Rollback to Agent Version

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

Agents

Agents

ModelsExpand Collapse

AgentsAPI Keys

AgentsChat

AgentsChatCompletions

AgentsEvaluation Datasets

AgentsEvaluation Metrics

AgentsEvaluation MetricsAnthropic

AgentsEvaluation MetricsAnthropicKeys

AgentsEvaluation MetricsModels

AgentsEvaluation MetricsOpenAI

AgentsEvaluation MetricsOpenAIKeys

AgentsEvaluation MetricsWorkspaces

AgentsEvaluation MetricsWorkspacesAgents

AgentsEvaluation Runs

ModelsExpand Collapse

AgentsEvaluation Test Cases

ModelsExpand Collapse

AgentsFunctions

AgentsKnowledge Bases

ModelsExpand Collapse

AgentsRoutes

AgentsVersions