pydo.genai.create_agent()

Generated on 3 Aug 2026 from pydo version v0.40.0

Copy page as Markdown View page as Markdown

Usage 

client.genai.create_agent(
    body={
        "anthropic_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
        "description": "\"My Agent Description\"",
        "instruction": "\"You are an agent who thinks deeply about the world\"",
        ...,
    },
)
Returns JSONRaises HttpResponseError

Description

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.

Parameters

anthropic_key_uuid string optional

Example: "12345678-1234-1234-1234-123456789012"

Optional Anthropic API key ID to use with Anthropic models

description string optional

Example: "My Agent Description"

A text description of the agent, not used in inference

instruction string optional

Example: "You are an agent who thinks deeply about the world"

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

knowledge_base_uuid array of strings optional

Example: ['example string']

Ids of the knowledge base(s) to attach to the agent

mcp_servers array of objects optional

MCP (Model Context Protocol) servers to attach to the agent

Show child properties
allowed_tools array of strings optional

Example: ['example string']

Optional list of allowed tool names to expose from this server

authorization string optional

Example: example string

Optional authorization header value for the MCP server

headers object optional

Optional additional headers to send to the MCP server

server_label string optional

Example: example string

A label identifying this MCP server

server_url string optional

Example: example string

The URL of the MCP server

model_provider_key_uuid string optional

Example: "12345678-1234-1234-1234-123456789012"

model_router_uuid string optional

Example: "12345678-1234-1234-1234-123456789012"

model_uuid string optional

Example: "12345678-1234-1234-1234-123456789012"

Identifier for the foundation model.

name string optional

Example: "My Agent"

Agent name

open_ai_key_uuid string optional

Example: "12345678-1234-1234-1234-123456789012"

Optional OpenAI API key ID to use with OpenAI models

project_id string optional

Example: "12345678-1234-1234-1234-123456789012"

The id of the DigitalOcean project this agent will belong to

reasoning_effort string optional

Example: "low"

region string optional

Example: "tor1"

The DigitalOcean region to deploy your agent in

router_preset_slug string optional

Example: "general"

tags array of strings optional

Example: ['example string']

Agent tag to organize related resources

thinking_token_budget integer optional

Example: 123

web_fetch_enabled boolean optional

Example: True

Whether the agent can use the built-in web_fetch tool to retrieve content from public web pages.

web_search_enabled boolean optional

Example: True

Whether the agent can use the built-in web_search tool to search the public web for current information.

workspace_uuid string optional

Example: 123e4567-e89b-12d3-a456-426614174000

Identifier for the workspace

Request Sample

Show Request Sample
import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

req = {
  "anthropic_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "description": "\"My Agent Description\"",
  "instruction": "\"You are an agent who thinks deeply about the world\"",
  "knowledge_base_uuid": [
    "example string"
  ],
  "mcp_servers": [
    {
      "allowed_tools": [
        "example string"
      ],
      "authorization": "example string",
      "server_label": "example string",
      "server_url": "example string"
    }
  ],
  "model_provider_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "model_router_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "model_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "name": "\"My Agent\"",
  "open_ai_key_uuid": "\"12345678-1234-1234-1234-123456789012\"",
  "project_id": "\"12345678-1234-1234-1234-123456789012\"",
  "reasoning_effort": "\"low\"",
  "region": "\"tor1\"",
  "router_preset_slug": "\"general\"",
  "tags": [
    "example string"
  ],
  "thinking_token_budget": 123,
  "web_fetch_enabled": True,
  "web_search_enabled": True,
  "workspace_uuid": "123e4567-e89b-12d3-a456-426614174000"
}

resp = client.genai.create_agent(body=req)

Response Example

Show Response Example
{
  "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": [],
    "api_keys": [],
    "chatbot": {
      "allowed_domains": [
        "example string"
      ],
      "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": [],
    "child_agents": [],
    "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": [],
    "guardrails": [],
    "if_case": "example string",
    "instruction": "example string",
    "k": 123,
    "knowledge_bases": [],
    "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,
    "mcp_servers": [],
    "model": {
      "capabilities": [
        "example string"
      ],
      "context_window": "12345",
      "created_at": "2023-01-01T00:00:00Z",
      "endpoints": [],
      "inference_name": "example name",
      "inference_version": "example string",
      "is_foundational": true,
      "kb_default_chunk_size": 123,
      "kb_max_chunk_size": 123,
      "kb_min_chunk_size": 123,
      "lifecycle_status": "example string",
      "name": "example name",
      "parameter_count": 123,
      "parent_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "reasoning_efforts": [
        "example string"
      ],
      "settings": [],
      "thinking": true,
      "type": "example string",
      "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"
    },
    "model_provider_key": {
      "api_key_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "provider": "MODEL_PROVIDER_DIGITALOCEAN",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    "model_router": {
      "created_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "name": "example name",
      "regions": [
        "example string"
      ],
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "name": "example name",
    "openai_api_key": {
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "deleted_at": "2023-01-01T00:00:00Z",
      "models": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    },
    "parent_agents": [],
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "provide_citations": true,
    "reasoning_effort": "example string",
    "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": [],
      "instruction": "example string",
      "k": 123,
      "knowledge_bases": [],
      "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,
      "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"
    },
    "thinking_token_budget": 123,
    "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",
    "vpc_egress_ips": [
      "example string"
    ],
    "vpc_uuid": "\"12345678-1234-1234-1234-123456789012\"",
    "web_fetch_enabled": true,
    "web_search_enabled": true,
    "workspace": {
      "agents": [],
      "created_at": "2023-01-01T00:00:00Z",
      "created_by": "12345",
      "created_by_email": "[email protected]",
      "deleted_at": "2023-01-01T00:00:00Z",
      "description": "example string",
      "evaluation_test_cases": [],
      "name": "example name",
      "updated_at": "2023-01-01T00:00:00Z",
      "uuid": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}

More Information

See /v2/gen-ai/agents in the API reference for additional detail on responses, headers, parameters, and more.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.