agents

Creates, updates, deletes, gets or lists an agents resource.

Overview

Name	agents
Type	Resource
Id	digitalocean.genai.agents

Fields

The following fields are returned by SELECT queries:

genai_get_agent

A successful response.

Name	Datatype	Description
name	string	Agent name (example: example name)
project_id	string	(example: 123e4567-e89b-12d3-a456-426614174000)
user_id	string (uint64)	Id of user that created the agent (example: 12345)
route_name	string	Route name (example: example name)
anthropic_api_key	object	Anthropic API Key Info
api_key_infos	array	Api key infos
api_keys	array	Api keys
chatbot	object	A Chatbot
chatbot_identifiers	array	Chatbot identifiers
child_agents	array	Child agents
conversation_logs_enabled	boolean	Whether conversation logs are enabled for the agent
created_at	string (date-time)	Creation date / time (example: 2023-01-01T00:00:00Z)
deployment	object	Description of deployment
description	string	Description of agent (example: example string)
functions	array
guardrails	array	The guardrails the agent is attached to
if_case	string	(example: example string)
instruction	string	Agent instruction. Instructions help your agent to perform its job effectively. See Write Effective Agent Instructions for best practices. (example: example string)
k	integer (int64)
knowledge_bases	array	Knowledge bases
logging_config	object
max_tokens	integer (int64)
mcp_servers	array	MCP (Model Context Protocol) servers attached to this agent
model	object	Description of a Model
model_provider_key	object
model_router	object	Model router
openai_api_key	object	OpenAI API Key Info
parent_agents	array	Parent agents
provide_citations	boolean	Whether the agent should provide in-response citations
reasoning_effort	string	The reasoning effort for the agent (example: example string)
region	string	Region code (example: example string)
retrieval_method	string	- 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) (default: RETRIEVAL_METHOD_UNKNOWN, example: RETRIEVAL_METHOD_UNKNOWN)
route_created_at	string (date-time)	Creation of route date / time (example: 2023-01-01T00:00:00Z)
route_created_by	string (uint64)	(example: 12345)
route_uuid	string	(example: 123e4567-e89b-12d3-a456-426614174000)
tags	array	Agent tag to organize related resources
temperature	number (float)
template	object	Represents an AgentTemplate entity
thinking_token_budget	integer (int64)	The thinking token budget for Anthropic extended thinking (0 = disabled)
top_p	number (float)
updated_at	string (date-time)	Last modified (example: 2023-01-01T00:00:00Z)
url	string	Access your agent under this url (example: example string)
uuid	string	Unique agent id (example: 123e4567-e89b-12d3-a456-426614174000)
version_hash	string	The latest version of the agent (example: example string)
vpc_egress_ips	array	VPC Egress IPs
vpc_uuid	string	(example: "12345678-1234-1234-1234-123456789012")
web_fetch_enabled	boolean	Whether this agent can use the built-in web_fetch tool.
web_search_enabled	boolean	Whether this agent can use the built-in web_search tool.
workspace	object

genai_list_agents_by_workspace

A successful response.

Name	Datatype	Description
agents	array
links	object	Links to other pages
meta	object	Meta information about the data set

genai_list_agents

A successful response.

