Agent Update API

​

Bevor du startest

• API-Key-Scope: Erfordert einen API-Schlüssel mit dem Agenten API-Scope und Bearbeitungszugriff auf den Agenten, den du aktualisieren möchtest.
• Veraltete Assistants API: Dies ist die neue Agents API mit nativer Vercel AI SDK Kompatibilität. Wenn du die veraltete Assistants API verwendest, siehe den Migrations-Guide.
• Entwurfseinstellungen: Konfigurationsänderungen gelten für den Entwurf des Agenten. Freigabeänderungen wirken sofort und erfordern keine Veröffentlichung. Die Antwort dieses Endpoints gibt den Entwurf zurück.

​

Basis-URL

https://api.langdock.com/agent/v1/update

​

Aktualisierungsverhalten

• Partielle Updates - Nur in der Anfrage enthaltene Felder werden aktualisiert; ausgelassene Felder bleiben unverändert
• Array-Felder ersetzen - actions, inputFields, conversationStarters, attachments, knowledgeFolderIds, skillIds, subAgents und workflowIds ersetzen bei Angabe vollständig die vorhandenen Werte
• Leere Arrays - Sende [], um alle Actions, Felder oder Anhänge zu entfernen. Bei skillIds entfernt [] alle Skills. Angehängte Dateivorlagen bleiben bestehen. Bei subAgents und workflowIds entfernt [] jeden Sub-Agenten oder Workflow
• Null-Behandlung - Sende null für emoji, um es zu löschen, und null für icon, um das hochgeladene Bild zu entfernen. Lass icon weg, um das aktuelle Bild zu behalten. icon zu setzen löscht emoji nicht. Für description und instruction sende einen leeren String "" zum Löschen
• Unveränderte Felder - Felder, die nicht in der Anfrage enthalten sind, behalten ihre aktuellen Werte

​

Parameter

​

Zugriffskonfiguration

{
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "access": {
    "users": [{ "id": "550e8400-e29b-41d4-a716-446655440001", "role": null }],
    "workspace": null
  }
}

​

Actions-Konfiguration

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

​

Eingabefelder-Konfiguration

​

Beispiele

​

Grundlegende Eigenschaften aktualisieren

const axios = require("axios");

async function updateAgentName() {
  const response = await axios.patch(
    "https://api.langdock.com/agent/v1/update",
    {
      agentId: "550e8400-e29b-41d4-a716-446655440000",
      name: "Erweiterter Dokumentenanalyst",
      description: "Analysiert Dokumente mit erweiterten Fähigkeiten",
      creativity: 0.7
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      }
    }
  );

  console.log("Agent aktualisiert:", response.data.message);
}

​

Validierungsregeln

• Agent-Zugriff - Ein persönlicher API-Schlüssel kann die Konfiguration ändern, wenn sein Besitzer den Agenten bearbeiten kann, auch über eine Gruppe oder den Workspace, oder wenn der Schlüssel eine Editor- oder Besitzerfreigabe hat. Ein Workspace-API-Schlüssel braucht diese Freigabe auf dem Schlüssel. Die Rolle Nutzer und der Status als Workspace-Admin erlauben keine Konfigurationsänderung.
• Workspace-Übereinstimmung - Der Agent muss zum selben Workspace wie dein API-Schlüssel gehören
• Modell - Falls angegeben, muss es in der Liste der aktiven Modelle deines Workspaces sein
• Actions - Falls angegeben, ersetzt das Array die Liste im Entwurf. Lass eine ID weg, um sie zu entfernen.
• Action-IDs im Entwurf - Fehlende oder gelöschte IDs, die schon im Entwurf stehen, werden weggelassen. Nicht verfügbare IDs, die schon im Entwurf stehen, bleiben.
• Neue Action-IDs - Müssen existieren und zu in deinem Workspace aktivierten Integrationen gehören. Sonst antwortet die Anfrage mit 400 und missingActionIds oder unavailableActionIds.
• Anhänge - Falls angegeben, müssen sie in deinem Workspace existieren und nicht gelöscht sein
• Ordner - Falls angegeben, müssen sie in deinem Workspace existieren und nicht gelöscht sein
• Skills - Falls angegeben, muss jede ID ein Skill sein, den der User, dem der API-Schlüssel gehört, anhängen kann. Dateivorlagen werden abgelehnt. Ein fehlender Skill antwortet mit 400 und missingSkillIds. Ein Skill, den dieser User nicht anhängen kann, antwortet mit 400 und inaccessibleSkillIds
• Sub-Agent- und Workflow-IDs im Entwurf - IDs, die schon im Entwurf stehen, bleiben ohne neue Prüfung. Workflows muss für diese IDs nicht aktiviert sein.
• Neue Sub-Agenten - Jede neue agentId muss ein Agent in deinem Workspace sein, den der User, dem der API-Schlüssel gehört, nutzen kann. Nur direkt, der Agent selbst und Zyklen werden abgelehnt. Ein fehlender Agent antwortet mit 400 und missingSubAgentIds. Ein Agent, den dieser User nicht nutzen kann, oder einer mit Nur direkt, antwortet mit 400 und inaccessibleSubAgentIds. Ein Zyklus oder der Agent selbst antwortet mit 400 und cyclicSubAgentIds
• Neue Workflows - Jede neue ID muss ein aktiver Workflow sein, den der User, dem der API-Schlüssel gehört, nutzen kann. Workflows muss für diesen User aktiviert sein. Ist Workflows nicht aktiviert, antworten neue IDs mit 400 und inaccessibleWorkflowIds. Sonst antwortet ein fehlender Workflow, einschließlich einer Vorlage, mit 400 und missingWorkflowIds, und ein inaktiver Workflow mit 400 und inactiveWorkflowIds. Ein Workflow, den dieser User nicht nutzen kann, antwortet mit 400 und inaccessibleWorkflowIds
• Freigaben - Freigabeberechtigungen und Empfänger werden geprüft, bevor Änderungen gespeichert werden
• Name - Falls angegeben, muss zwischen 1-80 Zeichen sein
• Beschreibung - Falls angegeben, maximal 800 Zeichen
• Instruktion - Falls angegeben, maximal 50000 Zeichen
• Creativity - Falls angegeben, muss zwischen 0 und 1 liegen

