Assistants Completions API

curl --request POST \
  --url https://api.langdock.com/assistant/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "assistantId": "asst_123",
  "messages": [
    {
      "role": "user",
      "content": "Hello, how can you help me?"
    }
  ],
  "stream": true
}
'

{
  "result": [
    {
      "id": "<string>",
      "content": [
        {
          "type": "<string>",
          "toolCallId": "<string>",
          "toolName": "<string>",
          "result": {},
          "args": {},
          "text": "<string>"
        }
      ]
    }
  ],
  "output": {}
}

POST

assistant

chat

completions

curl --request POST \
  --url https://api.langdock.com/assistant/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "assistantId": "asst_123",
  "messages": [
    {
      "role": "user",
      "content": "Hello, how can you help me?"
    }
  ],
  "stream": true
}
'

{
  "result": [
    {
      "id": "<string>",
      "content": [
        {
          "type": "<string>",
          "toolCallId": "<string>",
          "toolName": "<string>",
          "result": {},
          "args": {},
          "text": "<string>"
        }
      ]
    }
  ],
  "output": {}
}

Die Assistants API wird am 30. April eingestellt.Für neue Projekte 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

Parameter	Typ	Erforderlich	Beschreibung
`assistantId`	string	Eines von assistantId/assistant erforderlich	ID eines vorhandenen Assistenten zur Verwendung
`assistant`	object	Eines von assistantId/assistant erforderlich	Konfiguration für einen neuen Assistenten
`messages`	array	Ja	Array von Nachrichtenobjekten mit Rolle und Inhalt
`stream`	boolean	Nein	Streaming-Antworten aktivieren (Standard: false)
`output`	object	Nein	Spezifikation für strukturiertes Ausgabeformat

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, Datenanalyse, Bilderzeugung
actions - Nutzerdefinierte API-Integrationen
vectorDb - Vektordatenbankverbindungen
knowledgeFolderIds - IDs von zu verwendenden Wissensordnern
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:

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

data: {"type":"message","content":"Hallo"}
data: {"type":"message","content":" Welt"}
data: {"type":"done"}

Streams in JavaScript verarbeiten

const response = await fetch('https://api.langdock.com/assistant/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    assistantId: 'asst_123',
    messages: [{ role: 'user', content: '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);
  const lines = chunk.split('\n');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      if (data.type === 'message') {
        process.stdout.write(data.content);
      }
    }
  }
}

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

const axios = require("axios");

