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>",
  "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"
  ]
}
'

import requests

url = "https://api.langdock.com/agent/v1/create"

payload = {
    "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"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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']
  })
};

fetch('https://api.langdock.com/agent/v1/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.langdock.com/agent/v1/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.langdock.com/agent/v1/create"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"description\": \"<string>\",\n  \"temperature\": 0.5,\n  \"model\": \"<string>\",\n  \"capabilities\": {\n    \"webSearch\": true,\n    \"dataAnalyst\": true,\n    \"imageGeneration\": true\n  },\n  \"actions\": [\n    \"<unknown>\"\n  ],\n  \"vectorDb\": [\n    \"<unknown>\"\n  ],\n  \"knowledgeFolderIds\": [\n    \"<string>\"\n  ],\n  \"attachmentIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.langdock.com/agent/v1/create")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"description\": \"<string>\",\n  \"temperature\": 0.5,\n  \"model\": \"<string>\",\n  \"capabilities\": {\n    \"webSearch\": true,\n    \"dataAnalyst\": true,\n    \"imageGeneration\": true\n  },\n  \"actions\": [\n    \"<unknown>\"\n  ],\n  \"vectorDb\": [\n    \"<unknown>\"\n  ],\n  \"knowledgeFolderIds\": [\n    \"<string>\"\n  ],\n  \"attachmentIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.langdock.com/agent/v1/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"description\": \"<string>\",\n  \"temperature\": 0.5,\n  \"model\": \"<string>\",\n  \"capabilities\": {\n    \"webSearch\": true,\n    \"dataAnalyst\": true,\n    \"imageGeneration\": true\n  },\n  \"actions\": [\n    \"<unknown>\"\n  ],\n  \"vectorDb\": [\n    \"<unknown>\"\n  ],\n  \"knowledgeFolderIds\": [\n    \"<string>\"\n  ],\n  \"attachmentIds\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ]\n}"

response = http.request(request)
puts response.read_body

201

{
  "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

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	Accepted for compatibility. See warning below
canvas	boolean	No	Enable canvas capability (default: false)
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 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.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
• 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;
    canvasEnabled: boolean;
    extendedThinking: boolean;
    actions: Array<{
      actionId: string;
      requiresConfirmation: boolean;
    }>;
    inputFields: Array<{
      slug: string;
      type: string;
      label: string;
      description: string;
      required: boolean;
      order: number;
      options: string[];
      fileTypes: string[] | null;
      emailDomain: string | null;
    }>;
    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

Show child attributes

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

Show child attributes