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)
model	object	Description of a Model
openai_api_key	object	OpenAI API Key Info
parent_agents	array	Parent agents
provide_citations	boolean	Whether the agent should provide in-response citations
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 (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
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)
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	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 id of the agent the function route belongs to. (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")
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,
model,
openai_api_key,
parent_agents,
provide_citations,
region,
retrieval_method,
route_created_at,
route_created_by,
route_uuid,
tags,
temperature,
template,
top_p,
updated_at,
url,
uuid,
version_hash,
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 (
data__anthropic_key_uuid,
data__description,
data__instruction,
data__knowledge_base_uuid,
data__model_uuid,
data__name,
data__open_ai_key_uuid,
data__project_id,
data__region,
data__tags
)
SELECT 
'{{ anthropic_key_uuid }}',
'{{ description }}',
'{{ instruction }}',
'{{ knowledge_base_uuid }}',
'{{ model_uuid }}',
'{{ name }}',
'{{ open_ai_key_uuid }}',
'{{ project_id }}',
'{{ region }}',
'{{ tags }}'
RETURNING
agent
;

Manifest

# Description fields are for documentation purposes
- name: agents
  props:
    - name: anthropic_key_uuid
      value: string
      description: >
        Optional Anthropic API key ID to use with Anthropic models
        
    - name: description
      value: string
      description: >
        A text description of the agent, not used in inference
        
    - name: instruction
      value: string
      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: array
      description: >
        Ids of the knowledge base(s) to attach to the agent
        
    - name: model_uuid
      value: string
      description: >
        Identifier for the foundation model.
        
    - name: name
      value: string
      description: >
        Agent name
        
    - name: open_ai_key_uuid
      value: string
      description: >
        Optional OpenAI API key ID to use with OpenAI models
        
    - name: project_id
      value: string
      description: >
        The id of the DigitalOcean project this agent will belong to
        
    - name: region
      value: string
      description: >
        The DigitalOcean region to deploy your agent in
        
    - name: tags
      value: array
      description: >
        Agent tag to organize related resources
        

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 
data__agent_log_insights_enabled = {{ agent_log_insights_enabled }},
data__anthropic_key_uuid = '{{ anthropic_key_uuid }}',
data__conversation_logs_enabled = {{ conversation_logs_enabled }},
data__description = '{{ description }}',
data__instruction = '{{ instruction }}',
data__k = {{ k }},
data__max_tokens = {{ max_tokens }},
data__model_uuid = '{{ model_uuid }}',
data__name = '{{ name }}',
data__open_ai_key_uuid = '{{ open_ai_key_uuid }}',
data__project_id = '{{ project_id }}',
data__provide_citations = {{ provide_citations }},
data__retrieval_method = '{{ retrieval_method }}',
data__tags = '{{ tags }}',
data__temperature = {{ temperature }},
data__top_p = {{ top_p }},
data__uuid = '{{ uuid }}'
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 
data__agent_uuids = '{{ agent_uuids }}',
data__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

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 }}"
}';