Zum Hauptinhalt springen
POST
/
agent
/
v1
/
create
Creates a new agent
curl --request POST \
  --url https://api.langdock.com/agent/v1/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "instructions": "<string>",
  "description": "<string>",
  "temperature": 0.5,
  "model": "<string>",
  "capabilities": {
    "webSearch": true,
    "dataAnalyst": true,
    "imageGeneration": true
  },
  "actions": [
    "<unknown>"
  ],
  "vectorDb": [
    "<unknown>"
  ],
  "knowledgeFolderIds": [
    "<string>"
  ],
  "attachmentIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'
{
  "status": "<string>",
  "message": "<string>",
  "agent": {
    "name": "<string>",
    "instructions": "<string>",
    "description": "<string>",
    "temperature": 0.5,
    "model": "<string>",
    "capabilities": {
      "webSearch": true,
      "dataAnalyst": true,
      "imageGeneration": true
    },
    "actions": [
      "<unknown>"
    ],
    "vectorDb": [
      "<unknown>"
    ],
    "knowledgeFolderIds": [
      "<string>"
    ],
    "attachmentIds": [
      "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 createBasicAgent() {
  const response = await axios.post(
    "https://api.langdock.com/agent/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.agent.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: "Agent created successfully";
  agent: {
    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/agent/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
Maximum string length: 64
instructions
string
erforderlich
Maximum string length: 16384
description
string
Maximum string length: 256
temperature
number
Erforderlicher Bereich: 0 <= x <= 1
model
string
Maximum string length: 64
capabilities
object
actions
any[]
vectorDb
any[]
knowledgeFolderIds
string[]
attachmentIds
string<uuid>[]

Array of UUID strings identifying attachments for this message

Antwort

201 - application/json

Agent created successfully

status
string
message
string
agent
object