> ## 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.
# Agent Create API
> Create a new agent programmatically
**⚠️ Using our API via a dedicated deployment?** Just replace `api.langdock.com` with your deployment's base 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](/en/developer/assistants-api/assistant-to-agent-migration).
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](/en/developer/agents-api/agent-models)). 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](/en/developer/agents-api/upload-attachments). This will return attachment UUIDs that you can include in the `attachments` array.
## Examples
### Creating a Basic Agent
```javascript theme={null}
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)
```typescript theme={null}
{
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
```typescript theme={null}
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](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
## OpenAPI
````yaml POST /agent/v1/create
openapi: 3.0.0
info:
title: Langdock API
version: 3.0.0
servers:
- url: https://api.langdock.com
description: Production
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
deprecated: true
description: Deprecated. Accepted for compatibility and ignored.
imageGeneration:
type: boolean
actions:
type: array
items: 7d19e95b-21e8-417f-995e-24a8f5651c16
vectorDb:
type: array
items: 48adcef5-fb6f-434d-894d-ad23cdeb3651
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"
````