Zum Hauptinhalt springen
POST
/
assistant
/
v1
/
create
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
}
'
{
  "status": "success",
  "message": "Assistant created successfully",
  "assistant": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "emojiIcon": "<string>",
    "model": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "temperature": 0.5,
    "inputType": "PROMPT",
    "webSearchEnabled": true,
    "imageGenerationEnabled": true,
    "codeInterpreterEnabled": true,
    "canvasEnabled": true,
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "description": "<string>",
    "instruction": "<string>",
    "conversationStarters": [
      "<string>"
    ],
    "actions": [
      {
        "actionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "requiresConfirmation": true
      }
    ],
    "inputFields": [
      {
        "slug": "<string>",
        "type": "TEXT",
        "label": "<string>",
        "required": true,
        "order": 1,
        "description": "<string>",
        "options": [
          "<string>"
        ],
        "fileTypes": [
          "<string>"
        ]
      }
    ],
    "attachments": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ]
  }
}
Die Assistants API wird in einem zukünftigen Release 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

ParameterTypErforderlichBeschreibung
namestringJaName des Assistenten (1-80 Zeichen)
descriptionstringNeinBeschreibung der Assistentenfunktion (max. 500 Zeichen)
emojistringNeinEmoji-Icon für den Assistenten (z.B. ”🤖“)
instructionstringNeinSystemanweisung/Instruktionen für den Assistenten (max. 40000 Zeichen)
inputTypestringNeinEingabetyp: “PROMPT” oder “STRUCTURED” (Standard: “PROMPT”)
modelstringNeinZu verwendende Modell-UUID (verwendet Workspace-Standard wenn nicht angegeben)
creativitynumberNeinTemperatur zwischen 0-1 (Standard: 0.3)
conversationStartersstring[]NeinArray von vorgeschlagenen Prompts zum Einstieg
actionsarrayNeinArray von Action-Objekten für benutzerdefinierte Integrationen
inputFieldsarrayNeinArray von Formularfeld-Definitionen (für STRUCTURED Eingabetyp)
attachmentsstring[]NeinArray von Anhang-UUIDs für den Assistenten
webSearchbooleanNeinWebsuche-Fähigkeit aktivieren (Standard: false)
imageGenerationbooleanNeinBildgenerierungs-Fähigkeit aktivieren (Standard: false)
dataAnalystbooleanNeinCode-Interpreter-Fähigkeit aktivieren (Standard: false)
canvasbooleanNeinCanvas-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:
FeldTypErforderlichBeschreibung
slugstringJaEindeutiger Bezeichner für das Feld
typestringJaFeldtyp (siehe unterstützte Typen unten)
labelstringJaAnzeigebezeichnung für das Feld
descriptionstringNeinHilfetext für das Feld
requiredbooleanNeinOb das Feld erforderlich ist (Standard: false)
ordernumberJaAnzeigereihenfolge (0-indiziert)
optionsstring[]NeinOptionen für SELECT-Feldtypen
fileTypesstring[]NeinErlaubte 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:
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<uuid>

Model UUID to use (uses workspace default if not provided)

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

inputFields
object[]

Array of form field definitions (for STRUCTURED input type)

attachments
string<uuid>[]

Array of attachment UUIDs to include with the agent

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

Agent created successfully

status
enum<string>
erforderlich
Verfügbare Optionen:
success
message
string
erforderlich
Beispiel:

"Assistant created successfully"

assistant
object