Zum Hauptinhalt springen
POST
/
agent
/
v1
/
chat
/
completions
Creates a chat completion with an agent (Vercel AI SDK compatible)
curl --request POST \
  --url https://api.langdock.com/agent/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": "agent_123",
  "messages": [
    {
      "id": "msg_1",
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "Hello, how can you help me?"
        }
      ]
    }
  ],
  "stream": true
}
'
{
  "id": "<string>",
  "role": "assistant",
  "parts": [
    {}
  ],
  "output": "<unknown>"
}
⚠️ 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

ParameterTypErforderlichBeschreibung
agentIdstringEines von agentId/agent erforderlichID eines vorhandenen Agenten
agentobjectEines von agentId/agent erforderlichKonfiguration für einen temporären Agenten
messagesarrayJaArray von UIMessage-Objekten (Vercel AI SDK Format)
streambooleanNeinStreaming-Antworten aktivieren (Standard: false)
outputobjectNeinSpezifikation für strukturiertes Ausgabeformat
maxStepsintegerNeinMaximale Anzahl von Tool-Schritten (1-20)
imageResponseFormatstringNeinAntwortformat für vom Agenten generierte Bilder. "url" gibt eine signierte URL zurück, "b64_json" gibt base64-kodierte Bilddaten zurück.

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:
interface UIMessage {
  id: string;           // Eindeutige Kennung für diese Nachricht
  role: 'system' | 'user' | 'assistant';
  parts: MessagePart[]; // Array von Nachrichtenteilen
  metadata?: {          // Optionale Metadaten
    attachments?: string[];  // Array von Attachment-UUIDs
  };
}

Nachrichtenteil-Typen

User-Nachrichtenteile (zum Senden):
TypFelderBeschreibung
texttype: "text", text: stringKlartext-Inhalt
filetype: "file", mediaType: string, url: string, filename?: stringInline-Dateireferenz
Agent-Nachrichtenteile (in Antworten zurückgegeben — füge sie in den Gesprächsverlauf ein, wenn du Folgenachrichten sendest):
TypWichtige FelderBeschreibung
texttype: "text", text: stringTextantwort
reasoningtype: "reasoning", text: stringModell-Reasoning / Chain-of-Thought
tool-{name}type: "tool-{name}", toolCallId: string, state: "input-streaming" | "input-available" | "output-available" | "output-error", input?: any, output?: any, errorText?: stringTool-Aufruf und Ergebnis
source-urltype: "source-url", sourceId: string, url: string, title?: stringWeb-Quellenreferenz
source-documenttype: "source-document", sourceId: string, mediaType: string, title: string, filename?: stringDokumenten-Quellenreferenz

Beispielnachrichten

User-Nachricht mit Text

{
  id: "msg_1",
  role: "user",
  parts: [
    {
      type: "text",
      text: "Hallo, wie geht es dir?"
    }
  ]
}

User-Nachricht mit Attachment

{
  id: "msg_2",
  role: "user",
  parts: [
    {
      type: "text",
      text: "Bitte analysiere dieses Dokument"
    }
  ],
  metadata: {
    attachments: ["550e8400-e29b-41d4-a716-446655440000"]
  }
}
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

{
  id: "msg_3",
  role: "assistant",
  parts: [
    {
      type: "tool-webSearch",
      toolCallId: "call_123",
      state: "output-available",
      input: {
        query: "latest news"
      },
      output: { /* Suchergebnisse */ }
    }
  ]
}

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, Datenanalyse, Bilderzeugung, Canvas
  • 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.
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:
FeldTypBeschreibung
type”object” | “array” | “enum”Der Typ der strukturierten Ausgabe
schemaobjectJSON-Schema-Definition für die Ausgabe (für object/array-Typen)
enumstring[]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 im Vercel AI SDK Streaming-Format zurück, kompatibel mit dem useChat Hook und anderen Vercel AI SDK Features.

Verwendung mit dem Vercel AI SDK useChat Hook

