> ## 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. # Agents Completions API > Erstellt eine Modellantwort für einen bestimmten Agenten im Vercel AI SDK kompatiblen Format. **⚠️ Du nutzt unsere API in einem Dedicated Deployment?** Ersetze einfach `api.langdock.com` durch die Base URL deines Deployments: **`/api/public`** **MCP Support:** Du kannst auch über den [Langdock MCP Server](/de/using-langdock/guides/integrations/mcp/langdock-agent-mcp-server) auf deine Agenten zugreifen, sodass MCP-kompatible KI-Clients deine Agenten direkt aufrufen können. ## Basis-URL Erstellt eine Modellantwort für eine bestimmte Agenten-ID oder übergibt eine Agentenkonfiguration, die für deine Anfrage verwendet werden soll. Dieser Endpoint verwendet das Vercel AI SDK kompatible Nachrichtenformat für eine nahtlose Integration mit modernen AI-Anwendungen. Um einen Agenten mit einem API-Schlüssel zu teilen, folge [dieser Anleitung](/de/developer/agents-api/agent-api-guide) **Vercel AI SDK kompatibel**: Dieser Endpoint verwendet das UIMessage-Format des Vercel AI SDK und ist damit kompatibel mit dem `useChat` Hook und anderen Vercel AI SDK Features. ## Anfrageparameter | Parameter | Typ | Erforderlich | Beschreibung | | --------------------- | ------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | `agentId` | string | Eines von agentId/agent erforderlich | ID eines vorhandenen Agenten | | `agent` | object | Eines von agentId/agent erforderlich | Konfiguration für einen temporären Agenten | | `messages` | array | Ja | Array von UIMessage-Objekten (Vercel AI SDK Format) | | `stream` | boolean | Nein | Streaming-Antworten aktivieren (Standard: false) | | `output` | object | Nein | Spezifikation für strukturiertes Ausgabeformat | | `maxSteps` | integer | Nein | Maximale Anzahl von Tool-Schritten (1-20) | | `imageResponseFormat` | string | Nein | Antwortformat für vom Agenten generierte Bilder. `"url"` gibt eine signierte URL zurück, `"b64_json"` gibt base64-kodierte Bilddaten zurück. | ## Nachrichtenformat (Vercel AI SDK UIMessage) Die Agents API verwendet das Vercel AI SDK UIMessage-Format für maximale Kompatibilität mit modernen AI-Frameworks. ### UIMessage-Struktur Jede Nachricht im `messages` Array sollte enthalten: ```typescript theme={null} interface UIMessage { id: string; // Eindeutige Kennung für diese Nachricht role: 'system' | 'user' | 'assistant'; parts: MessagePart[]; // Array von Nachrichtenteilen metadata?: { // Optionale Metadaten attachments?: string[]; // Array von Attachment-UUIDs }; } ``` ### Nachrichtenteil-Typen **User-Nachrichtenteile** (zum Senden): | Typ | Felder | Beschreibung | | ------ | ----------------------------------------------------------------------- | -------------------- | | `text` | `type: "text"`, `text: string` | Klartext-Inhalt | | `file` | `type: "file"`, `mediaType: string`, `url: string`, `filename?: string` | Inline-Dateireferenz | **Agent-Nachrichtenteile** (in Antworten zurückgegeben — füge sie in den Gesprächsverlauf ein, wenn du Folgenachrichten sendest): | Typ | Wichtige Felder | Beschreibung | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | `text` | `type: "text"`, `text: string` | Textantwort | | `reasoning` | `type: "reasoning"`, `text: string` | Modell-Reasoning / Chain-of-Thought | | `tool-{name}` | `type: "tool-{name}"`, `toolCallId: string`, `state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"`, `input?: any`, `output?: any`, `errorText?: string` | Tool-Aufruf und Ergebnis | | `source-url` | `type: "source-url"`, `sourceId: string`, `url: string`, `title?: string` | Web-Quellenreferenz | | `source-document` | `type: "source-document"`, `sourceId: string`, `mediaType: string`, `title: string`, `filename?: string` | Dokumenten-Quellenreferenz | ### Beispielnachrichten #### User-Nachricht mit Text ```javascript theme={null} { id: "msg_1", role: "user", parts: [ { type: "text", text: "Hallo, wie geht es dir?" } ] } ``` #### User-Nachricht mit Attachment ```javascript theme={null} { id: "msg_2", role: "user", parts: [ { type: "text", text: "Bitte analysiere dieses Dokument" } ], metadata: { attachments: ["550e8400-e29b-41d4-a716-446655440000"] } } ``` Um Dateien an eine Nachricht anzuhängen, lade sie über die [Upload Attachment API](/de/developer/agents-api/upload-attachments) hoch und referenziere die zurückgegebenen UUIDs im `metadata.attachments` Array der Nachricht. Verwende keine `type: "file"` Parts für hochgeladene Attachments — dieses Format ist für Inline-Dateireferenzen reserviert (z.B. Data URIs). #### Agent-Nachricht mit Tool-Aufruf ```javascript theme={null} { id: "msg_3", role: "assistant", parts: [ { type: "tool-webSearch", toolCallId: "call_123", state: "output-available", input: { query: "latest news" }, output: { /* Suchergebnisse */ } } ] } ``` ## Agentenkonfiguration Bei der Erstellung eines temporären Agenten mit dem `agent` Parameter kannst du Folgendes angeben: * `name` - Name des Agenten (max. 64 Zeichen) * `instructions` - Systemanweisungen (max. 16384 Zeichen) * `description` - Optionale Beschreibung (max. 256 Zeichen) * `temperature` - Temperatur zwischen 0-1 * `model` - Zu verwendende Modell-ID (siehe [Verfügbare Modelle](/de/developer/agents-api/agent-models) für Optionen) * `capabilities` - Aktivieren von Funktionen wie Websuche, Dateien erstellen & bearbeiten, Bilderzeugung, Canvas * `knowledgeFolderIds` - IDs der zu verwendenden Wissensdatenbanken * `attachmentIds` - Array von UUID-Strings zur Identifizierung zu verwendender Anhänge Du kannst eine Liste verfügbarer Modelle mit der [Models API](/de/developer/agents-api/agent-models) abrufen. Die Feldnamen der Inline-Agentenkonfiguration unterscheiden sich von den [Create](/de/developer/agents-api/agent-create) und [Update](/de/developer/agents-api/agent-update) Agent APIs. Insbesondere verwendet dieser Endpoint `instructions` (Plural) und `temperature`, während die CRUD-Endpoints `instruction` (Singular) und `creativity` verwenden. Der Completions-Endpoint akzeptiert auch ein verschachteltes `capabilities` Objekt, während die CRUD-Endpoints flache Boolean-Felder verwenden. `attachmentIds` in der Inline-Agentenkonfiguration ist derzeit nicht funktionsfähig — der Agent kann die angehängten Dateien nicht lesen. Verwende stattdessen `metadata.attachments` bei einzelnen Nachrichten, um hochgeladene Dateien pro Nachricht zu referenzieren, oder erstelle einen persistenten Agenten mit dem `attachments` Feld über die [Create Agent API](/de/developer/agents-api/agent-create). ## Tools über die API verwenden Wenn ein Agent Tools konfiguriert hat (in der Langdock-Oberfläche „Actions" genannt), wird er diese automatisch bei API-Anfragen verwenden, wenn es passend ist. Die Verbindung muss auf „vorausgewählte Verbindung" (mit anderen Nutzern geteilt) gesetzt werden, damit die Tool-Authentifizierung funktioniert. Vorausgewählte Verbindung Einstellung in der Agentenkonfiguration Tools mit aktivierter Option **„Menschliche Bestätigung erforderlich"** funktionieren nicht über die API — sie erfordern eine manuelle Genehmigung in der Langdock-Oberfläche. Um ein Tool über die API zu nutzen, deaktiviere diese Einstellung in der Agentenkonfiguration. ## Strukturierte Ausgabe Du kannst ein strukturiertes Ausgabeformat mit dem optionalen `output` Parameter angeben: | Feld | Typ | Beschreibung | | -------- | ----------------------------- | --------------------------------------------------------------- | | `type` | "object" \| "array" \| "enum" | Der Typ der strukturierten Ausgabe | | `schema` | object | JSON-Schema-Definition für die Ausgabe (für object/array-Typen) | | `enum` | string\[] | Array erlaubter Werte (für enum-Typ) | Das Verhalten des `output` Parameters hängt vom angegebenen Typ ab: * `type: "object"` ohne Schema: Erzwingt, dass die Antwort ein einzelnes JSON-Objekt ist (keine spezifische Struktur) * `type: "object"` mit Schema: Erzwingt, dass die Antwort dem bereitgestellten JSON-Schema entspricht * `type: "array"` mit Schema: Erzwingt, dass die Antwort ein Array von Objekten ist, die dem bereitgestellten Schema entsprechen * `type: "enum"`: Erzwingt, dass die Antwort einer der im `enum` Array angegebenen Werte ist Du kannst Tools wie [easy-json-schema](https://easy-json-schema.github.io/) verwenden, um JSON-Schemas aus Beispiel-JSON-Objekten zu generieren. ## Streaming-Antworten Wenn `stream` auf `true` gesetzt ist, gibt die API einen Stream im Vercel AI SDK Streaming-Format zurück, kompatibel mit dem `useChat` Hook und anderen Vercel AI SDK Features. Anfragen ohne Streaming werden nach 100 Sekunden mit einem HTTP 524 Fehler beendet. Wenn dein Agent Tools ausführt, lange Antworten generiert oder langsamere Modelle verwendet, kann die Anfrage dieses Limit überschreiten. Setze `stream: true`, um die Verbindung offen zu halten und Timeouts zu vermeiden. ### Verwendung mit dem Vercel AI SDK useChat Hook ```typescript theme={null} 'use client'; import { useChat } from '@ai-sdk/react'; export default function Chat() { const { messages, input, handleInputChange, handleSubmit } = useChat({ api: 'https://api.langdock.com/agent/v1/chat/completions', headers: { 'Authorization': `Bearer ${process.env.NEXT_PUBLIC_LANGDOCK_API_KEY}` }, body: { agentId: 'your-agent-id' } }); return (
{messages.map(m => (
{m.role === 'user' ? 'User: ' : 'AI: '} {m.content}
))}
); } ``` ### Manuelle Stream-Verarbeitung ```javascript theme={null} const response = await fetch('https://api.langdock.com/agent/v1/chat/completions', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ agentId: 'agent_123', messages: [ { id: 'msg_1', role: 'user', parts: [{ type: 'text', text: 'Hallo' }] } ], stream: true }), }); const reader = response.body.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const chunk = decoder.decode(value); console.log(chunk); // Streaming-Chunks verarbeiten } ``` ## Abrufen von Attachment-IDs Um Attachments in deinen Agentengesprächen zu verwenden, lade zuerst die Dateien mit der [Upload Attachment API](/de/developer/agents-api/upload-attachments) hoch. Dies gibt eine `attachmentId` (UUID) für jede Datei zurück. Du kannst Attachments dann auf zwei Arten verwenden: 1. **Pro Nachricht** (empfohlen): Füge die Attachment-UUIDs in das `metadata.attachments` Array der Nachricht ein. So kannst du verschiedene Dateien in verschiedenen Nachrichten innerhalb desselben Gesprächs referenzieren. 2. **Agent-Ebene**: Füge die UUIDs in das `attachments` Array ein, wenn du einen persistenten Agenten [erstellst](/de/developer/agents-api/agent-create) oder [aktualisierst](/de/developer/agents-api/agent-update). Alle Nachrichten an diesen Agenten haben dann Zugriff auf diese Dateien. ## Antwortformat Die API gibt ein JSON-Objekt mit einem `messages` Array zurück, das die Antwort des Agenten enthält: ```typescript theme={null} interface CompletionResponse { messages: Array<{ id: string; role: "assistant"; content: string; }>; // Strukturierte Ausgabe - enthalten wenn angefordert output?: object | array | string; } ``` ### Standard-Antwort Die Antwort enthält ein `messages` Array. Jede Nachricht hat: * `id` - Eindeutige Kennung für die Nachricht * `role` - Immer `"assistant"` für Completion-Antworten * `content` - Die Textantwort des Agenten als einfacher String ### Strukturierte Ausgabe Wenn die Anfrage einen `output` Parameter enthält, wird die Antwort automatisch ein `output` Feld mit den formatierten strukturierten Daten enthalten. Der Typ dieses Feldes hängt vom angeforderten Ausgabeformat ab: * Wenn `output.type` "object" war: Gibt ein JSON-Objekt zurück (mit Schema-Validierung, falls ein Schema bereitgestellt wurde) * Wenn `output.type` "array" war: Gibt ein Array von Objekten zurück, die dem bereitgestellten Schema entsprechen * Wenn `output.type` "enum" war: Gibt einen String zurück, der einem der bereitgestellten Enum-Werte entspricht ## Beispiele ### Verwendung eines vorhandenen Agenten mit Attachment ```javascript theme={null} const response = await fetch( "https://api.langdock.com/agent/v1/chat/completions", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ agentId: "agent_123", messages: [ { id: "msg_1", role: "user", parts: [ { type: "text", text: "Kannst du dieses Dokument für mich analysieren?" } ], metadata: { attachments: ["550e8400-e29b-41d4-a716-446655440000"] } } ] }) } ); const data = await response.json(); const responseText = data.messages[0].content; console.log(responseText); ``` ### Verwendung einer temporären Agentenkonfiguration ```javascript theme={null} const response = await fetch( "https://api.langdock.com/agent/v1/chat/completions", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ agent: { name: "Document Analyzer", instructions: "You are a helpful agent who analyzes documents and answers questions about them", temperature: 0.7, model: "gpt-5", capabilities: { webSearch: true } }, messages: [ { id: "msg_1", role: "user", parts: [ { type: "text", text: "Was sind die wichtigsten Punkte im Dokument?" } ] } ] }) } ); const data = await response.json(); console.log(data); ``` ### Verwendung von strukturierter Ausgabe mit Schema ```javascript theme={null} const response = await fetch( "https://api.langdock.com/agent/v1/chat/completions", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ agent: { name: "Weather Agent", instructions: "You are a helpful weather agent", model: "gpt-5", capabilities: { webSearch: true } }, messages: [ { id: "msg_1", role: "user", parts: [ { type: "text", text: "Wie ist das Wetter heute in Paris, Berlin und London?" } ] } ], output: { type: "array", schema: { type: "object", properties: { weather: { type: "object", properties: { city: { type: "string" }, tempInCelsius: { type: "number" }, tempInFahrenheit: { type: "number" } }, required: ["city", "tempInCelsius", "tempInFahrenheit"] } } } } }) } ); const data = await response.json(); console.log(data.output); // Output: // [ // { "weather": { "city": "Paris", "tempInCelsius": 1, "tempInFahrenheit": 33 } }, // { "weather": { "city": "Berlin", "tempInCelsius": 1, "tempInFahrenheit": 35 } }, // { "weather": { "city": "London", "tempInCelsius": 7, "tempInFahrenheit": 45 } } // ] ``` ### Verwendung mit Next.js Server Actions ```typescript theme={null} // app/actions.ts 'use server'; import { generateId } from 'ai'; export async function chatWithAgent(message: string) { const response = await fetch( 'https://api.langdock.com/agent/v1/chat/completions', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.LANGDOCK_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ agentId: process.env.AGENT_ID, messages: [ { id: generateId(), role: 'user', parts: [ { type: 'text', text: message } ] } ] }) } ); const data = await response.json(); return data.messages[0].content; } ``` ## Rate Limits Die Rate Limit für den Agents Completions Endpoint beträgt **500 RPM (Anfragen pro Minute)** und **60,000 TPM (Token pro Minute)**. Rate Limits werden auf Workspace-Ebene definiert - nicht auf API-Schlüssel-Ebene. Jedes Modell hat seine eigene Rate Limit. Wenn du deine Rate Limit überschreitest, erhältst du eine `429 Too Many Requests` Antwort. Bitte beachte, dass die Rate Limits Änderungen unterliegen. Beziehe dich auf diese Dokumentation für die aktuellsten Informationen. Falls du eine höhere Rate Limit benötigst, kontaktiere uns bitte unter [support@langdock.com](mailto:support@langdock.com). ## Fehlerbehandlung ```javascript theme={null} try { const response = await fetch('https://api.langdock.com/agent/v1/chat/completions', options); if (!response.ok) { const error = await response.json(); throw new Error(error.message || 'Request failed'); } const data = await response.json(); // Antwort verarbeiten } catch (error) { console.error('Error:', error.message); } ``` Häufige Fehler-Statuscodes: * `400` - Ungültige Anfrageparameter, fehlerhaftes Nachrichtenformat, Agent nicht gefunden oder Agent nicht mit API-Schlüssel geteilt * `401` - Ungültiger oder fehlender API-Schlüssel * `429` - Rate Limit überschritten * `500` - Serverfehler 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/chat/completions 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/chat/completions: post: tags: - Agent summary: Creates a chat completion with an agent (Vercel AI SDK compatible) description: Creates a model response using Vercel AI SDK compatible UIMessage format parameters: [] requestBody: required: true content: application/json: examples: streamingEnabled: summary: Request with streaming enabled value: agentId: agent_123 messages: - id: msg_1 role: user parts: - type: text text: Hello, how can you help me? stream: true schema: type: object oneOf: - type: object required: - agentId - messages properties: agentId: type: string description: ID of an existing agent to use messages: type: array description: Array of UIMessage objects (Vercel AI SDK format) items: type: object required: - id - role - parts properties: id: type: string description: Unique message identifier role: type: string enum: - user - assistant - system - tool parts: type: array items: type: object required: - type properties: type: type: string enum: - text - file - tool-invocation - tool-result text: type: string description: Text content for text parts url: type: string description: File URL for file parts name: type: string description: File name mimeType: type: string description: MIME type of the file toolCallId: type: string description: Tool call identifier toolName: type: string description: Name of the tool args: type: object description: Tool arguments result: type: object description: Tool result stream: type: boolean default: false output: $ref: '#/components/schemas/StructuredOutputConfig' imageResponseFormat: type: string enum: - url - b64_json description: >- Response format for images generated by the agent. "url" returns a signed URL, "b64_json" returns base64-encoded image data. responses: '200': description: Successful chat completion content: application/json: schema: type: object description: UIMessage response (Vercel AI SDK format) required: - id - role - parts properties: id: type: string role: type: string enum: - assistant parts: type: array items: type: object output: description: Structured output if requested '400': description: Invalid request parameters '429': description: Rate limit exceeded '500': description: Internal server error components: schemas: StructuredOutputConfig: type: object description: >- Specification for structured output format. When type is object/array and no schema is provided, the response will be JSON but can have any structure. When the type is enum, you must provide an enum parameter with an array of strings as options. properties: type: type: string enum: - object - array - enum description: The type of structured output schema: type: object description: >- JSON Schema definition for the output (required for object/array types with specific structure). Search for "JSON to JSON Schema" in the web to find a tool to convert any JSON into the required JSON Schema format. enum: type: array items: type: string description: >- Array of allowed values (required for enum type). Values must be of type string. oneOf: - properties: type: enum: - enum enum: type: array items: type: string - properties: type: enum: - object - array schema: type: object - properties: type: enum: - object - array securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: API key as Bearer token. Format "Bearer YOUR_API_KEY" ````