Assistant Create API

Einen neuen Assistenten programmatisch erstellen

POST /assistant/v1/create

cURL

basicAgent

curl --request POST \ --url https://api.langdock.com/assistant/v1/create \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "name": "Document Analyzer", "description": "Analyzes and summarizes documents", "emoji": "📄", "instruction": "You are a helpful agent that analyzes documents.", "creativity": 0.5, "dataAnalyst": true } '

201

{
  "status": "success",
  "message": "Assistant created successfully"
}

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 einen neuen Assistenten in deinem Workspace programmatisch. Der erstellte Assistent kann über den Chat-Completions-Endpunkt verwendet oder über die Langdock-Benutzeroberfläche aufgerufen werden.

Erfordert einen API-Schlüssel mit dem AGENT_API Scope. Erstellte Assistenten werden automatisch mit dem API-Schlüssel geteilt, um sie in Chat-Completions zu verwenden.

​

Anfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
name	string	Ja	Name des Assistenten (1-80 Zeichen)
description	string	Nein	Beschreibung der Assistentenfunktion (max. 500 Zeichen)
emoji	string	Nein	Emoji-Icon für den Assistenten (z.B. ”🤖“)
instruction	string	Nein	Systemanweisung/Instruktionen für den Assistenten (max. 40000 Zeichen)
inputType	string	Nein	Eingabetyp: “PROMPT” oder “STRUCTURED” (Standard: “PROMPT”)
model	string	Nein	Zu verwendende Modell-UUID (verwendet Workspace-Standard wenn nicht angegeben)
creativity	number	Nein	Temperatur zwischen 0-1 (Standard: 0.3)
conversationStarters	string[]	Nein	Array von vorgeschlagenen Prompts zum Einstieg
actions	array	Nein	Array von Action-Objekten für benutzerdefinierte Integrationen
inputFields	array	Nein	Array von Formularfeld-Definitionen (für STRUCTURED Eingabetyp)
attachments	string[]	Nein	Array von Anhang-UUIDs für den Assistenten
webSearch	boolean	Nein	Websuche-Fähigkeit aktivieren (Standard: false)
imageGeneration	boolean	Nein	Bildgenerierungs-Fähigkeit aktivieren (Standard: false)
dataAnalyst	boolean	Nein	Code-Interpreter-Fähigkeit aktivieren (Standard: false)
canvas	boolean	Nein	Canvas-Fähigkeit aktivieren (Standard: false)

​

Actions-Konfiguration

Jede Action im actions Array sollte enthalten:

• actionId (erforderlich) - UUID der Action aus einer aktivierten Integration
• requiresConfirmation (optional) - Ob vor der Ausführung eine Benutzerbestätigung erforderlich ist (Standard: true)

Nur Actions von in deinem Workspace aktivierten Integrationen können verwendet werden.

​

Eingabefelder-Konfiguration

Bei Verwendung von inputType: "STRUCTURED" kannst du Formularfelder im inputFields Array definieren:

Feld	Typ	Erforderlich	Beschreibung
slug	string	Ja	Eindeutiger Bezeichner für das Feld
type	string	Ja	Feldtyp (siehe unterstützte Typen unten)
label	string	Ja	Anzeigebezeichnung für das Feld
description	string	Nein	Hilfetext für das Feld
required	boolean	Nein	Ob das Feld erforderlich ist (Standard: false)
order	number	Ja	Anzeigereihenfolge (0-indiziert)
options	string[]	Nein	Optionen für SELECT-Feldtypen
fileTypes	string[]	Nein	Erlaubte Dateitypen für FILE-Feldtypen

Unterstützte Feldtypen:

• TEXT - Einzeilige Texteingabe
• MULTI_LINE_TEXT - Mehrzeiliger Textbereich
• NUMBER - Numerische Eingabe
• CHECKBOX - Boolean-Checkbox
• FILE - Datei-Upload
• SELECT - Dropdown-Auswahl
• DATE - Datumsauswahl

​

Anhangs-IDs abrufen

Um Anhänge in deinen Assistenten einzubinden, lade zuerst Dateien mit der Upload Attachment API hoch. Dies gibt Anhang-UUIDs zurück, die du im attachments Array verwenden kannst.

​

Beispiele

​

Einen einfachen Assistenten erstellen

const axios = require("axios");

async function createBasicAssistant() {
  const response = await axios.post(
    "https://api.langdock.com/assistant/v1/create",
    {
      name: "Dokumentenanalyse",
      description: "Analysiert und fasst Dokumente zusammen",
      emoji: "📄",
      instruction: "Du bist ein hilfreicher Assistent, der Dokumente analysiert und klare Zusammenfassungen der wichtigsten Informationen liefert.",
      creativity: 0.5,
      conversationStarters: [
        "Fasse dieses Dokument zusammen",
        "Was sind die wichtigsten Punkte?",
        "Extrahiere Aktionspunkte"
      ],
      dataAnalyst: true,
      webSearch: false
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      }
    }
  );

  console.log("Assistent erstellt:", response.data.assistant.id);
}

