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"
    ]
  }
}
Erstellt einen neuen Agenten in deinem Workspace programmatisch. Der erstellte Agent 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 Agenten werden automatisch mit dem API-Schlüssel geteilt, um sie in Chat-Completions zu verwenden.

Anfrageparameter

ParameterTypErforderlichBeschreibung
namestringJaName des Agenten (1-255 Zeichen)
descriptionstringNeinBeschreibung der Agentenfunktion (max. 256 Zeichen)
emojistringNeinEmoji-Icon für den Agenten (z.B. ”🤖“)
instructionstringNeinSystemanweisung/Instruktionen für den Agenten (max. 16384 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 Agenten
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: false)
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 Agenten 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 Agenten erstellen

const axios = require("axios");

async function createBasicAssistant() {
  const response = await axios.post(
    "https://api.langdock.com/api/public/assistant/v1/create",
    {
      name: "Dokumentenanalyse",
      description: "Analysiert und fasst Dokumente zusammen",
      emoji: "📄",
      instruction: "Du bist ein hilfreicher Agent, 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("Agent 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-255 Zeichen sein
  • Beschreibung - Maximal 256 Zeichen
  • Instruktion - Maximal 16384 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 Agenten 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 Agenten in der Benutzeroberfläche verwalten
  • Anhänge sind bidirektional mit dem Agenten verknüpft
  • Der Agent-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/api/public/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;
    }
  }
}
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