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

List

API Reference
Agents
List Agents
agents.list(AgentListParams**kwargs) -> AgentListResponse
get/v2/gen-ai/agents

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

ParametersExpand Collapse
only_deployed: Optional[bool]

Only list agents that are deployed.

page: Optional[int]

Page number.

per_page: Optional[int]

Items per page.

ReturnsExpand Collapse
class AgentListResponse: …

List of Agents

agents: Optional[List[Agent]]

Agents

chatbot: Optional[AgentChatbot]

A Chatbot

button_background_color: Optional[str]
name: Optional[str]

Name of chatbot

primary_color: Optional[str]
secondary_color: Optional[str]
starting_message: Optional[str]
chatbot_identifiers: Optional[List[AgentChatbotIdentifier]]

Chatbot identifiers

agent_chatbot_identifier: Optional[str]

Agent chatbot identifier

created_at: Optional[datetime]

Creation date / time

formatdate-time
deployment: Optional[AgentDeployment]

Description of deployment

created_at: Optional[datetime]

Creation date / time

formatdate-time
name: Optional[str]

Name

status: Optional[Literal["STATUS_UNKNOWN", "STATUS_WAITING_FOR_DEPLOYMENT", "STATUS_DEPLOYING", 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[datetime]

Last modified

formatdate-time
url: Optional[str]

Access your deployed agent here

uuid: Optional[str]

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[str]

Description of agent

if_case: Optional[str]

Instructions to the agent on how to use the route

instruction: Optional[str]

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

k: Optional[int]

How many results should be considered from an attached knowledge base

formatint64
max_tokens: Optional[int]

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: Optional[APIAgentModel]

Description of a Model

name: Optional[str]

Agent name

project_id: Optional[str]

The DigitalOcean project ID associated with the agent

provide_citations: Optional[bool]

Whether the agent should provide in-response citations

region: Optional[str]

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[datetime]

Creation of route date / time

formatdate-time
route_created_by: Optional[str]

Id of user that created the route

formatuint64
route_name: Optional[str]

Route name

route_uuid: Optional[str]

Route uuid

tags: Optional[List[str]]

A set of abitrary tags to organize your agent

temperature: Optional[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.

formatfloat
template: Optional[AgentTemplate]

Represents an AgentTemplate entity

created_at: Optional[datetime]

The agent template's creation date

formatdate-time
description: Optional[str]

Deprecated - Use summary instead

guardrails: Optional[List[AgentTemplateGuardrail]]

List of guardrails associated with the agent template

priority: Optional[int]

Priority of the guardrail

formatint32
uuid: Optional[str]

Uuid of the guardrail

instruction: Optional[str]

Instructions for the agent template

k: Optional[int]

The 'k' value for the agent template

formatint64
knowledge_bases: Optional[List[APIKnowledgeBase]]

List of knowledge bases associated with the agent template

added_to_agent_at: Optional[datetime]

Time when the knowledge base was added to the agent

formatdate-time
created_at: Optional[datetime]

Creation date / time

formatdate-time
database_id: Optional[str]
embedding_model_uuid: Optional[str]
is_public: Optional[bool]

Whether the knowledge base is public or not

last_indexing_job: Optional[APIIndexingJob]

IndexingJob description

name: Optional[str]

Name of knowledge base

project_id: Optional[str]
region: Optional[str]

Region code

tags: Optional[List[str]]

Tags to organize related resources

updated_at: Optional[datetime]

Last modified

formatdate-time
user_id: Optional[str]

Id of user that created the knowledge base

formatint64
uuid: Optional[str]

Unique id for knowledge base

long_description: Optional[str]

The long description of the agent template

max_tokens: Optional[int]

The max_tokens setting for the agent template

formatint64
model: Optional[APIAgentModel]

Description of a Model

name: Optional[str]

Name of the agent template

short_description: Optional[str]

The short description of the agent template

summary: Optional[str]

The summary of the agent template

tags: Optional[List[str]]

List of tags associated with the agent template

temperature: Optional[float]

The temperature setting for the agent template

formatfloat
template_type: Optional[Literal["AGENT_TEMPLATE_TYPE_STANDARD", "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[float]

The top_p setting for the agent template

formatfloat
updated_at: Optional[datetime]

The agent template's last updated date

formatdate-time
uuid: Optional[str]

Unique id

top_p: Optional[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.

formatfloat
updated_at: Optional[datetime]

Last modified

formatdate-time
url: Optional[str]

Access your agent under this url

user_id: Optional[str]

Id of user that created the agent

formatuint64
uuid: Optional[str]

Unique agent id

version_hash: Optional[str]

The latest version of the agent

Links to other pages

meta: Optional[APIMeta]

Meta information about the data set

from gradient import Gradient

client = Gradient()
agents = client.agents.list()
print(agents.agents)
{
  "agents": [
    {
      "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"
        }
      ],
      "created_at": "2021-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": "This is a chatbot that can help you with your questions.",
      "if_case": "if talking about the weather use this route",
      "instruction": "Hello, how can I help you?",
      "k": 5,
      "max_tokens": 100,
      "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": "My Agent",
      "project_id": "12345678-1234-1234-1234-123456789012",
      "provide_citations": true,
      "region": "\"tor1\"",
      "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
      "route_created_at": "2021-01-01T00:00:00Z",
      "route_created_by": "12345678",
      "route_name": "Route Name",
      "route_uuid": "\"12345678-1234-1234-1234-123456789012\"",
      "tags": [
        "example string"
      ],
      "temperature": 0.5,
      "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": 0.9,
      "updated_at": "2021-01-01T00:00:00Z",
      "url": "https://example.com/agent",
      "user_id": "12345678",
      "uuid": "\"12345678-1234-1234-1234-123456789012\"",
      "version_hash": "example string"
    }
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}
Returns Examples
{
  "agents": [
    {
      "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"
        }
      ],
      "created_at": "2021-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": "This is a chatbot that can help you with your questions.",
      "if_case": "if talking about the weather use this route",
      "instruction": "Hello, how can I help you?",
      "k": 5,
      "max_tokens": 100,
      "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": "My Agent",
      "project_id": "12345678-1234-1234-1234-123456789012",
      "provide_citations": true,
      "region": "\"tor1\"",
      "retrieval_method": "RETRIEVAL_METHOD_UNKNOWN",
      "route_created_at": "2021-01-01T00:00:00Z",
      "route_created_by": "12345678",
      "route_name": "Route Name",
      "route_uuid": "\"12345678-1234-1234-1234-123456789012\"",
      "tags": [
        "example string"
      ],
      "temperature": 0.5,
      "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": 0.9,
      "updated_at": "2021-01-01T00:00:00Z",
      "url": "https://example.com/agent",
      "user_id": "12345678",
      "uuid": "\"12345678-1234-1234-1234-123456789012\"",
      "version_hash": "example string"
    }
  ],
  "links": {
    "pages": {
      "first": "example string",
      "last": "example string",
      "next": "example string",
      "previous": "example string"
    }
  },
  "meta": {
    "page": 123,
    "pages": 123,
    "total": 123
  }
}