> ## 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 | 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 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"
],
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)
```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;
codeInterpreterEnabled: 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
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
imageGeneration:
type: boolean
actions:
type: array
items: fdb10eff-76fb-404f-a98e-571420b27064
vectorDb:
type: array
items: 03eca062-ada7-44b8-bb90-cf5689d693cd
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"
````