> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Update API
> Einen vorhandenen Agenten programmatisch aktualisieren
**⚠️ Du nutzt unsere API in einem Dedicated Deployment?** Ersetze einfach `api.langdock.com` durch die Base URL deines Deployments: **`/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](/de/developer/assistants-api/assistant-to-agent-migration).
Aktualisiert einen vorhandenen Agenten in deinem Workspace. Nur die von dir angegebenen Felder werden aktualisiert, was partielle Updates ermöglicht, ohne andere Konfigurationen zu beeinflussen.
Änderungen werden nur auf den **Entwurf** des Agenten angewendet. Die aktive (veröffentlichte) Version bleibt unverändert, bis der Agent in der Langdock-Oberfläche veröffentlicht wird. Die Antwort dieses Endpoints gibt den Entwurf zurück.
Erfordert einen API-Schlüssel mit dem `AGENT_API` Scope und Zugriff auf den Agenten, den du aktualisieren möchtest.
## Aktualisierungsverhalten
Der Update-Endpunkt verwendet partielle Update-Semantik mit spezifischem Verhalten für verschiedene Feldtypen:
* **Partielle Updates** - Nur in der Anfrage enthaltene Felder werden aktualisiert; ausgelassene Felder bleiben unverändert
* **Array-Felder ersetzen** - `actions`, `inputFields`, `conversationStarters` und `attachments` ersetzen bei Angabe vollständig die vorhandenen Werte
* **Leere Arrays** - Sende `[]` um alle Actions/Felder/Anhänge zu entfernen
* **Null-Behandlung** - Sende `null` für `emoji` um es zu löschen. 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
## Anfrageparameter
Setze einen der folgenden Parameter, um die aktuellen Einstellungen des Agenten zu überschreiben. Felder, die du weglässt, bleiben unverändert. Nur `agentId` ist erforderlich.
| Parameter | Typ | Erforderlich | Beschreibung |
| ---------------------- | --------- | ------------ | --------------------------------------------------------------------------------------- |
| `agentId` | string | Ja | UUID des zu aktualisierenden Agenten |
| `name` | string | Nein | Name des Agenten (1-80 Zeichen) |
| `description` | string | Nein | Beschreibung (max. 500 Zeichen, `""` zum Löschen) |
| `emoji` | string | Nein | Emoji-Icon (max. 16 Zeichen, null zum Löschen) |
| `instruction` | string | Nein | Systemanweisung (max. 40000 Zeichen, `""` zum Löschen) |
| `model` | string | Nein | Modell-ID (Deployment-Name aus der [Models API](/de/developer/agents-api/agent-models)) |
| `creativity` | number | Nein | Temperatur zwischen 0 und 1 |
| `conversationStarters` | string\[] | Nein | Vorgeschlagene Prompts, max. 20, je 1-255 Zeichen (ersetzt vorhandene) |
| `actions` | array | Nein | Actions (ersetzt vorhandene) |
| `inputFields` | array | Nein | Formularfelder (ersetzt vorhandene) |
| `attachments` | string\[] | Nein | Anhang-UUIDs (ersetzt vorhandene) |
| `webSearch` | boolean | Nein | Websuche aktivieren |
| `imageGeneration` | boolean | Nein | Bildgenerierung aktivieren |
| `dataAnalyst` | boolean | Nein | Zur Kompatibilität akzeptiert. Siehe Warnhinweis unten |
| `inputType` | string | Nein | Eingabetyp: "PROMPT" oder "STRUCTURED" |
| `canvas` | boolean | Nein | Canvas aktivieren |
| `extendedThinking` | boolean | Nein | Extended Thinking aktivieren |
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.
Array-Felder (`actions`, `inputFields`, `conversationStarters`, `attachments`) werden **vollständig ersetzt**, nicht zusammengeführt. Gib immer das vollständige gewünschte Array an, einschließlich aller vorhandenen Elemente, die du behalten möchtest.
### 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
### Eingabefelder-Konfiguration
Für die `inputFields` Array-Struktur, siehe die [Agent Create API](/de/developer/agents-api/agent-create) Dokumentation.
## Beispiele
### Grundlegende Eigenschaften aktualisieren
```javascript theme={null}
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
Die API wendet mehrere Validierungsregeln an:
* **Agent-Zugriff** - Dein API-Schlüssel muss Zugriff auf den Agenten haben
* **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, müssen sie zu in deinem Workspace aktivierten Integrationen gehören
* **Anhänge** - Falls angegeben, müssen sie in deinem Workspace existieren und nicht gelöscht sein
* **Name** - Falls angegeben, muss zwischen 1-80 Zeichen sein
* **Beschreibung** - Falls angegeben, maximal 500 Zeichen
* **Instruktion** - Falls angegeben, maximal 40000 Zeichen
* **Creativity** - Falls angegeben, muss zwischen 0 und 1 liegen
## Antwortformat
### Erfolgreiche Antwort (200 OK)
```typescript theme={null}
{
status: "success";
message: "Agent updated 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
```typescript theme={null}
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:', error.response.data.message);
break;
case 401:
console.error('Ungültiger oder fehlender API-Schlüssel');
break;
case 403:
console.error('Unzureichende Berechtigungen - kein Zugriff auf diesen Agenten');
break;
case 404:
console.error('Agent nicht gefunden oder API-Schlüssel hat keinen Zugriff');
break;
case 429:
console.error('Rate Limit überschritten');
break;
case 500:
console.error('Server-Fehler');
break;
}
}
}
```
## Best Practices
**Vorhandene Werte beibehalten**: Wenn du Array-Felder wie `actions` oder `attachments` aktualisierst, füge immer vorhandene Elemente ein, die du behalten möchtest, da das gesamte Array ersetzt wird.
1. **Vor dem Update abrufen** - Wenn du vorhandene Array-Werte beibehalten musst, rufe zuerst die aktuelle Agent-Konfiguration ab
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 testen** - Überprüfe, dass Actions zu aktivierten Integrationen gehören, bevor du aktualisierst
5. **Fehler elegant behandeln** - Implementiere eine ordnungsgemäße Fehlerbehandlung für Validierungsfehler
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](/de/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
## OpenAPI
````yaml PATCH /agent/v1/update
openapi: 3.0.0
info:
title: Langdock API
version: 3.0.0
servers:
- url: https://api.langdock.com
description: Production
security:
- bearerAuth: []
paths:
/agent/v1/update:
patch:
tags:
- Agent Build
summary: Updates an existing agent
description: Updates an existing agent in your workspace.
operationId: updateAgentV2
requestBody:
required: true
content:
application/json:
schema:
allOf:
- type: object
required:
- agentId
properties:
agentId:
type: string
format: uuid
- $ref: '#/components/schemas/Assistant'
responses:
'200':
description: Agent updated successfully
components:
schemas:
Assistant:
type: object
required:
- name
- instructions
properties:
name:
type: string
maxLength: 64
description:
type: string
maxLength: 256
instructions:
type: string
maxLength: 16384
temperature:
type: number
minimum: 0
maximum: 1
model:
type: string
maxLength: 64
capabilities:
type: object
properties:
webSearch:
type: boolean
dataAnalyst:
type: boolean
deprecated: true
description: Deprecated. Accepted for compatibility and ignored.
imageGeneration:
type: boolean
actions:
type: array
items: 7d19e95b-21e8-417f-995e-24a8f5651c16
vectorDb:
type: array
items: 48adcef5-fb6f-434d-894d-ad23cdeb3651
knowledgeFolderIds:
type: array
items:
type: string
attachmentIds:
type: array
items:
type: string
format: uuid
description: Array of UUID strings identifying attachments for this message
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: API key as Bearer token. Format "Bearer YOUR_API_KEY"
````