Skip to main content
POST
Creates a chat completion with an agent (Vercel AI SDK compatible)
⚠️ Du nutzt unsere API in einem Dedicated Deployment? Ersetze einfach api.langdock.com durch die Base URL deines Deployments: <deployment-url>/api/public
MCP Support: Du kannst auch über den Langdock 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
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

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:

Nachrichtenteil-Typen

User-Nachrichtenteile (zum Senden): Agent-Nachrichtenteile (in Antworten zurückgegeben — füge sie in den Gesprächsverlauf ein, wenn du Folgenachrichten sendest):

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 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 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 abrufen.
Die Feldnamen der Inline-Agentenkonfiguration unterscheiden sich von den Create und 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.

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: 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 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

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 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 oder aktualisierst. 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:

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

Verwendung einer temporären Agentenkonfiguration

Verwendung von strukturierter Ausgabe mit Schema

Verwendung mit Next.js Server Actions

Rate Limits

Die Standard-Limits sind 500 RPM (Anfragen pro Minute) und 60.000 TPM (Tokens pro Minute).
  • RPM wird je Workspace, Modell und API-Key begrenzt.
  • TPM teilen sich alle API-Keys, die dasselbe Modell in einem Workspace verwenden.
  • In Dedicated Deployments können Admins unter Einstellungen > Workspace > Produkte > API eigene Limits je Modell festlegen.
Wenn du dein Rate Limit überschreitest, erhältst du eine 429 Too Many Requests Antwort.

Fehlerbehandlung

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.

Autorisierungen

Authorization
string
header
erforderlich

API key as Bearer token. Format "Bearer YOUR_API_KEY"

Body

application/json
agentId
string
erforderlich

ID of an existing agent to use

messages
object[]
erforderlich

Array of UIMessage objects (Vercel AI SDK format)

stream
boolean
Standard:false
output
object

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.

imageResponseFormat
enum<string>

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

Antwort

Successful chat completion

UIMessage response (Vercel AI SDK format)

id
string
erforderlich
role
enum<string>
erforderlich
Verfügbare Optionen:
assistant
parts
object[]
erforderlich
output
any

Structured output if requested