Creates a new agent
Agents API
Agent Create API
Create a new agent programmatically
POST
Creates a new agent
Documentation Index
Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
Use this file to discover all available pages before exploring further.
⚠️ Using our API via a dedicated deployment? Just replace
api.langdock.com with your deployment’s base URL: <deployment-url>/api/publicThis is the new Agents API with native Vercel AI SDK compatibility. If you’re using the legacy Assistants API, see the migration guide.
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 theactions array should contain:
actionId(required) - UUID of the action from an enabled integrationrequiresConfirmation(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 usinginputType: "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 |
TEXT- Single line text inputMULTI_LINE_TEXT- Multi-line text areaNUMBER- Numeric inputCHECKBOX- Boolean checkboxFILE- File uploadSELECT- Dropdown selectionDATE- Date pickerEMAIL- 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 theattachments array.
Examples
Creating a Basic Agent
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
createAgentspermission - Name - Must be between 1-80 characters
- Description - Maximum 500 characters
- Instruction - Maximum 40000 characters
- Creativity - Must be between 0 and 1
Important Notes
- 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
createdByandworkspaceIdare automatically set from your API key
Response Format
Success Response (201 Created)
Error Handling
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
API key as Bearer token. Format "Bearer YOUR_API_KEY"
Body
application/json
Maximum string length:
64Maximum string length:
16384Maximum string length:
256Required range:
0 <= x <= 1Maximum string length:
64Array of UUID strings identifying attachments for this message