Bevor du startest
- Agenten-Zugriff: 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
useChatHook und anderen Vercel AI SDK Features. - MCP: 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
Parameter
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:
role: "system" bleiben in der Anfrage als normaler User-Kontext. Sie gelten nicht als System-Prompt.
Die letzte Nachricht ist die aktuelle Anfrage nur, wenn role user ist. Eine letzte Nachricht mit einer anderen Rolle fällt weg.
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 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-idvon der Models APIcapabilities- Aktivieren von Funktionen wie Websuche, Dateien erstellen & bearbeiten, Bilderzeugung, CanvasknowledgeFolderIds- IDs der zu verwendenden WissensdatenbankenattachmentIds- Array von UUID-Strings zur Identifizierung zu verwendender Anhänge
Hinweise zur Konfiguration
- Verfügbare Modelle: Du kannst eine Liste verfügbarer Modelle mit der Models API abrufen. Sende die zurückgegebene
id. Completions lehnt einen Deployment-Namen ab, der zu mehr als einer zugänglichen Zeile passt. Eindeutige Namen und Anthropic-Aliase funktionieren weiter. - Feldnamen: Die Feldnamen der Inline-Agentenkonfiguration unterscheiden sich von den Create und Update Agent APIs. Dieser Endpoint verwendet
instructions(Plural) undtemperature, während die CRUD-Endpointsinstruction(Singular) undcreativityverwenden. Der Completions-Endpoint akzeptiert auch ein verschachteltescapabilitiesObjekt, während die CRUD-Endpoints flache Boolean-Felder verwenden. attachmentIdsderzeit nicht funktionsfähig: Der Agent kann Dateien, die überattachmentIdsin der Inline-Agentenkonfiguration referenziert werden, nicht lesen. Verwende stattdessenmetadata.attachmentsbei einzelnen Nachrichten, um hochgeladene Dateien pro Nachricht zu referenzieren, oder erstelle einen persistenten Agenten mit demattachmentsFeld ü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. Tools authentifizieren sich über eine vorausgewählte Verbindung am Agenten oder über eine Verbindung, die mit dem API-Key geteilt ist.Ein Workspace-API-Key läuft als Service Account. Tools brauchen eine vorausgewählte Verbindung oder eine Verbindung, die mit diesem Key geteilt ist.

Strukturierte Ausgabe
Du kannst ein strukturiertes Ausgabeformat mit dem optionalenoutput 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 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.
Ein Lauf mit deinem Workspace-API-Key stoppt vor dem nächsten Modellaufruf, sobald dein Workspace sein monatliches Ausgabenlimit erreicht. Hat der Stream schon begonnen, bleibt der HTTP-Status 200. Der Fehlertext ist
You have reached the monthly spending limit (€100.00) for your workspace, wenn das Limit 100 € beträgt. Danach endet der Stream mit einem Fehler. Ohne Streaming erhältst du 429, und die Antwort enthält keine Ausgabe aus früheren Schritten.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 Standard-Limits sind 500 RPM (Anfragen pro Minute) und 150.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 der Cloud können Admins unter Einstellungen > Workspace > Produkte > API die TPM für eigene Modelle setzen; sie begrenzt die geschätzte Größe einer einzelnen Anfrage.
- In Dedicated Deployments können Admins unter Einstellungen > Workspace > Produkte > API eigene Limits je Modell festlegen.
429 Too Many Requests Antwort.
Fehlerbehandlung
400- Ungültige Anfrageparameter, fehlerhaftes Nachrichtenformat, Agent nicht gefunden, Agent nicht mit API-Schlüssel geteilt oder eine angehängte Integrationsdatei, die der API-Schlüssel nicht lesen kann401- Ungültiger oder fehlender API-Schlüssel429- Rate Limit überschritten, die Integration hat die Zugriffsprüfung für eine angehängte Integrationsdatei per Rate Limit blockiert, oder der Workspace hat sein monatliches Ausgabenlimit erreicht500- Serverfehler503- Zugriffsprüfung für eine angehängte Integrationsdatei nicht verfügbar
400 und 429 stehen die IDs zusätzlich in details.attachmentIds.
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.