Agent API

Erstellt eine Modellantwort für eine bestimmte Agenten-ID oder übergibt eine Agentenkonfiguration, die für deine Anfrage verwendet werden soll.

Um einen Agenten mit einem API-Schlüssel zu teilen, folge dieser Anleitung

Basis-URL

https://api.langdock.com/assistant/v1/chat/completions

Für dedizierte Deployments verwende stattdessen https://<deine-domain>/api/public/assistant/v1/chat/completions.

Anfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
`assistantId`	string	Eines von assistantId/assistant erforderlich	ID eines vorhandenen Agenten zur Verwendung
`assistant`	object	Eines von assistantId/assistant erforderlich	Konfiguration für einen neuen Agenten
`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

Agentenkonfiguration

Bei der Erstellung eines temporären Agenten kannst du Folgendes angeben:

name (erforderlich) - Name des Agenten (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 Agentenkonfiguration 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:

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)

Der output Parameter-Verhalten 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.

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 Agentengesprä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 Agenten- oder Nachrichtenkonfiguration einfügen kannst.

Beispiele

Verwendung eines vorhandenen Agenten

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 Agentenkonfiguration

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-4",
        capabilities: {
          webSearch: true,
          dataAnalyst: true,
        },
        attachmentIds: ["550e8400-e29b-41d4-a716-446655440000"], // Obtain attachmentIds from upload attachment endpoint
      },
      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 Agent",
        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 [email protected] 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": "[email protected]",
  //   "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 Agent 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 [email protected].

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 Agent, 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 Agenten 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;
    }
  }
}

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

Anzeigen untergeordnete attribute

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

Anzeigen untergeordnete attribute

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

Anzeigen untergeordnete attribute

output

Present when output parameter was specified in the request

Überblick

Completion API

Embedding API

Knowledge Folder API

Usage Export API

Agent API

Basis-URL

Anfrageparameter

Nachrichtenformat

Agentenkonfiguration

Tools über die API verwenden

Strukturierte Ausgabe

Streaming-Antworten

Stream-Format

Streams in JavaScript verarbeiten

Abrufen von Anhangs-IDs

Beispiele

Verwendung eines vorhandenen Agenten

Verwendung einer temporären Agentenkonfiguration

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

Autorisierungen

Body

Antwort

Überblick

Completion API

Embedding API

Agent API

Knowledge Folder API

Usage Export API

​Basis-URL

​Anfrageparameter

​Nachrichtenformat

​Agentenkonfiguration

​Tools über die API verwenden

​Strukturierte Ausgabe

​Streaming-Antworten

​Stream-Format

​Streams in JavaScript verarbeiten

​Abrufen von Anhangs-IDs

​Beispiele

​Verwendung eines vorhandenen Agenten

​Verwendung einer temporären Agentenkonfiguration

​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

Autorisierungen

Body

Antwort

Basis-URL

Anfrageparameter

Nachrichtenformat

Agentenkonfiguration

Tools über die API verwenden

Strukturierte Ausgabe

Streaming-Antworten

Stream-Format

Streams in JavaScript verarbeiten

Abrufen von Anhangs-IDs

Beispiele

Verwendung eines vorhandenen Agenten

Verwendung einer temporären Agentenkonfiguration

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