Name	Datatype	Description
agents	array	Agents
links	object	Links to other pages
meta	object	Meta information about the data set

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
genai_get_agent	select	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.
genai_list_agents_by_workspace	select	workspace_uuid	only_deployed, page, per_page	To list all agents by a Workspace, send a GET request to /v2/gen-ai/workspaces/{workspace_uuid}/agents.
genai_list_agents	select		only_deployed, page, per_page	To list all agents, send a GET request to /v2/gen-ai/agents.
genai_create_agent	insert			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.
genai_update_agent	replace	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.
genai_update_agents_workspace	replace	workspace_uuid		To move all listed agents a given workspace, send a PUT request to /v2/gen-ai/workspaces/{workspace_uuid}/agents.
genai_delete_agent	delete	uuid		To delete an agent, send a DELETE request to /v2/gen-ai/agents/{uuid}.
genai_attach_agent_function	exec	agent_uuid		To create a function route for an agent, send a POST request to /v2/gen-ai/agents/{agent_uuid}/functions.
genai_update_agent_function	exec	agent_uuid, function_uuid		To update the function route, send a PUT request to /v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}.
genai_detach_agent_function	exec	agent_uuid, function_uuid		To delete a function route from an agent, send a DELETE request to /v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}.
genai_attach_agent_guardrails	exec	agent_uuid		To attach guardrails to an agent, send a POST request to /v2/gen-ai/agents/{agent_uuid}/guardrails.
genai_detach_agent_guardrail	exec	agent_uuid, guardrail_uuid		To detach a guardrail from an agent, send a DELETE request to /v2/gen-ai/agents/{agent_uuid}/guardrails/{guardrail_uuid}.
genai_attach_agent	exec	parent_agent_uuid, child_agent_uuid		To add an agent route to an agent, send a POST request to /v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid}.
genai_update_attached_agent	exec	parent_agent_uuid, child_agent_uuid		To update an agent route for an agent, send a PUT request to /v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid}.
genai_detach_agent	exec	parent_agent_uuid, child_agent_uuid		To delete an agent route from a parent agent, send a DELETE request to /v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid}.
genai_update_agent_deployment_visibility	exec	uuid		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.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
agent_uuid	string	The UUID of the agent. (example: "123e4567-e89b-12d3-a456-426614174000")
child_agent_uuid	string	Routed agent id (example: "123e4567-e89b-12d3-a456-426614174000")
function_uuid	string	The function route to be destroyed. This does not destroy the function itself. (example: "123e4567-e89b-12d3-a456-426614174000")
guardrail_uuid	string	The UUID of the guardrail to detach. (example: "123e4567-e89b-12d3-a456-426614174000")
parent_agent_uuid	string	Pagent agent id (example: "123e4567-e89b-12d3-a456-426614174000")
uuid	string	Unique id (example: "123e4567-e89b-12d3-a456-426614174000")
workspace_uuid	string	Workspace uuid to move agents to (example: "123e4567-e89b-12d3-a456-426614174000")
only_deployed	boolean	Only list agents that are deployed. (example: true)
page	integer	Page number. (example: 1)
per_page	integer	Items per page. (example: 1)

SELECT examples

genai_get_agent

To retrieve details of an agent, GET request to /v2/gen-ai/agents/{uuid}. The response body is a JSON object containing the agent.

SELECT
name,
project_id,
user_id,
route_name,
anthropic_api_key,
api_key_infos,
api_keys,
chatbot,
chatbot_identifiers,
child_agents,
conversation_logs_enabled,
created_at,
deployment,
description,
functions,
guardrails,
if_case,
instruction,
k,
knowledge_bases,
logging_config,
max_tokens,
mcp_servers,
model,
model_provider_key,
model_router,
openai_api_key,
parent_agents,
provide_citations,
reasoning_effort,
region,
retrieval_method,
route_created_at,
route_created_by,
route_uuid,
tags,
temperature,
template,
thinking_token_budget,
top_p,
updated_at,
url,
uuid,
version_hash,
vpc_egress_ips,
vpc_uuid,
web_fetch_enabled,
web_search_enabled,
workspace
FROM digitalocean.genai.agents
WHERE uuid = '{{ uuid }}' -- required
;

genai_list_agents_by_workspace

To list all agents by a Workspace, send a GET request to /v2/gen-ai/workspaces/{workspace_uuid}/agents.

SELECT
agents,
links,
meta
FROM digitalocean.genai.agents
WHERE workspace_uuid = '{{ workspace_uuid }}' -- required
AND only_deployed = '{{ only_deployed }}'
AND page = '{{ page }}'
AND per_page = '{{ per_page }}'
;

genai_list_agents

To list all agents, send a GET request to /v2/gen-ai/agents.

SELECT
agents,
links,
meta
FROM digitalocean.genai.agents
WHERE only_deployed = '{{ only_deployed }}'
AND page = '{{ page }}'
AND per_page = '{{ per_page }}'
;

INSERT examples

genai_create_agent

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.

INSERT INTO digitalocean.genai.agents (
anthropic_key_uuid,
description,
instruction,
knowledge_base_uuid,
mcp_servers,
model_provider_key_uuid,
model_router_uuid,
model_uuid,
name,
open_ai_key_uuid,
project_id,
reasoning_effort,
region,
router_preset_slug,
tags,
thinking_token_budget,
web_fetch_enabled,
web_search_enabled,
workspace_uuid
)
SELECT 
'{{ anthropic_key_uuid }}',
'{{ description }}',
'{{ instruction }}',
'{{ knowledge_base_uuid }}',
'{{ mcp_servers }}',
'{{ model_provider_key_uuid }}',
'{{ model_router_uuid }}',
'{{ model_uuid }}',
'{{ name }}',
'{{ open_ai_key_uuid }}',
'{{ project_id }}',
'{{ reasoning_effort }}',
'{{ region }}',
'{{ router_preset_slug }}',
'{{ tags }}',
{{ thinking_token_budget }},
{{ web_fetch_enabled }},
{{ web_search_enabled }},
'{{ workspace_uuid }}'
RETURNING
agent
;

