Skip to main content
POST
Die Assistants API wird am 16. August eingestellt.Für neue Systeme empfehlen wir die Agents API. Die Agents API bietet native Vercel AI SDK Kompatibilität und entfernt benutzerdefinierte Transformationen.Siehe den Migrations-Guide für Details zu den Unterschieden.
Erstellt eine Modellantwort für eine bestimmte Assistenten-ID oder übergibt eine Assistentenkonfiguration, die für deine Anfrage verwendet werden soll.
Um einen Assistenten mit einem API-Schlüssel zu teilen, folge dieser Anleitung

Anfrageparameter

Nachrichtenformat

Jede Nachricht im messages Array sollte enthalten:
  • role (erforderlich) - Eines von: “user”, “assistant” oder “tool”
  • content (erforderlich) - Der Nachrichteninhalt als String
  • attachmentIds (optional) - Array von UUID-Strings zur Identifizierung von Anhängen für diese Nachricht

Assistentenkonfiguration

Bei der Erstellung eines temporären Assistenten kannst du Folgendes angeben:
  • name (erforderlich) - Name des Assistenten (max. 64 Zeichen)
  • instructions (erforderlich) - 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 und Bilderzeugung
  • actions - Nutzerdefinierte API-Integrationen
  • vectorDb - Vektordatenbankverbindungen
  • 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. Dies ist nützlich, wenn du sehen möchtest, welche Modelle du in deiner Assistentenkonfiguration verwenden kannst.

Tools über die API verwenden

Wenn ein Assistent 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 Assistentenkonfiguration
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 Assistentenkonfiguration.

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 von Server-Sent Events (SSE) zurück, anstatt auf die vollständige Antwort zu warten. Dies ermöglicht es dir, Antworten progressiv anzuzeigen, während sie generiert werden.
Anfragen ohne Streaming werden nach 100 Sekunden mit einem HTTP 524 Fehler beendet. Wenn dein Assistant 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.

Stream-Format

Jedes Event im Stream folgt dem SSE-Format mit JSON-Daten:

Streams in JavaScript verarbeiten

Abrufen von Anhangs-IDs

Um Anhänge in deinen Assistentengesprächen zu verwenden, musst du zuerst die Dateien mit der Upload Attachment API hochladen. Dies gibt eine attachmentId für jede Datei, die du dann in das attachmentIds Array in deiner Assistenten- oder Nachrichtenkonfiguration einfügen kannst.

Beispiele

Verwendung eines vorhandenen Assistenten

Verwendung einer temporären Assistentenkonfiguration

Verwendung von strukturierter Ausgabe mit Schema (Array)

Verwendung von strukturierter Ausgabe mit Schema (Object)

Verwendung von strukturierter Ausgabe mit Enum

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.

Antwortformat

Die API gibt ein Objekt zurück, das Folgendes enthält:

Standardergebnis

Das result Array enthält den Nachrichtenaustausch zwischen Nutzer und Assistent, einschließlich aller durchgeführten Tool-Aufrufe. Dies ist immer in der Antwort enthalten.

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
Zum Beispiel, wenn Wetterdaten mit strukturierter Ausgabe angefordert werden:
Das output Feld wird automatisch mit den formatierten Ergebnissen basierend auf der Antwort des Assistenten und deiner Schema-Definition gefüllt. Du kannst das direkt in deiner Anwendung verwenden, ohne die vollständige Konversation in result parsen zu müssen.

Fehlerbehandlung

Migration zur Agents API

Die neue Agents API bietet verbesserte Kompatibilität mit modernen AI SDKs, einschließlich nativer Unterstützung für das Vercel AI SDK. Der Hauptunterschied liegt im Format des Chat-Completions-Endpunkts. Siehe den entsprechenden Endpunkt in der Agents API:
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
assistantId
string
erforderlich

ID of an existing agent to use

messages
object[]
erforderlich
stream
boolean
Standard:false

Enable or disable streaming responses. When true, returns server-sent events. When false, returns complete JSON response.

Beispiel:

true

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.

maxSteps
integer
Standard:10

Maximum number of steps the agent can take during the conversation

Erforderlicher Bereich: 1 <= x <= 20

Antwort

Successful chat completion

result
object[]
erforderlich
output

Present when output parameter was specified in the request