'use client';

import { useChat } from '@ai-sdk/react';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    api: 'https://api.langdock.com/agent/v1/chat/completions',
    headers: {
      'Authorization': `Bearer ${process.env.NEXT_PUBLIC_LANGDOCK_API_KEY}`
    },
    body: {
      agentId: 'your-agent-id'
    }
  });

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          {m.role === 'user' ? 'User: ' : 'AI: '}
          {m.content}
        </div>
      ))}

      <form onSubmit={handleSubmit}>
        <input
          value={input}
          placeholder="Schreib etwas..."
          onChange={handleInputChange}
        />
      </form>
    </div>
  );
}

Manuelle Stream-Verarbeitung

const response = await fetch('https://api.langdock.com/agent/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agentId: 'agent_123',
    messages: [
      {
        id: 'msg_1',
        role: 'user',
        parts: [{ type: 'text', text: '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);
  console.log(chunk);  // Streaming-Chunks verarbeiten
}

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:
interface CompletionResponse {
  messages: Array<{
    id: string;
    role: "assistant";
    content: string;
  }>;

  // Strukturierte Ausgabe - enthalten wenn angefordert
  output?: object | array | string;
}

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

const response = await fetch(
  "https://api.langdock.com/agent/v1/chat/completions",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      agentId: "agent_123",
      messages: [
        {
          id: "msg_1",
          role: "user",
          parts: [
            {
              type: "text",
              text: "Kannst du dieses Dokument für mich analysieren?"
            }
          ],
          metadata: {
            attachments: ["550e8400-e29b-41d4-a716-446655440000"]
          }
        }
      ]
    })
  }
);

const data = await response.json();
const responseText = data.messages[0].content;
console.log(responseText);

Verwendung einer temporären Agentenkonfiguration

const response = await fetch(
  "https://api.langdock.com/agent/v1/chat/completions",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      agent: {
        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
        }
      },
      messages: [
        {
          id: "msg_1",
          role: "user",
          parts: [
            {
              type: "text",
              text: "Was sind die wichtigsten Punkte im Dokument?"
            }
          ]
        }
      ]
    })
  }
);

const data = await response.json();
console.log(data);

Verwendung von strukturierter Ausgabe mit Schema

const response = await fetch(
  "https://api.langdock.com/agent/v1/chat/completions",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      agent: {
        name: "Weather Agent",
        instructions: "You are a helpful weather agent",
        model: "gpt-5",
        capabilities: {
          webSearch: true
        }
      },
      messages: [
        {
          id: "msg_1",
          role: "user",
          parts: [
            {
              type: "text",
              text: "Wie ist das Wetter heute in Paris, Berlin und London?"
            }
          ]
        }
      ],
      output: {
        type: "array",
        schema: {
          type: "object",
          properties: {
            weather: {
              type: "object",
              properties: {
                city: { type: "string" },
                tempInCelsius: { type: "number" },
                tempInFahrenheit: { type: "number" }
              },
              required: ["city", "tempInCelsius", "tempInFahrenheit"]
            }
          }
        }
      }
    })
  }
);

const data = await response.json();
console.log(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 mit Next.js Server Actions

// app/actions.ts
'use server';

import { generateId } from 'ai';

export async function chatWithAgent(message: string) {
  const response = await fetch(
    'https://api.langdock.com/agent/v1/chat/completions',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.LANGDOCK_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        agentId: process.env.AGENT_ID,
        messages: [
          {
            id: generateId(),
            role: 'user',
            parts: [
              {
                type: 'text',
                text: message
              }
            ]
          }
        ]
      })
    }
  );

  const data = await response.json();
  return data.messages[0].content;
}

Rate Limits

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

Fehlerbehandlung

try {
  const response = await fetch('https://api.langdock.com/agent/v1/chat/completions', options);

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Request failed');
  }

  const data = await response.json();
  // Antwort verarbeiten
} catch (error) {
  console.error('Error:', error.message);
}
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