Manifest

# Description fields are for documentation purposes
- name: agents
props:
  - name: anthropic_key_uuid
    value: "{{ anthropic_key_uuid }}"
    description: |
      Optional Anthropic API key ID to use with Anthropic models
  - name: description
    value: "{{ description }}"
    description: |
      A text description of the agent, not used in inference
  - name: instruction
    value: "{{ instruction }}"
    description: |
      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.
  - name: knowledge_base_uuid
    value:
      - "{{ knowledge_base_uuid }}"
    description: |
      Ids of the knowledge base(s) to attach to the agent
  - name: mcp_servers
    description: |
      MCP (Model Context Protocol) servers to attach to the agent
    value:
      - allowed_tools: "{{ allowed_tools }}"
        authorization: "{{ authorization }}"
        headers: "{{ headers }}"
        server_label: "{{ server_label }}"
        server_url: "{{ server_url }}"
  - name: model_provider_key_uuid
    value: "{{ model_provider_key_uuid }}"
  - name: model_router_uuid
    value: "{{ model_router_uuid }}"
  - name: model_uuid
    value: "{{ model_uuid }}"
    description: |
      Identifier for the foundation model.
  - name: name
    value: "{{ name }}"
    description: |
      Agent name
  - name: open_ai_key_uuid
    value: "{{ open_ai_key_uuid }}"
    description: |
      Optional OpenAI API key ID to use with OpenAI models
  - name: project_id
    value: "{{ project_id }}"
    description: |
      The id of the DigitalOcean project this agent will belong to
  - name: reasoning_effort
    value: "{{ reasoning_effort }}"
  - name: region
    value: "{{ region }}"
    description: |
      The DigitalOcean region to deploy your agent in
  - name: router_preset_slug
    value: "{{ router_preset_slug }}"
  - name: tags
    value:
      - "{{ tags }}"
    description: |
      Agent tag to organize related resources
  - name: thinking_token_budget
    value: {{ thinking_token_budget }}
  - name: web_fetch_enabled
    value: {{ web_fetch_enabled }}
    description: |
      Whether the agent can use the built-in web_fetch tool to retrieve content from public web pages.
  - name: web_search_enabled
    value: {{ web_search_enabled }}
    description: |
      Whether the agent can use the built-in web_search tool to search the public web for current information.
  - name: workspace_uuid
    value: "{{ workspace_uuid }}"
    description: |
      Identifier for the workspace

REPLACE examples

genai_update_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.

REPLACE digitalocean.genai.agents
SET 
agent_log_insights_enabled = {{ agent_log_insights_enabled }},
allowed_domains = '{{ allowed_domains }}',
anthropic_key_uuid = '{{ anthropic_key_uuid }}',
clear_mcp_servers = {{ clear_mcp_servers }},
conversation_logs_enabled = {{ conversation_logs_enabled }},
description = '{{ description }}',
instruction = '{{ instruction }}',
k = {{ k }},
max_tokens = {{ max_tokens }},
mcp_servers = '{{ mcp_servers }}',
model_provider_key_uuid = '{{ model_provider_key_uuid }}',
model_router_uuid = '{{ model_router_uuid }}',
model_uuid = '{{ model_uuid }}',
name = '{{ name }}',
open_ai_key_uuid = '{{ open_ai_key_uuid }}',
project_id = '{{ project_id }}',
provide_citations = {{ provide_citations }},
reasoning_effort = '{{ reasoning_effort }}',
retrieval_method = '{{ retrieval_method }}',
router_preset_slug = '{{ router_preset_slug }}',
tags = '{{ tags }}',
temperature = {{ temperature }},
thinking_token_budget = {{ thinking_token_budget }},
top_p = {{ top_p }},
uuid = '{{ uuid }}',
web_fetch_enabled = {{ web_fetch_enabled }},
web_search_enabled = {{ web_search_enabled }}
WHERE 
uuid = '{{ uuid }}' --required
RETURNING
agent;

genai_update_agents_workspace

To move all listed agents a given workspace, send a PUT request to /v2/gen-ai/workspaces/{workspace_uuid}/agents.

REPLACE digitalocean.genai.agents
SET 
agent_uuids = '{{ agent_uuids }}',
workspace_uuid = '{{ workspace_uuid }}'
WHERE 
workspace_uuid = '{{ workspace_uuid }}' --required
RETURNING
workspace;

