Agent Create API

Create a new agent programmatically

POST /agent/v1/create

Creates a new agent

cURL

curl --request POST \
  --url https://api.langdock.com/agent/v1/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "instruction": "<string>",
  "inputType": "PROMPT",
  "emoji": "<string>",
  "model": "<string>",
  "creativity": 0.3,
  "conversationStarters": [],
  "actions": [],
  "inputFields": [],
  "webSearch": false,
  "imageGeneration": false,
  "dataAnalyst": false,
  "extendedThinking": false,
  "attachments": [],
  "knowledgeFolderIds": []
}
'

201

{
  "status": "success",
  "message": "<string>",
  "agent": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "description": "<string>",
    "instruction": "<string>",
    "emojiIcon": "<string>",
    "model": "<string>",
    "temperature": 0.5,
    "conversationStarters": [
      "<string>"
    ],
    "inputType": "PROMPT",
    "webSearchEnabled": true,
    "imageGenerationEnabled": true,
    "canvasEnabled": true,
    "extendedThinking": true,
    "actions": [
      {
        "actionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "requiresConfirmation": true
      }
    ],
    "inputFields": [
      {
        "type": "TEXT",
        "label": "<string>",
        "description": "<string>",
        "required": true,
        "order": 1
      }
    ],
    "attachments": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "knowledgeFolderIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}

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

Before You Start

• API key scope: Requires an API key with the Agent API scope. Created agents are automatically shared with the API key for use in chat completions.
• Legacy Assistants API: This is the new Agents API with native Vercel AI SDK compatibility. If you’re using the legacy Assistants API, see the migration guide.

Base URL

https://api.langdock.com/agent/v1/create

Dedicated deployments

Replace api.langdock.com with <your-deployment-url>/api/public in all requests.

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 800 chars)
emoji	string	No	Emoji icon for the agent (max 16 chars, e.g., ”🤖“)
instruction	string	No	System prompt/instructions for the agent (max 50000 chars)
inputType	string	No	Input type: “PROMPT”, “STRUCTURED”, “INTEGRATION”, “SCHEDULED”, or “WEBHOOK” (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 up to 50 attachment UUIDs to include with the agent
knowledgeFolderIds	string[]	No	Array of Folder 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	Accepted for compatibility. See warning below
extendedThinking	boolean	No	Enable extended thinking mode (default: false)

The dataAnalyst parameter is deprecated and has no effect. Requests that include it still succeed for backward compatibility, but Langdock ignores the value and does not enable file or code execution. Omit this parameter from new integrations.

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 and MULTI_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
• MULTI_SELECT - Multi-select
• 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.langdock.com/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"
      ],
      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
• Folders - 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 800 characters
• Instruction - Maximum 50000 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 Langdock 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 | null;
    instruction: string | null;
    emojiIcon: string | null;
    model: string | null;
    temperature: number;
    conversationStarters: string[];
    inputType: "PROMPT" | "STRUCTURED" | "INTEGRATION" | "SCHEDULED" | "WEBHOOK";
    webSearchEnabled: boolean;
    imageGenerationEnabled: boolean;
    canvasEnabled: boolean;
    extendedThinking: boolean;
    actions: Array<{
      actionId: string;
      requiresConfirmation: boolean;
    }>;
    inputFields: Array<{
      type: "TEXT" | "MULTI_LINE_TEXT" | "NUMBER" | "CHECKBOX" | "FILE" | "SELECT" | "MULTI_SELECT" | "DATE" | "EMAIL";
      label: string;
      description: string | null;
      required: boolean;
      order: number;
    }>;
    attachments: string[];
    knowledgeFolderIds: string[];
    owner: {
      id: string;
      name: string | null;
      email: string;
    } | null;
    createdAt: string;
    updatedAt: string;
  };
}

Error Handling

try {
  const response = await axios.post('https://api.langdock.com/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;
    }
  }
}

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

Authorizations

Authorization · string · header · required

API key as Bearer token. Format "Bearer YOUR_API_KEY"

Body

application/json

name · string · required

Name of the agent or assistant

Required string length: 1 - 80

description · string

Description of what the agent or assistant does. Send an empty string to clear it during an update.

Maximum string length: 800

instruction · string

System prompt or instructions. Send an empty string to clear it during an update.

Maximum string length: 50000

inputType · enum<string> · default: PROMPT

Input type

Available options: PROMPT, STRUCTURED, INTEGRATION, SCHEDULED, WEBHOOK

emoji · string | null

Emoji icon

Maximum string length: 16

model · string

Model deployment name

creativity · number · default: 0.3

Temperature for response generation

Required range: 0 <= x <= 1

conversationStarters · string[]

Suggested prompts

Maximum array length: 20

Required string length: 1 - 255

actions · object[]

Actions that the agent or assistant can use

Show child attributes

inputFields · object[]

Form fields for STRUCTURED input

Show child attributes

webSearch · boolean · default: false

Enable web search

imageGeneration · boolean · default: false

Enable image generation

dataAnalyst · boolean · default: false · deprecated

Deprecated. Accepted for compatibility and ignored.

extendedThinking · boolean · default: false

Enable extended thinking

attachments · string<uuid>[]

Attachment UUIDs

Maximum array length: 50

knowledgeFolderIds · string<uuid>[]

Folder UUIDs

Response

201 - application/json

Agent created successfully

status · enum<string> · required

Available options: success

message · string · required

agent · object · required

Show child attributes