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"
    ]
  }
}
⚠️ Du nutzt unsere API in einem Dedicated Deployment? Ersetze einfach api.langdock.com durch die Base URL deines Deployments: <deployment-url>/api/public
Dies ist die neue Agents API mit nativer Vercel AI SDK Kompatibilität. Wenn du die veraltete Assistants API verwendest, siehe den Migrations-Guide.
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-80 Zeichen)
descriptionstringNeinBeschreibung der Agentenfunktion (max. 500 Zeichen)
emojistringNeinEmoji-Icon für den Agenten (max. 16 Zeichen, z.B. ”🤖“)
instructionstringNeinSystemanweisung/Instruktionen für den Agenten (max. 40000 Zeichen)
inputTypestringNeinEingabetyp: “PROMPT” oder “STRUCTURED” (Standard: “PROMPT”)
modelstringNeinModell-ID (Deployment-Name von der Models API). Verwendet Workspace-Standard wenn nicht angegeben
creativitynumberNeinTemperatur zwischen 0-1 (Standard: 0.3)
conversationStartersstring[]NeinArray von vorgeschlagenen Prompts zum Einstieg (max. 20, je 1-255 Zeichen)
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)
dataAnalystbooleanNeinZur Kompatibilität akzeptiert. Siehe Warnhinweis unten
canvasbooleanNeinCanvas-Fähigkeit aktivieren (Standard: false)
extendedThinkingbooleanNeinExtended-Thinking-Modus aktivieren (Standard: false)
Der Parameter dataAnalyst ist veraltet und hat keine Wirkung. Anfragen mit diesem Parameter sind aus Gründen der Abwärtskompatibilität weiterhin erfolgreich, aber Langdock ignoriert den Wert und aktiviert weder Dateiarbeit noch Codeausführung. Lass diesen Parameter in neuen Integrationen weg.

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
fileTypesstringNeinErlaubte Dateitypen für FILE-Feldtypen (nullable)
emailDomainstringNeinErlaubte E-Mail-Domain für EMAIL-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
  • EMAIL - E-Mail-Adresse

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"
      ],
      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 createAgents 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 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;
    canvasEnabled: boolean;
    extendedThinking: 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;
      emailDomain: 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 429:
        console.error('Rate Limit überschritten');
        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