​

Validierungsregeln

Die API wendet mehrere Validierungsregeln an:

• Modell - Muss in der Liste der aktiven Modelle deines Workspaces sein
• Actions - Müssen zu in deinem Workspace aktivierten Integrationen gehören
• Anhänge - Müssen in deinem Workspace existieren und nicht gelöscht sein
• Berechtigungen - Dein API-Schlüssel muss die createAssistants Berechtigung haben
• Name - Muss zwischen 1-80 Zeichen sein
• Beschreibung - Maximal 500 Zeichen
• Instruktion - Maximal 40000 Zeichen
• Creativity - Muss zwischen 0 und 1 liegen

​

Wichtige Hinweise

Vorausgewählte OAuth-Verbindungen werden über die API nicht unterstützt. Benutzer müssen OAuth-Verbindungen über die Langdock-Benutzeroberfläche konfigurieren.

• Erstellte Assistenten werden automatisch mit deinem API-Schlüssel für die Verwendung in Chat-Completions geteilt
• Der Ersteller des API-Schlüssels wird zum Eigentümer und kann den Assistenten in der Benutzeroberfläche verwalten
• Anhänge sind bidirektional mit dem Assistenten verknüpft
• Der Assistenten-Typ wird auf AGENT gesetzt (nicht WORKFLOW oder PROJECT)
• createdBy und workspaceId werden automatisch aus deinem API-Schlüssel übernommen

​

Antwortformat

​

Erfolgreiche Antwort (201 Created)

{
  status: "success";
  message: "Assistant created successfully";
  assistant: {
    id: string;
    name: string;
    description: string;
    instruction: string;
    emojiIcon: string;
    model: string;
    temperature: number;
    conversationStarters: string[];
    inputType: "PROMPT" | "STRUCTURED";
    webSearchEnabled: boolean;
    imageGenerationEnabled: boolean;
    codeInterpreterEnabled: boolean;
    canvasEnabled: boolean;
    actions: Array<{
      actionId: string;
      requiresConfirmation: boolean;
    }>;
    inputFields: Array<{
      slug: string;
      type: string;
      label: string;
      description: string;
      required: boolean;
      order: number;
      options: string[];
      fileTypes: string[] | null;
    }>;
    attachments: string[];
    createdAt: string;
    updatedAt: string;
  };
}

​

Fehlerbehandlung

try {
  const response = await axios.post('https://api.langdock.com/assistant/v1/create', ...);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error('Ungültige Parameter:', error.response.data.message);
        break;
      case 401:
        console.error('Ungültiger oder fehlender API-Schlüssel');
        break;
      case 403:
        console.error('Unzureichende Berechtigungen - erfordert AGENT_API Scope');
        break;
      case 404:
        console.error('Ressource nicht gefunden (Modell, Action oder Anhang)');
        break;
      case 500:
        console.error('Server-Fehler');
        break;
    }
  }
}

​

Migration zur Agents API

Die neue Agents API bietet verbesserte Kompatibilität mit modernen AI SDKs. Der Create-Endpunkt hat ähnliche Funktionalität mit aktualisierten Parameternamen.

Siehe den entsprechenden Endpunkt in der Agents API:

• Agent Create API - Verwendet agentId statt assistantId

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

name · string · erforderlich

Name of the agent

Required string length: 1 - 255

description · string

Description of what the agent does

Maximum string length: 256

emoji · string

Emoji icon for the agent (e.g., "🤖")

instruction · string

System prompt/instructions for the agent

Maximum string length: 16384

inputType · enum<string> · Standard: PROMPT

Input type for the agent

Verfügbare Optionen: PROMPT, STRUCTURED

model · string

Model ID to use (see Models for Agent API)

creativity · number · Standard: 0.3

Temperature for response generation

Erforderlicher Bereich: 0 <= x <= 1

conversationStarters · string[]

Array of suggested prompts to help users get started

actions · object[]

Array of action objects for custom integrations

Show child attributes

inputFields · object[]

Array of form field definitions (for STRUCTURED input type)

Show child attributes

attachments · string<uuid>[]

Array of attachment UUIDs to include with the agent

webSearch · boolean · Standard: false

Enable web search capability

imageGeneration · boolean · Standard: false

Enable image generation capability

dataAnalyst · boolean · Standard: false

Enable code interpreter capability

canvas · boolean · Standard: false

Enable canvas capability

Antwort

201

application/json

Agent created successfully

status · enum<string> · erforderlich

Verfügbare Optionen: success

message · string · erforderlich

Beispiel:

"Assistant created successfully"

assistant · object

Show child attributes