Creates a chat completion with an agent (Vercel AI SDK compatible)
Agents API
Agents Completions API
Erstellt eine Modellantwort für einen bestimmten Agenten im Vercel AI SDK kompatiblen Format.
POST
Creates a chat completion with an agent (Vercel AI SDK compatible)
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.
⚠️ Du nutzt unsere API in einem Dedicated Deployment? Ersetze einfach
api.langdock.com durch die Base URL deines Deployments: <deployment-url>/api/publicBasis-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
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 immessages Array sollte enthalten:
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 |
| 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
User-Nachricht mit Attachment
Um Dateien an eine Nachricht anzuhängen, lade sie über die Upload Attachment API 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
Agentenkonfiguration
Bei der Erstellung eines temporären Agenten mit demagent 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-1model- Zu verwendende Modell-ID (siehe Verfügbare Modelle für Optionen)capabilities- Aktivieren von Funktionen wie Websuche, Datenanalyse, Bilderzeugung, CanvasknowledgeFolderIds- IDs von zu verwendenden WissensordnernattachmentIds- Array von UUID-Strings zur Identifizierung zu verwendender Anhänge
Du kannst eine Liste verfügbarer Modelle mit der Models API abrufen.
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.
Strukturierte Ausgabe
Du kannst ein strukturiertes Ausgabeformat mit dem optionalenoutput 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) |
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 entsprichttype: "array"mit Schema: Erzwingt, dass die Antwort ein Array von Objekten ist, die dem bereitgestellten Schema entsprechentype: "enum": Erzwingt, dass die Antwort einer der imenumArray angegebenen Werte ist
Du kannst Tools wie easy-json-schema verwenden, um JSON-Schemas aus Beispiel-JSON-Objekten zu generieren.
Streaming-Antworten
Wennstream 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.
Verwendung mit dem Vercel AI SDK useChat Hook
Manuelle Stream-Verarbeitung
Abrufen von Attachment-IDs
Um Attachments in deinen Agentengesprächen zu verwenden, lade zuerst die Dateien mit der Upload Attachment API hoch. Dies gibt eineattachmentId (UUID) für jede Datei zurück. Du kannst Attachments dann auf zwei Arten verwenden:
- Pro Nachricht (empfohlen): Füge die Attachment-UUIDs in das
metadata.attachmentsArray der Nachricht ein. So kannst du verschiedene Dateien in verschiedenen Nachrichten innerhalb desselben Gesprächs referenzieren. - Agent-Ebene: Füge die UUIDs in das
attachmentsArray ein, wenn du einen persistenten Agenten erstellst oder aktualisierst. Alle Nachrichten an diesen Agenten haben dann Zugriff auf diese Dateien.
Antwortformat
Die API gibt ein JSON-Objekt mit einemmessages Array zurück, das die Antwort des Agenten enthält:
Standard-Antwort
Die Antwort enthält einmessages Array. Jede Nachricht hat:
id- Eindeutige Kennung für die Nachrichtrole- Immer"assistant"für Completion-Antwortencontent- Die Textantwort des Agenten als einfacher String
Strukturierte Ausgabe
Wenn die Anfrage einenoutput 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
Verwendung einer temporären Agentenkonfiguration
Verwendung von strukturierter Ausgabe mit Schema
Verwendung mit Next.js Server Actions
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 eine429 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.
Fehlerbehandlung
400- Ungültige Anfrageparameter, fehlerhaftes Nachrichtenformat, Agent nicht gefunden oder Agent nicht mit API-Schlüssel geteilt401- Ungültiger oder fehlender API-Schlüssel429- Rate Limit überschritten500- 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.
Autorisierungen
API key as Bearer token. Format "Bearer YOUR_API_KEY"
Body
application/json
ID of an existing agent to use
Array of UIMessage objects (Vercel AI SDK format)
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.
- Option 1
- Option 2
- Option 3
Response format for images generated by the agent. "url" returns a signed URL, "b64_json" returns base64-encoded image data.
Verfügbare Optionen:
url, b64_json