Skip to main content
POST
/
agent
/
v1
/
create
Creates a new agent
curl --request POST \
  --url https://api.langdock.com/agent/v1/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "instructions": "<string>",
  "description": "<string>",
  "temperature": 0.5,
  "model": "<string>",
  "capabilities": {
    "webSearch": true,
    "dataAnalyst": true,
    "imageGeneration": true
  },
  "actions": [
    "<unknown>"
  ],
  "vectorDb": [
    "<unknown>"
  ],
  "knowledgeFolderIds": [
    "<string>"
  ],
  "attachmentIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'
{
  "status": "<string>",
  "message": "<string>",
  "agent": {
    "name": "<string>",
    "instructions": "<string>",
    "description": "<string>",
    "temperature": 0.5,
    "model": "<string>",
    "capabilities": {
      "webSearch": true,
      "dataAnalyst": true,
      "imageGeneration": true
    },
    "actions": [
      "<unknown>"
    ],
    "vectorDb": [
      "<unknown>"
    ],
    "knowledgeFolderIds": [
      "<string>"
    ],
    "attachmentIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ]
  }
}
⚠️ Using our API via a dedicated deployment? Just replace api.langdock.com 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 Langdock 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

ParameterTypeRequiredDescription
namestringYesName of the agent (1-80 characters)
descriptionstringNoDescription of what the agent does (max 500 chars)
emojistringNoEmoji icon for the agent (max 16 chars, e.g., ”🤖“)
instructionstringNoSystem prompt/instructions for the agent (max 40000 chars)
inputTypestringNoInput type: “PROMPT” or “STRUCTURED” (default: “PROMPT”)
modelstringNoModel identifier to use (deployment name from the Models API). Uses workspace default if not provided
creativitynumberNoTemperature between 0-1 (default: 0.3)
conversationStartersstring[]NoArray of suggested prompts to help users get started (max 20, each 1-255 chars)
actionsarrayNoArray of action objects for custom integrations
inputFieldsarrayNoArray of form field definitions (for STRUCTURED input type)
attachmentsstring[]NoArray of attachment UUIDs to include with the agent
webSearchbooleanNoEnable web search capability (default: false)
imageGenerationbooleanNoEnable image generation capability (default: false)
dataAnalystbooleanNoEnable code interpreter capability (default: false)
canvasbooleanNoEnable canvas capability (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:
FieldTypeRequiredDescription
slugstringYesUnique identifier for the field
typestringYesField type (see supported types below)
labelstringYesDisplay label for the field
descriptionstringNoHelp text for the field
requiredbooleanNoWhether the field is required (default: false)
ordernumberYesDisplay order (0-indexed)
optionsstring[]NoOptions for SELECT type fields
fileTypesstringNoAllowed file types for FILE type fields (nullable)
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

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"
      ],
      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 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;
    instruction: string;
    emojiIcon: string;
    model: string;
    temperature: number;
    conversationStarters: string[];
    inputType: "PROMPT" | "STRUCTURED";
    webSearchEnabled: boolean;
    imageGenerationEnabled: boolean;
    codeInterpreterEnabled: boolean;
    canvasEnabled: boolean;
    actions: Array<{
      actionId: string;
      requiresConfirmation: boolean;
    }>;
    inputFields: Array<{
      type: string;
      label: string;
      description: string;
      required: boolean;
      order: number;
    }>;
    attachments: string[];
    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
Maximum string length: 64
instructions
string
required
Maximum string length: 16384
description
string
Maximum string length: 256
temperature
number
Required range: 0 <= x <= 1
model
string
Maximum string length: 64
capabilities
object
actions
any[]
vectorDb
any[]
knowledgeFolderIds
string[]
attachmentIds
string<uuid>[]

Array of UUID strings identifying attachments for this message

Response

201 - application/json

Agent created successfully

status
string
message
string
agent
object