dots.v2.genAi.agents.post()

Generated on 13 Nov 2026 from DoTs version v1.24.0

Usage

client.v2.genAi.agents.post(body: ApiCreateAgentInputPublic, requestConfiguration?: RequestConfiguration<object>): Promise<undefined | ApiCreateAgentOutput>

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

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

knowledgeBaseUuid array of strings optional

Example: ["example string"]

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

mcpServers array of objects optional

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

Show child properties
allowedTools 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

serverLabel string optional

Example: example string

A label identifying this MCP server

serverUrl string optional

Example: example string

The URL of the MCP server

modelProviderKeyUuid string optional

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

modelRouterUuid string optional

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

modelUuid string optional

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

Identifier for the foundation model.

name string optional

Example: "My Agent"

Agent name

openAiKeyUuid string optional

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

Optional OpenAI API key ID to use with OpenAI models

projectId string optional

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

The id of the DigitalOcean project this agent will belong to

reasoningEffort string optional

Example: "low"

region string optional

Example: "tor1"

The DigitalOcean region to deploy your agent in

routerPresetSlug string optional

Example: "general"

tags array of strings optional

Example: ["example string"]

Agent tag to organize related resources

thinkingTokenBudget integer optional

Example: 123

webFetchEnabled boolean optional

Example: true

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

webSearchEnabled boolean optional

Example: true

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

workspaceUuid string optional

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

Identifier for the workspace

Request Sample

Show Request Sample
import { FetchRequestAdapter } from "@microsoft/kiota-http-fetchlibrary";
import {
    createDigitalOceanClient,
    DigitalOceanApiKeyAuthenticationProvider,
} from "@digitalocean/dots";

const authProvider = new DigitalOceanApiKeyAuthenticationProvider(process.env.DIGITALOCEAN_TOKEN!);
const adapter = new FetchRequestAdapter(authProvider);
const client = createDigitalOceanClient(adapter);

const response = await client.v2.genAi.agents.post({
    anthropicKeyUuid: "\"12345678-1234-1234-1234-123456789012\"",
    description: "\"My Agent Description\"",
    instruction: "\"You are an agent who thinks deeply about the world\"",
    knowledgeBaseUuid: [
        "example string",
    ],
    mcpServers: [
        {
            allowedTools: [
                "example string",
            ],
            authorization: "example string",
            serverLabel: "example string",
            serverUrl: "example string",
        },
    ],
    modelProviderKeyUuid: "\"12345678-1234-1234-1234-123456789012\"",
    modelRouterUuid: "\"12345678-1234-1234-1234-123456789012\"",
    modelUuid: "\"12345678-1234-1234-1234-123456789012\"",
    name: "\"My Agent\"",
    openAiKeyUuid: "\"12345678-1234-1234-1234-123456789012\"",
    projectId: "\"12345678-1234-1234-1234-123456789012\"",
    reasoningEffort: "\"low\"",
    region: "\"tor1\"",
    routerPresetSlug: "\"general\"",
    tags: [
        "example string",
    ],
    thinkingTokenBudget: 123,
    webFetchEnabled: true,
    webSearchEnabled: true,
    workspaceUuid: "123e4567-e89b-12d3-a456-426614174000",
});

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.