async function chatWithAssistant() {
  const response = await axios.post(
    "https://api.langdock.com/assistant/v1/chat/completions",
    {
      assistantId: "asst_123",
      messages: [
        {
          role: "user",
          content: "Kannst du dieses Dokument für mich analysieren?",
          attachmentIds: ["550e8400-e29b-41d4-a716-446655440000"], // Erhalte attachmentIds vom Upload-Attachment-Endpunkt
        },
      ],
      stream: true, // Streaming-Antworten aktivieren
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

  console.log(response.data.result);
}

Verwendung einer temporären Assistentenkonfiguration

const axios = require("axios");

async function chatWithNewAssistant() {
  const response = await axios.post(
    "https://api.langdock.com/assistant/v1/chat/completions",
    {
      assistant: {
        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,
          dataAnalyst: true,
        },
        attachmentIds: ["550e8400-e29b-41d4-a716-446655440000"], // Erhalte attachmentIds vom Upload-Attachment-Endpunkt
      },
      messages: [
        {
          role: "user",
          content: "What are the key points in the document?",
        },
      ],
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

  console.log(response.data.result);
}

Verwendung von strukturierter Ausgabe mit Schema (Array)

const axios = require("axios");

async function getStructuredWeather() {
  const response = await axios.post(
    "https://api.langdock.com/assistant/v1/chat/completions",
    {
      assistant: {
        name: "Weather Assistant",
        instructions: "You are a helpful weather agent",
        model: "gpt-5.1",
        capabilities: {
          webSearch: true,
        },
      },
      messages: [
        {
          role: "user",
          content: "What's the weather in paris, berlin and london today?",
        },
      ],
      output: {
        type: "array",
        schema: {
          type: "object",
          properties: {
            weather: {
              type: "object",
              properties: {
                city: {
                  type: "string",
                },
                tempInCelsius: {
                  type: "number",
                },
                tempInFahrenheit: {
                  type: "number",
                },
              },
              required: ["city", "tempInCelsius", "tempInFahrenheit"],
            },
          },
        },
      },
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

  // Access the structured data directly from output
  console.log(response.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 von strukturierter Ausgabe mit Schema (Object)

const axios = require("axios");

async function extractContactInfo() {
  const response = await axios.post(
    "https://api.langdock.com/assistant/v1/chat/completions",
    {
      assistant: {
        name: "Contact Extractor",
        instructions: "You extract contact information from text",
      },
      messages: [
        {
          role: "user",
          content:
            "Extract the contact info: John Smith is our new sales lead. You can reach him at john.smith@example.com or call +1-555-123-4567.",
        },
      ],
      output: {
        type: "object",
        schema: {
          type: "object",
          properties: {
            name: {
              type: "string",
            },
            email: {
              type: "string",
            },
            phone: {
              type: "string",
            },
            role: {
              type: "string",
            },
          },
          required: ["name", "email"],
        },
      },
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

  // Access the structured data directly from output
  console.log(response.data.output);
  // Output:
  // {
  //   "name": "John Smith",
  //   "email": "john.smith@example.com",
  //   "phone": "+1-555-123-4567",
  //   "role": "sales lead"
  // }
}

Verwendung von strukturierter Ausgabe mit Enum

const axios = require("axios");

async function getSentimentAnalysis() {
  const response = await axios.post(
    "https://api.langdock.com/assistant/v1/chat/completions",
    {
      assistant: {
        name: "Sentiment Analyzer",
        instructions: "You analyze the sentiment of text",
      },
      messages: [
        {
          role: "user",
          content:
            "How would you rate this review: 'This product exceeded my expectations!'",
        },
      ],
      output: {
        type: "enum",
        enum: ["positive", "neutral", "negative"],
      },
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

  // Access the enum result directly from output
  console.log(response.data.output);
  // Output: "positive"
}

Rate Limits

Die Rate Limit für den Assistant Completion Endpunkt beträgt 500 RPM (Anfragen pro Minute) und 60,000 TPM (Token pro Minute). Rate Limits werden auf Workspace-Ebene definiert - und nicht auf API-Schlüsselebene. 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.

Antwortformat

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

{
  // Standard message results - always present
  result: Array<{
    id: string;
    role: "tool" | "assistant";
    content: Array<{
      type: string;
      toolCallId?: string;
      toolName?: string;
      result?: object;
      args?: object;
      text?: string;
    }>;
  }>;

  // Structured output - included by default
  output?: object | array | string;
}

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:

// Request
{
  "output": {
    "type": "array",
    "schema": {
      "type": "object",
      "properties": {
        "weather": {
          "type": "object",
          "properties": {
            "city": { "type": "string" },
            "tempInCelsius": { "type": "number" },
            "tempInFahrenheit": { "type": "number" }
          },
          "required": ["city", "tempInCelsius", "tempInFahrenheit"]
        }
      }
    }
  }
}

// Response
{
  "result": [
    // Full conversation including tool calls (e.g., web searches)
    { "role": "assistant", "content": [...], "id": "..." },
    { "role": "tool", "content": [...], "id": "..." },
    { "role": "assistant", "content": "...", "id": "..." }
  ],
  "output": [
    { "weather": { "city": "Paris", "tempInCelsius": 1, "tempInFahrenheit": 33 } },
    { "weather": { "city": "Berlin", "tempInCelsius": 1, "tempInFahrenheit": 35 } },
    { "weather": { "city": "London", "tempInCelsius": 7, "tempInFahrenheit": 45 } }
  ]
}

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

try {
  const response = await axios.post('https://api.langdock.com/assistant/v1/chat/completions', ...);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error('Invalid parameters:', error.response.data.message);
        break;
      case 429:
        console.error('Rate limit exceeded');
        break;
      case 500:
        console.error('Server error');
        break;
    }
  }
}

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:

Agents Completions API - Verwendet das Vercel AI SDK Nachrichtenformat

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

Option 1
Option 2

assistantId

string

erforderlich

ID of an existing agent to use

messages

object[]

erforderlich

Show child attributes

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.

Option 1
Option 2
Option 3

Show child attributes

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

Show child attributes

output

Present when output parameter was specified in the request

Migration von der Assistants API zur Agents API Assistant Get API

⌘I

Documentation Index

​Anfrageparameter

​Nachrichtenformat

​Assistentenkonfiguration

​Tools über die API verwenden

​Strukturierte Ausgabe

​Streaming-Antworten

​Stream-Format

​Streams in JavaScript verarbeiten

​Abrufen von Anhangs-IDs

​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

​Antwortformat

​Standardergebnis

​Strukturierte Ausgabe

​Fehlerbehandlung

​Migration zur Agents API

Autorisierungen

Body

Antwort

Anfrageparameter

Nachrichtenformat

Assistentenkonfiguration

Tools über die API verwenden

Strukturierte Ausgabe

Streaming-Antworten

Stream-Format

Streams in JavaScript verarbeiten

Abrufen von Anhangs-IDs

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

Antwortformat

Standardergebnis

Strukturierte Ausgabe

Fehlerbehandlung

Migration zur Agents API