Agent Create API

Create a new agent programmatically

Agent Create API

Create a new agent programmatically

⚠️ Using our API via a dedicated deployment? Just replace api.odeus.ai with your deployment's base URL: <deployment-url>/api/public

This is the new Agents API with native Vercel AI SDK compatibility. If you're using the legacy Assistants API, see the migration guide.

Creates a new agent in your workspace programmatically. The created agent can be used via the chat completions endpoint or accessed through the Odeus UI.

Requires an API key with the AGENT_API scope. Created agents are automatically shared with the API key for use in chat completions.

Request Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Name of the agent (1-80 characters)
`description`	string	No	Description of what the agent does (max 500 chars)
`emoji`	string	No	Emoji icon for the agent (max 16 chars, e.g., "🤖")
`instruction`	string	No	System prompt/instructions for the agent (max 40000 chars)
`inputType`	string	No	Input type: "PROMPT" or "STRUCTURED" (default: "PROMPT")
`model`	string	No	Model identifier to use (deployment name from the Models API). Uses workspace default if not provided
`creativity`	number	No	Temperature between 0-1 (default: 0.3)
`conversationStarters`	string[]	No	Array of suggested prompts to help users get started (max 20, each 1-255 chars)
`actions`	array	No	Array of action objects for custom integrations
`inputFields`	array	No	Array of form field definitions (for STRUCTURED input type)
`attachments`	string[]	No	Array of attachment UUIDs to include with the agent
`webSearch`	boolean	No	Enable web search capability (default: false)
`imageGeneration`	boolean	No	Enable image generation capability (default: false)
`dataAnalyst`	boolean	No	Enable code interpreter capability (default: false)
`canvas`	boolean	No	Enable canvas capability (default: false)
`extendedThinking`	boolean	No	Enable extended thinking mode (default: false)

Actions Configuration

Each action in the actions array should contain:

actionId (required) - UUID of the action from an enabled integration
requiresConfirmation (optional) - Whether to require user confirmation before executing (default: true)

Only actions from integrations enabled in your workspace can be used.

Input Fields Configuration

When using inputType: "STRUCTURED", you can define form fields in the inputFields array:

Field	Type	Required	Description
`slug`	string	Yes	Unique identifier for the field
`type`	string	Yes	Field type (see supported types below)
`label`	string	Yes	Display label for the field
`description`	string	No	Help text for the field
`required`	boolean	No	Whether the field is required (default: false)
`order`	number	Yes	Display order (0-indexed)
`options`	string[]	No	Options for SELECT type fields
`fileTypes`	string	No	Allowed file types for FILE type fields (nullable)
`emailDomain`	string	No	Allowed email domain for EMAIL type fields

Supported Field Types:

TEXT - Single line text input
MULTI_LINE_TEXT - Multi-line text area
NUMBER - Numeric input
CHECKBOX - Boolean checkbox
FILE - File upload
SELECT - Dropdown selection
DATE - Date picker
EMAIL - Email address

Obtaining Attachment IDs

To include attachments with your agent, first upload files using the Upload Attachment API. This will return attachment UUIDs that you can include in the attachments array.

Examples

Creating a Basic Agent

const axios = require("axios");

async function createBasicAgent() {
  const response = await axios.post(
    "https://api.odeus.ai/agent/v1/create",
    {
      name: "Document Analyzer",
      description: "Analyzes and summarizes documents",
      emoji: "📄",
      instruction: "You are a helpful agent that analyzes documents and provides clear summaries of key information.",
      creativity: 0.5,
      conversationStarters: [
        "Summarize this document",
        "What are the key points?",
        "Extract action items"
      ],
      dataAnalyst: true,
      webSearch: false
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      }
    }
  );

  console.log("Agent created:", response.data.agent.id);
}

Validation Rules

The API enforces several validation rules:

Model - Must be in your workspace's active models list
Actions - Must belong to integrations enabled in your workspace
Attachments - Must exist in your workspace and not be deleted
Permissions - Your API key must have the createAgents permission
Name - Must be between 1-80 characters
Description - Maximum 500 characters
Instruction - Maximum 40000 characters
Creativity - Must be between 0 and 1

Important Notes

Pre-selected OAuth connections are not supported via the API. Users must configure OAuth connections through the Odeus UI.

Created agents are automatically shared with your API key for use in chat completions
The API key creator becomes the owner and can manage the agent in the UI
Attachments are bidirectionally linked to the agent
createdBy and workspaceId are automatically set from your API key

Response Format

Success Response (201 Created)

{
  status: "success";
  message: "Agent created successfully";
  agent: {
    id: string;
    name: string;
    description: string;
    instruction: string;
    emojiIcon: string;
    model: string;
    temperature: number;
    conversationStarters: string[];
    inputType: "PROMPT" | "STRUCTURED";
    webSearchEnabled: boolean;
    imageGenerationEnabled: boolean;
    codeInterpreterEnabled: boolean;
    canvasEnabled: boolean;
    extendedThinking: boolean;
    actions: Array&lt;{
      actionId: string;
      requiresConfirmation: boolean;
    }&gt;;
    inputFields: Array&lt;{
      slug: string;
      type: string;
      label: string;
      description: string;
      required: boolean;
      order: number;
      options: string[];
      fileTypes: string[] | null;
      emailDomain: string | null;
    }&gt;;
    attachments: string[];
    createdAt: string;
    updatedAt: string;
  };
}

Error Handling

try {
  const response = await axios.post('https://api.odeus.ai/agent/v1/create', ...);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error('Invalid parameters or resource not found:', error.response.data.message);
        break;
      case 401:
        console.error('Invalid or missing API key');
        break;
      case 403:
        console.error('Insufficient permissions - requires AGENT_API scope');
        break;
      case 429:
        console.error('Rate limit exceeded');
        break;
      case 500:
        console.error('Server error');
        break;
    }
  }
}

Odeus intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on API Key Best Practices.

OpenAPI

openapi: 3.0.0
info:
  title: Odeus API
  version: 3.0.0
servers:
  - url: https://api.odeus.ai
security:
  - bearerAuth: []
paths:
  /agent/v1/create:
    post:
      tags:
        - Agent Build
      summary: Creates a new agent
      description: Creates a new agent in your workspace programmatically.
      operationId: createAgentV2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Assistant'
      responses:
        '201':
          description: Agent created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  agent:
                    $ref: '#/components/schemas/Assistant'
components:
  schemas:
    Assistant:
      type: object
      required:
        - name
        - instructions
      properties:
        name:
          type: string
          maxLength: 64
        description:
          type: string
          maxLength: 256
        instructions:
          type: string
          maxLength: 16384
        temperature:
          type: number
          minimum: 0
          maximum: 1
        model:
          type: string
          maxLength: 64
        capabilities:
          type: object
          properties:
            webSearch:
              type: boolean
            dataAnalyst:
              type: boolean
            imageGeneration:
              type: boolean
        actions:
          type: array
          items: fcf0fd67-fd0e-4a00-b735-68e73c7eacb2
        vectorDb:
          type: array
          items: f0c033f7-804b-4122-8a48-a9c1f45fd570
        knowledgeFolderIds:
          type: array
          items:
            type: string
        attachmentIds:
          type: array
          items:
            type: string
            format: uuid
          description: Array of UUID strings identifying attachments for this message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"