DELETE examples

genai_delete_agent

To delete an agent, send a DELETE request to /v2/gen-ai/agents/{uuid}.

DELETE FROM digitalocean.genai.agents
WHERE uuid = '{{ uuid }}' --required
;

Lifecycle Methods

genai_attach_agent_function

To create a function route for an agent, send a POST request to /v2/gen-ai/agents/{agent_uuid}/functions.

EXEC digitalocean.genai.agents.genai_attach_agent_function 
@agent_uuid='{{ agent_uuid }}' --required 
@@json=
'{
"agent_uuid": "{{ agent_uuid }}", 
"description": "{{ description }}", 
"faas_name": "{{ faas_name }}", 
"faas_namespace": "{{ faas_namespace }}", 
"function_name": "{{ function_name }}", 
"input_schema": "{{ input_schema }}", 
"output_schema": "{{ output_schema }}"
}'
;

genai_update_agent_function

To update the function route, send a PUT request to /v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}.

EXEC digitalocean.genai.agents.genai_update_agent_function 
@agent_uuid='{{ agent_uuid }}' --required, 
@function_uuid='{{ function_uuid }}' --required 
@@json=
'{
"agent_uuid": "{{ agent_uuid }}", 
"description": "{{ description }}", 
"faas_name": "{{ faas_name }}", 
"faas_namespace": "{{ faas_namespace }}", 
"function_name": "{{ function_name }}", 
"function_uuid": "{{ function_uuid }}", 
"input_schema": "{{ input_schema }}", 
"output_schema": "{{ output_schema }}"
}'
;

genai_detach_agent_function

To delete a function route from an agent, send a DELETE request to /v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}.

EXEC digitalocean.genai.agents.genai_detach_agent_function 
@agent_uuid='{{ agent_uuid }}' --required, 
@function_uuid='{{ function_uuid }}' --required
;

genai_attach_agent_guardrails

To attach guardrails to an agent, send a POST request to /v2/gen-ai/agents/{agent_uuid}/guardrails.

EXEC digitalocean.genai.agents.genai_attach_agent_guardrails 
@agent_uuid='{{ agent_uuid }}' --required 
@@json=
'{
"agent_uuid": "{{ agent_uuid }}", 
"guardrails": "{{ guardrails }}"
}'
;

genai_detach_agent_guardrail

To detach a guardrail from an agent, send a DELETE request to /v2/gen-ai/agents/{agent_uuid}/guardrails/{guardrail_uuid}.

EXEC digitalocean.genai.agents.genai_detach_agent_guardrail 
@agent_uuid='{{ agent_uuid }}' --required, 
@guardrail_uuid='{{ guardrail_uuid }}' --required
;

genai_attach_agent

To add an agent route to an agent, send a POST request to /v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid}.

EXEC digitalocean.genai.agents.genai_attach_agent 
@parent_agent_uuid='{{ parent_agent_uuid }}' --required, 
@child_agent_uuid='{{ child_agent_uuid }}' --required 
@@json=
'{
"child_agent_uuid": "{{ child_agent_uuid }}", 
"if_case": "{{ if_case }}", 
"parent_agent_uuid": "{{ parent_agent_uuid }}", 
"route_name": "{{ route_name }}"
}'
;

genai_update_attached_agent

To update an agent route for an agent, send a PUT request to /v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid}.

EXEC digitalocean.genai.agents.genai_update_attached_agent 
@parent_agent_uuid='{{ parent_agent_uuid }}' --required, 
@child_agent_uuid='{{ child_agent_uuid }}' --required 
@@json=
'{
"child_agent_uuid": "{{ child_agent_uuid }}", 
"if_case": "{{ if_case }}", 
"parent_agent_uuid": "{{ parent_agent_uuid }}", 
"route_name": "{{ route_name }}", 
"uuid": "{{ uuid }}"
}'
;

genai_detach_agent

To delete an agent route from a parent agent, send a DELETE request to /v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid}.

EXEC digitalocean.genai.agents.genai_detach_agent 
@parent_agent_uuid='{{ parent_agent_uuid }}' --required, 
@child_agent_uuid='{{ child_agent_uuid }}' --required
;

genai_update_agent_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.

EXEC digitalocean.genai.agents.genai_update_agent_deployment_visibility 
@uuid='{{ uuid }}' --required 
@@json=
'{
"uuid": "{{ uuid }}", 
"visibility": "{{ visibility }}"
}'
;