​

Antwortformat

​

Erfolgreiche Antwort (200 OK)

{
  status: "success";
  message: "Agent updated successfully";
  agent: {
    id: string;
    name: string;
    description: string | null;
    instruction: string | null;
    emojiIcon: string | null;
    model: string | null;
    temperature: number;
    conversationStarters: string[];
    inputType: "PROMPT" | "STRUCTURED" | "INTEGRATION" | "SCHEDULED" | "WEBHOOK";
    webSearchEnabled: boolean;
    imageGenerationEnabled: boolean;
    canvasEnabled: boolean;
    extendedThinking: boolean;
    actions: Array<{
      actionId: string;
      requiresConfirmation: boolean;
    }>;
    inputFields: Array<{
      type: "TEXT" | "MULTI_LINE_TEXT" | "NUMBER" | "CHECKBOX" | "FILE" | "SELECT" | "MULTI_SELECT" | "DATE" | "EMAIL";
      label: string;
      description: string | null;
      required: boolean;
      order: number;
      slug: string;
      options: string[];
      fileTypes: string | null;
      emailDomain: string | null;
    }>;
    attachments: string[];
    knowledgeFolderIds: string[];
    skillIds: string[];
    subAgents: Array<{
      agentId: string;
      requiresConfirmation: boolean;
    }>;
    workflowIds: string[];
    owner: {
      id: string;
      name: string | null;
      email: string;
    } | null;
    createdAt: string;
    updatedAt: string;
    access?: {
      users: Array<{ id: string; role: "user" | "editor" }>;
      groups: Array<{ id: string; role: "user" | "editor" }>;
      workspace: "user" | "editor" | null;
      sharingManagedByAdmin: boolean;
    };
  };
  preservedUnavailableActionIds?: string[];
}

​

Fehlerbehandlung

try {
  const response = await axios.patch('https://api.langdock.com/agent/v1/update', ...);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error('Ungültige Parameter oder Ressource nicht gefunden:', error.response.data.message);
        break;
      case 401:
        console.error('Ungültiger oder fehlender API-Schlüssel');
        break;
      case 403:
        console.error('Agent nicht gefunden oder API-Schlüssel hat keinen Bearbeitungszugriff');
        break;
      case 404:
        console.error('Freigabeziel nicht gefunden');
        break;
      case 429:
        console.error('Rate Limit überschritten');
        break;
      case 500:
        console.error('Server-Fehler');
        break;
    }
  }
}

​

Best Practices

1. Vor dem Update abrufen - Wenn du vorhandene Array-Werte beibehalten musst, rufe zuerst den bearbeitbaren Entwurf mit version=draft ab. Ein normaler GET gibt die veröffentlichte Version zurück, wenn eine existiert, sonst den Entwurf.
2. Inkrementelle Updates - Aktualisiere nur die Felder, die geändert werden müssen
3. Anhänge validieren - Stelle sicher, dass Anhang-UUIDs gültig sind, bevor du sie einfügst
4. Actions im Entwurf behalten - Schicke jede Action-ID mit, die du behalten willst. Fehlende IDs, die schon im Entwurf stehen, werden weggelassen. Nicht verfügbare IDs, die schon im Entwurf stehen, bleiben.
5. Fehler elegant behandeln - Implementiere eine ordnungsgemäße Fehlerbehandlung für Validierungsfehler