> ## 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
> Einen neuen Agenten programmatisch erstellen
Erstellt einen neuen Agenten in deinem Workspace programmatisch. Der erstellte Agent kann über den Chat-Completions-Endpunkt verwendet oder über die Langdock-Benutzeroberfläche aufgerufen werden.
## Bevor du startest
* **API-Key-Scope**: Erfordert einen API-Schlüssel mit dem **Agenten API**-Scope. Erstellte Agenten werden automatisch mit dem API-Schlüssel geteilt, um sie in Chat-Completions zu verwenden.
* **Veraltete Assistants API**: Dies ist die neue Agents API mit nativer Vercel AI SDK Kompatibilität. Wenn du die veraltete Assistants API verwendest, siehe den [Migrations-Guide](/de/developer/agents-api/assistant-to-agent-migration).
## Basis-URL
```
https://api.langdock.com/agent/v1/create
```
**Dedicated Deployments**
Ersetze `api.langdock.com` durch `/api/public` in allen Anfragen.
## Parameter
| Parameter | Typ | Erforderlich | Beschreibung |
| - | - | - | - |
| `name` | string | Ja | Name des Agenten (1-80 Zeichen) |
| `description` | string | Nein | Beschreibung der Agentenfunktion (max. 800 Zeichen) |
| `emoji` | string | Nein | Emoji-Icon für den Agenten (max. 16 Zeichen, z.B. "🤖") |
| `instruction` | string | Nein | Systemanweisung/Instruktionen für den Agenten (max. 50000 Zeichen) |
| `inputType` | string | Nein | Eingabetyp: "PROMPT", "STRUCTURED", "INTEGRATION", "SCHEDULED" oder "WEBHOOK" (Standard: "PROMPT") |
| `model` | string | Nein | `id` von der [Models API](/de/developer/agents-api/agent-models). Eindeutige Namen und Anthropic-Aliase bleiben gültig. Verwendet Workspace-Standard wenn nicht angegeben |
| `creativity` | number | Nein | Temperatur zwischen 0-1 (Standard: 0.3) |
| `conversationStarters` | string\[] | Nein | Array von vorgeschlagenen Prompts zum Einstieg (max. 20, je 1-255 Zeichen) |
| `actions` | array | Nein | Array von Action-Objekten für benutzerdefinierte Integrationen |
| `inputFields` | array | Nein | Array von Formularfeld-Definitionen (für STRUCTURED Eingabetyp) |
| `attachments` | string\[] | Nein | Array von bis zu 50 Anhang-UUIDs für den Agenten |
| `knowledgeFolderIds` | string\[] | Nein | Array von Ordner-UUIDs für den Agenten |
| `skillIds` | string\[] | Nein | Skill-UUIDs zum Anhängen. Siehe [Skills](#skills) |
| `webSearch` | boolean | Nein | Websuche-Fähigkeit aktivieren (Standard: false) |
| `imageGeneration` | boolean | Nein | Bildgenerierungs-Fähigkeit aktivieren (Standard: false) |
| `dataAnalyst` | boolean | Nein | Zur Kompatibilität akzeptiert. Siehe Warnhinweis unten |
| `extendedThinking` | boolean | Nein | Extended-Thinking-Modus aktivieren (Standard: false) |
Der Parameter `dataAnalyst` ist veraltet und hat keine Wirkung. Anfragen mit diesem Parameter sind aus Gründen der Abwärtskompatibilität weiterhin erfolgreich, aber Langdock ignoriert den Wert und aktiviert weder Dateiarbeit noch Codeausführung. Lass diesen Parameter in neuen Integrationen weg.
### Actions-Konfiguration
Jede Action im `actions` Array sollte enthalten:
* `actionId` (erforderlich) - UUID der Action aus einer aktivierten Integration
* `requiresConfirmation` (optional) - Ob vor der Ausführung eine Benutzerbestätigung erforderlich ist (Standard: true)
Nur Actions von in deinem Workspace aktivierten Integrationen können verwendet werden.
### Skills
* Übergib Skill-UUIDs aus der [Skills API](/de/developer/skills-api/list-skills) in `skillIds`.
* Der User, dem der API-Schlüssel gehört, muss jeden Skill anhängen können. Dateivorlagen werden abgelehnt.
### Eingabefelder-Konfiguration
Bei Verwendung von `inputType: "STRUCTURED"` kannst du Formularfelder im `inputFields` Array definieren:
| Feld | Typ | Erforderlich | Beschreibung |
| - | - | - | - |
| `slug` | string | Ja | Eindeutiger Bezeichner für das Feld |
| `type` | string | Ja | Feldtyp (siehe unterstützte Typen unten) |
| `label` | string | Ja | Anzeigebezeichnung für das Feld |
| `description` | string | Nein | Hilfetext für das Feld |
| `required` | boolean | Nein | Ob das Feld erforderlich ist (Standard: false) |
| `order` | number | Ja | Anzeigereihenfolge (0-indiziert) |
| `options` | string\[] | Nein | Optionen für SELECT- und MULTI\_SELECT-Feldtypen |
| `fileTypes` | string | Nein | Erlaubte Dateitypen für FILE-Feldtypen (nullable) |
| `emailDomain` | string | Nein | Erlaubte E-Mail-Domain für EMAIL-Feldtypen |
**Unterstützte Feldtypen:**
* `TEXT` - Einzeilige Texteingabe
* `MULTI_LINE_TEXT` - Mehrzeiliger Textbereich
* `NUMBER` - Numerische Eingabe
* `CHECKBOX` - Boolean-Checkbox
* `FILE` - Datei-Upload
* `SELECT` - Dropdown-Auswahl
* `MULTI_SELECT` - Mehrfachauswahl
* `DATE` - Datumsauswahl
* `EMAIL` - E-Mail-Adresse
## Anhangs-IDs abrufen
Um Anhänge in deinen Agenten einzubinden, lade zuerst Dateien mit der [Upload Attachment API](/de/developer/agents-api/upload-attachments) hoch. Dies gibt Anhang-UUIDs zurück, die du im `attachments` Array verwenden kannst.
## Beispiele
### Einen einfachen Agenten erstellen
```javascript theme={null}
const axios = require("axios");
async function createBasicAgent() {
const response = await axios.post(
"https://api.langdock.com/agent/v1/create",
{
name: "Dokumentenanalyse",
description: "Analysiert und fasst Dokumente zusammen",
emoji: "📄",
instruction: "Du bist ein hilfreicher Agent, der Dokumente analysiert und klare Zusammenfassungen der wichtigsten Informationen liefert.",
creativity: 0.5,
conversationStarters: [
"Fasse dieses Dokument zusammen",
"Was sind die wichtigsten Punkte?",
"Extrahiere Aktionspunkte"
],
webSearch: false
},
{
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
}
);
console.log("Agent erstellt:", response.data.agent.id);
}
```
## Validierungsregeln
Die API wendet mehrere Validierungsregeln an:
* **Modell** - Muss in der Liste der aktiven Modelle deines Workspaces sein
* **Actions** - Müssen zu in deinem Workspace aktivierten Integrationen gehören
* **Anhänge** - Müssen in deinem Workspace existieren und nicht gelöscht sein
* **Ordner** - Müssen in deinem Workspace existieren und nicht gelöscht sein
* **Skills** - Jede ID muss ein Skill sein, den der User, dem der API-Schlüssel gehört, anhängen kann. Dateivorlagen werden abgelehnt
* **Berechtigungen** - Dein API-Schlüssel muss die `createAgents` Berechtigung haben
* **Name** - Muss zwischen 1-80 Zeichen sein
* **Beschreibung** - Maximal 800 Zeichen
* **Instruktion** - Maximal 50000 Zeichen
* **Creativity** - Muss zwischen 0 und 1 liegen
## Wichtige Hinweise
Vorausgewählte OAuth-Verbindungen werden über die API nicht unterstützt. Benutzer müssen OAuth-Verbindungen über die Langdock-Benutzeroberfläche konfigurieren.
* Erstellte Agenten werden automatisch mit deinem API-Schlüssel für die Verwendung in Chat-Completions geteilt
* Der User, dem der API-Schlüssel gehört, wird zum Eigentümer und kann den Agenten in der Benutzeroberfläche verwalten
* Anhänge sind bidirektional mit dem Agenten verknüpft
* `createdBy` und `workspaceId` werden automatisch aus deinem API-Schlüssel übernommen
## Antwortformat
### Erfolgreiche Antwort (201 Created)
```typescript theme={null}
{
status: "success";
message: "Agent created successfully";
agent: {
id: string;
name: string;
description: string | null;
instruction: string | null;
emojiIcon: string | null;
model: string | null;
temperature: number;
conversationStarters: string[];
inputType: "PROMPT" | "STRUCTURED" | "INTEGRATION" | "SCHEDULED" | "WEBHOOK";
webSearchEnabled: boolean;
imageGenerationEnabled: boolean;
canvasEnabled: boolean;
extendedThinking: boolean;
actions: Array<{
actionId: string;
requiresConfirmation: boolean;
}>;
inputFields: Array<{
type: "TEXT" | "MULTI_LINE_TEXT" | "NUMBER" | "CHECKBOX" | "FILE" | "SELECT" | "MULTI_SELECT" | "DATE" | "EMAIL";
label: string;
description: string | null;
required: boolean;
order: number;
}>;
attachments: string[];
knowledgeFolderIds: string[];
skillIds: string[];
owner: {
id: string;
name: string | null;
email: string;
} | null;
createdAt: string;
updatedAt: string;
};
}
```
## Fehlerbehandlung
```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('Ungültige Parameter oder Ressource nicht gefunden:', error.response.data.message);
break;
case 401:
console.error('Ungültiger oder fehlender API-Schlüssel');
break;
case 403:
console.error('Unzureichende Berechtigungen - erfordert den Agenten API-Scope');
break;
case 429:
console.error('Rate Limit überschritten');
break;
case 500:
console.error('Server-Fehler');
break;
}
}
}
```
Langdock blockiert bewusst Browser-basierte Anfragen, um deinen API-Schlüssel zu schützen und die Sicherheit deiner Anwendungen zu gewährleisten. Weitere Informationen findest du in unserem Guide zu [Best Practices für API-Schlüssel](/de/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/AssistantCreateRequest'
responses:
'201':
description: Agent created successfully
content:
application/json:
schema:
type: object
required:
- status
- message
- agent
properties:
status:
type: string
enum:
- success
message:
type: string
agent:
$ref: '#/components/schemas/AssistantDetails'
components:
schemas:
AssistantCreateRequest:
allOf:
- $ref: '#/components/schemas/AssistantWriteRequest'
- type: object
required:
- name
properties:
inputType:
default: PROMPT
creativity:
default: 0.3
conversationStarters:
default: []
actions:
default: []
inputFields:
default: []
webSearch:
default: false
imageGeneration:
default: false
dataAnalyst:
default: false
extendedThinking:
default: false
attachments:
default: []
knowledgeFolderIds:
default: []
AssistantDetails:
type: object
required:
- id
- name
- description
- instruction
- emojiIcon
- model
- temperature
- conversationStarters
- inputType
- webSearchEnabled
- imageGenerationEnabled
- canvasEnabled
- extendedThinking
- actions
- inputFields
- attachments
- knowledgeFolderIds
- createdAt
- updatedAt
properties:
id:
type: string
format: uuid
description: Unique identifier for the agent
name:
type: string
description: Name of the agent
description:
type: string
nullable: true
description: Description of what the agent does
instruction:
type: string
nullable: true
description: System prompt/instructions for the agent
emojiIcon:
type: string
nullable: true
description: Emoji icon for the agent
model:
type: string
nullable: true
description: Model ID to use (see Models for Agent API)
temperature:
type: number
minimum: 0
maximum: 1
description: Temperature/creativity setting for response generation
conversationStarters:
type: array
items:
type: string
description: Array of suggested prompts to help users get started
inputType:
type: string
enum:
- PROMPT
- STRUCTURED
- INTEGRATION
- SCHEDULED
- WEBHOOK
description: Input type for the agent
webSearchEnabled:
type: boolean
description: Whether web search capability is enabled
imageGenerationEnabled:
type: boolean
description: Whether image generation capability is enabled
canvasEnabled:
type: boolean
description: Whether canvas capability is enabled
extendedThinking:
type: boolean
description: >-
Whether extended thinking is enabled. Only supported on models that
expose this capability; enabling it on an unsupported model returns
a 400 error.
actions:
type: array
items:
type: object
required:
- actionId
- requiresConfirmation
properties:
actionId:
type: string
format: uuid
description: >-
UUID of a live action. Missing and soft-deleted ids are
omitted. Live unavailable actions remain.
requiresConfirmation:
type: boolean
description: Whether user confirmation is required before executing
description: >-
Live actions on the returned version. Missing and soft-deleted ids
are omitted. Live unavailable actions remain.
inputFields:
type: array
items:
type: object
required:
- type
- label
- description
- required
- order
properties:
type:
type: string
enum:
- TEXT
- MULTI_LINE_TEXT
- NUMBER
- CHECKBOX
- FILE
- SELECT
- MULTI_SELECT
- DATE
- EMAIL
description: Field type
label:
type: string
description: Display label for the field
description:
type: string
nullable: true
description: Help text for the field
required:
type: boolean
description: Whether the field is required
order:
type: integer
minimum: 0
description: Display order (0-indexed)
description: Array of form field definitions (for STRUCTURED input type)
attachments:
type: array
items:
type: string
format: uuid
description: Array of attachment UUIDs associated with the agent
knowledgeFolderIds:
type: array
items:
type: string
format: uuid
description: Array of Folder UUIDs associated with the agent
createdAt:
type: string
format: date-time
description: Timestamp when the agent was created
updatedAt:
type: string
format: date-time
description: Timestamp when the agent was last updated
AssistantWriteRequest:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 80
description: Name of the agent or assistant
description:
type: string
maxLength: 800
description: >-
Description of what the agent or assistant does. Send an empty
string to clear it during an update.
instruction:
type: string
maxLength: 50000
description: >-
System prompt or instructions. Send an empty string to clear it
during an update.
inputType:
type: string
enum:
- PROMPT
- STRUCTURED
- INTEGRATION
- SCHEDULED
- WEBHOOK
description: Input type
emoji:
type: string
nullable: true
maxLength: 16
description: Emoji icon
model:
type: string
description: >-
id from GET /agent/v1/models. Unique deployment names and Anthropic
aliases stay valid. When several accessible rows share a name, send
the UUID id.
creativity:
type: number
minimum: 0
maximum: 1
description: Temperature for response generation
conversationStarters:
type: array
maxItems: 20
items:
type: string
minLength: 1
maxLength: 255
description: Suggested prompts
actions:
type: array
items:
$ref: '#/components/schemas/AssistantActionRequest'
description: >-
Actions that the agent or assistant can use. On update, the array
replaces the draft list.
inputFields:
type: array
items:
$ref: '#/components/schemas/AssistantInputFieldRequest'
description: Form fields for STRUCTURED input
webSearch:
type: boolean
description: Enable web search
imageGeneration:
type: boolean
description: Enable image generation
dataAnalyst:
type: boolean
deprecated: true
description: Deprecated. Accepted for compatibility and ignored.
extendedThinking:
type: boolean
description: Enable extended thinking
attachments:
type: array
maxItems: 50
items:
type: string
format: uuid
description: Attachment UUIDs
knowledgeFolderIds:
type: array
items:
type: string
format: uuid
description: Folder UUIDs
AssistantActionRequest:
type: object
required:
- actionId
properties:
actionId:
type: string
format: uuid
description: >-
UUID of the action. Create requires an enabled workspace
integration. Update also accepts ids already on the draft as
described on PATCH /agent/v1/update.
requiresConfirmation:
type: boolean
default: true
description: Whether to require user confirmation before executing
AssistantInputFieldRequest:
type: object
required:
- slug
- type
- label
- order
properties:
slug:
type: string
minLength: 1
maxLength: 64
description: Unique identifier for the field
type:
type: string
enum:
- TEXT
- MULTI_LINE_TEXT
- NUMBER
- CHECKBOX
- FILE
- SELECT
- MULTI_SELECT
- DATE
- EMAIL
description: Field type
label:
type: string
minLength: 1
maxLength: 255
description: Display label for the field
description:
type: string
maxLength: 512
description: Help text for the field
required:
type: boolean
default: false
description: Whether the field is required
order:
type: integer
minimum: 0
description: Display order
options:
type: array
default: []
items:
type: string
minLength: 1
maxLength: 255
description: Options for SELECT and MULTI_SELECT fields
fileTypes:
type: string
nullable: true
maxLength: 255
description: Allowed file types for FILE fields
emailDomain:
type: string
nullable: true
description: Allowed email domain for EMAIL fields
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: API key as Bearer token. Format "Bearer YOUR_API_KEY"
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.