> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuwacom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents-API Übersicht

> Agents in deinem nuwacom Workspace programmatisch erstellen, verwalten und nutzen

Mit der Agents-API kannst du Agents in deinem nuwacom Workspace programmatisch erstellen, verwalten und nutzen, zum Beispiel um Agents aus eigenen Tools heraus anzulegen, Agent-Instruktionen mit einer externen Quelle synchron zu halten oder eigene Chat-Erlebnisse darauf aufzubauen.

## Bevor du startest

* **API-Key**: Alle Endpunkte erfordern einen Bearer-Token. Admins können API-Keys in den Workspace-Einstellungen im Bereich **API Keys** erstellen.
* **Space-Bezug**: Agents gehören immer zu einem Space, daher sind alle Endpunkte unter dem Space-Pfad verschachtelt (`/api/v1/spaces/{spaceId}/agents`). Die Rolle des Aufrufers in diesem Space muss Leserechte für das Agents-Feature haben, um Agents aufzulisten oder abzurufen, und Schreibrechte, um sie zu erstellen, zu ändern oder zu löschen.
* **Entwurf & veröffentlichte Version**: Erstellen und Ändern schreibt in den **Entwurf** des Agents. [Veröffentlichen](/api-reference/agents/publish-an-agent) macht den Entwurf zur Live-Version, die die Completion-API standardmäßig verwendet. API-Antworten zeigen immer den Entwurfsstand. Das Feld `published` zeigt an, ob eine veröffentlichte Version existiert, und `hasUnpublishedChanges`, ob der Entwurf davon abweicht. Wer den Agent sehen und nutzen kann, wird separat über das Teilen in der nuwacom App gesteuert.
* **Nur eigene Agents**: Eingebaute nuwacom System-Agents werden über diese API weder gelistet noch ausgelesen. Es erscheinen nur Agents, die im Space angelegt wurden (über diese API oder die App). Mit einem System-Agent kannst du weiterhin über die [Completion-API](/api-reference/completion-api/openai-chat-completion) chatten, wenn du dessen ID bereits kennst.

## Base URL

```
https://{customer-tenant}.nuwacom.ai
```

Ersetze `{customer-tenant}` durch den Tenant-Namen deines Workspace.

## Verfügbare Endpunkte

### Agents

| Methode | Endpunkt | Beschreibung |
| - | - | - |
| `GET` | `/api/v1/spaces/{spaceId}/agents` | [Agents auflisten](/api-reference/agents/list-agents) |
| `POST` | `/api/v1/spaces/{spaceId}/agents` | [Neuen Agent erstellen](/api-reference/agents/create-an-agent) |
| `GET` | `/api/v1/spaces/{spaceId}/agents/{agentId}` | [Agent-Details abrufen](/api-reference/agents/get-an-agent) |
| `PATCH` | `/api/v1/spaces/{spaceId}/agents/{agentId}` | [Agent aktualisieren](/api-reference/agents/update-an-agent) |
| `POST` | `/api/v1/spaces/{spaceId}/agents/{agentId}/publish` | [Agent veröffentlichen](/api-reference/agents/publish-an-agent) |
| `POST` | `/api/v1/spaces/{spaceId}/agents/{agentId}/unpublish` | [Veröffentlichung zurückziehen](/api-reference/agents/unpublish-an-agent) |
| `DELETE` | `/api/v1/spaces/{spaceId}/agents/{agentId}` | [Agent löschen](/api-reference/agents/delete-an-agent) |

### Verwandte Endpunkte

| Methode | Endpunkt | Beschreibung |
| - | - | - |
| `POST` | `/api/v1/openai/chat/completions` | [Mit einem Agent chatten](/api-reference/completion-api/openai-chat-completion) über die Option `agentId` |
| `GET` | `/api/ai/models` | [Verfügbare Modelle auflisten](/api-reference/ai/list-all-ai-models) |

## Pagination

[Agents auflisten](/api-reference/agents/list-agents) ist paginiert. Steuere die Seite über zwei optionale Query-Parameter:

| Parameter | Typ | Beschreibung |
| - | - | - |
| `limit` | integer | Maximale Anzahl zurückgegebener Agents (1–100). Standard: `50`. |
| `offset` | integer | Anzahl der zu überspringenden Agents am Anfang der Liste. Standard: `0`. |

Die Antwort ist eine Envelope: Die Agents stehen in `data`, zusammen mit den Pagination-Metadaten.

```json theme={null}
{
  "data": [ { "id": "…", "name": "Support Agent", "published": true } ],
  "total": 128,
  "limit": 50,
  "offset": 0,
  "hasMore": true
}
```

Blättere durch die gesamte Liste, indem du `offset` um `limit` erhöhst, bis `hasMore` gleich `false` ist:

```bash theme={null}
curl "https://{customer-tenant}.nuwacom.ai/api/v1/spaces/DEINE_SPACE_ID/agents?limit=50&offset=50" \
  -H "Authorization: Bearer $NUWACOM_API_KEY"
```

## Mit einem Agent chatten

Nutze die OpenAI-kompatible [Completion-API](/api-reference/completion-api/openai-chat-completion) und übergib die ID des Agents als `agentId`. Die komplette Konfiguration des Agents (System-Prompt, Wissensquellen, Modell-Optionen) wird automatisch angewendet:

```bash theme={null}
curl https://{customer-tenant}.nuwacom.ai/api/v1/openai/chat/completions \
  -H "Authorization: Bearer $NUWACOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "space_id": "DEINE_SPACE_ID",
    "agentId": "DEINE_AGENT_ID",
    "model": "azure-gpt-4o",
    "messages": [
      { "role": "user", "content": "Hallo!" }
    ]
  }'
```

Das Feld `model` ist Pflicht und dient als Fallback; hat der Agent in seinen `options` ein Modell konfiguriert, gewinnt das Modell des Agents.

Standardmäßig wird die **veröffentlichte** Version des Agents verwendet. Um mit einem Agent zu chatten, der nur als Entwurf existiert (zum Beispiel direkt nach dem Erstellen über die API), übergib zusätzlich `"agentPublished": false`.

## Beispiel: Agent erstellen

```bash theme={null}
curl -X POST https://{customer-tenant}.nuwacom.ai/api/v1/spaces/DEINE_SPACE_ID/agents \
  -H "Authorization: Bearer $NUWACOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support-Agent",
    "description": "Beantwortet Fragen aus dem Kundensupport",
    "systemInstruction": "Du bist ein freundlicher Support-Agent. Antworte prägnant.",
    "conversationStarters": [
      { "text": "Wobei kannst du mir helfen?" }
    ],
    "model": "azure-gpt-4o",
    "temperature": 0.3,
    "attachmentIds": ["DEINE_ASSET_ID_NACH_UPLOAD"]
  }'
```

Lade Dateien zuerst über [Asset hochladen](/api-reference/assets/upload-an-asset) hoch und übergib die zurückgegebene `id` in `attachmentIds`. Für Knowledge-Ordner und nuwacom-Dokumente nutze `folderIds` bzw. `contentIds`.

Die verfügbaren Modell-IDs für `model` findest du über [Verfügbare Modelle auflisten](/api-reference/ai/list-all-ai-models).

Die Antwort enthält die `id` des neuen Agents sowie alle seine Einstellungen. Der Agent startet als unveröffentlichter Entwurf (`published: false`); mit [Agent veröffentlichen](/api-reference/agents/publish-an-agent) machst du ihn zur Live-Version.

## Actions

Actions sind die Werkzeuge, die ein Agent während eines Chats aufrufen kann – eingebaute nuwacom-Tools (z. B. Websuche oder Wissensabruf), die Tools eines [MCP](https://modelcontextprotocol.io)-Servers oder Actions einer verbundenen Integration (Gmail, Outlook, …). Konfiguriere sie über das `actions`-Array beim [Erstellen](/api-reference/agents/create-an-agent) und [Aktualisieren](/api-reference/agents/update-an-agent).

Jede Action hat folgende Felder:

| Feld | Typ | Beschreibung |
| - | - | - |
| `integration` | string | Anbieter der Action: `"nuwacom"` für eingebaute Tools, `"MCP"` für einen MCP-Server oder ein verbundener Integrationstyp (z. B. `"gmail"`). |
| `key` | string | Action-Key innerhalb der Integration. Für `nuwacom` einer der unten gelisteten eingebauten Keys; für eine Integration oder einen MCP-Server der exakte Tool-Key des Anbieters (z. B. `"GMAIL_SEND_EMAIL"`). |
| `requiresConfirmation` | boolean | Ob der Nutzer vor Ausführung bestätigen muss. Standard: `false`. |
| `defaultValues` | object | Voreingestellte Parameterwerte, die bei jeder Ausführung angewendet werden. Standard: `{}`. |
| `integrationId` | string | ID der konkreten verbundenen Integrations-Instanz (bei Anbieter-Integrationen). Optional. |
| `mcpClientId` | string | ID des MCP-Clients, der diese Action bereitstellt. Für `"MCP"`-Actions erforderlich. |

### Eingebaute nuwacom-Action-Keys

Wenn `integration` gleich `"nuwacom"` ist, muss `key` einer der app-unterstützten eingebauten Tools sein:

| `key` | Beschreibung |
| - | - |
| `WEB_SEARCH` | Websuche. |
| `RETRIEVE_FROM_KNOWLEDGE_BASE` | Abruf aus den Wissensquellen des Agents. |
| `DISPLAY_DOCUMENT` | Dokument im Chat darstellen. |
| `DISPLAY_SLIDES` | Folien im Chat darstellen. |
| `DISPLAY_EMAIL` | E-Mail-Entwurf im Chat darstellen. |
| `IMAGE_GENERATION` | Bilder generieren. |
| `VIDEO_GENERATION` | Videos generieren. |

<Warning>
  Nur die obigen Keys sind für `nuwacom`-Actions gültig. Andere interne nuwacom-Keys (z. B. `RETRIEVE_FROM_CONTENT`) sind nicht über die API konfigurierbar – die API akzeptiert sie zwar, sie sind aber kein nutzerseitiges Tool und werden in der App nicht korrekt dargestellt. Für Integrations- oder MCP-Actions den exakten Key des jeweiligen Anbieters/Servers verwenden.
</Warning>

<Note>
  Beim Aktualisieren **ersetzt** das `actions`-Array die aktuellen Entwurfs-Actions des Agents vollständig. Sende die komplette gewünschte Menge oder `[]`, um alle zu entfernen. Wird `actions` weggelassen, bleiben sie unverändert. Wie andere Änderungen wirken sich Action-Bearbeitungen auf den Entwurf aus – [veröffentliche](/api-reference/agents/publish-an-agent) den Agent, damit sie für die Completion-API wirksam werden.
</Note>

```bash theme={null}
curl -X POST https://{customer-tenant}.nuwacom.ai/api/v1/spaces/DEINE_SPACE_ID/agents \
  -H "Authorization: Bearer $NUWACOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Recherche-Agent",
    "systemInstruction": "Du recherchierst Themen mithilfe der Websuche.",
    "actions": [
      { "integration": "nuwacom", "key": "WEB_SEARCH" },
      { "integration": "nuwacom", "key": "RETRIEVE_FROM_KNOWLEDGE_BASE", "requiresConfirmation": true }
    ]
  }'
```

## Skills

Skills sind wiederverwendbare Anweisungspakete (siehe [Skills API](/de/admin/skills-api-uebersicht)), die ein Agent bei Bedarf während eines Chats lädt. Hänge sie über das `skillIds`-Array beim [Erstellen](/api-reference/agents/create-an-agent) und [Aktualisieren](/api-reference/agents/update-an-agent) an; Antworten geben die angehängten IDs im selben Feld zurück.

* Hat ein Agent angehängte Skills, werden **nur** diese Skills für ihn geladen. Ein Agent ohne angehängte Skills erhält keine.
* Skill-IDs müssen zum selben Space gehören – erstelle und finde sie über [List skills](/api-reference/skills/list-skills) und [Create a skill](/api-reference/skills/create-a-skill).

<Note>
  Beim Aktualisieren **ersetzt** das `skillIds`-Array die aktuelle Entwurfs-Skill-Menge des Agents vollständig. Sende die komplette gewünschte Menge oder `[]`, um alle Skills zu entfernen. Wird `skillIds` weggelassen, bleiben sie unverändert. Wie andere Änderungen wirken sich Skill-Bearbeitungen auf den Entwurf aus – [veröffentliche](/api-reference/agents/publish-an-agent) den Agent, damit sie für die Completion-API wirksam werden.
</Note>

```bash theme={null}
curl -X PATCH https://{customer-tenant}.nuwacom.ai/api/v1/spaces/DEINE_SPACE_ID/agents/DEINE_AGENT_ID \
  -H "Authorization: Bearer $NUWACOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skillIds": ["DEINE_SKILL_ID"]
  }'
```

## Verfügbarkeit: App und externes Embed

Wo ein Agent genutzt werden kann, steuern zwei unabhängige Schalter, beide konfigurierbar beim [Erstellen](/api-reference/agents/create-an-agent) und [Aktualisieren](/api-reference/agents/update-an-agent):

| Feld | Typ | Beschreibung |
| - | - | - |
| `appEnabled` | boolean | Ob der Agent innerhalb der nuwacom-App verfügbar ist. Standard: `true`. |
| `embedEnabled` | boolean | Ob der Agent als externes, einbettbares Chat-Widget veröffentlicht wird. Standard: `false`. |
| `embedOptions` | object | Konfiguration des externen Embed-Widgets (siehe unten). Beim Aktualisieren **ersetzt** das übergebene Objekt die bisherigen Embed-Optionen vollständig. |
| `embedId` | string | Schreibgeschützte Kennung zum Einbetten des Agents als externes Widget. Wird in Antworten zurückgegeben. |

`embedOptions` unterstützt folgende Schlüssel:

| Feld | Typ | Beschreibung |
| - | - | - |
| `domainWhitelist` | string\[] | Origins, die das Embed-Widget laden dürfen (z. B. `"https://www.example.com"`). Erforderlich, um einen Embed-Agent zu veröffentlichen. |
| `showSources` | boolean | Ob das Widget Quellenangaben anzeigt. |
| `allowFileUpload` | boolean | Ob Endnutzer im Widget Dateien hochladen dürfen. |
| `allowVoiceInput` | boolean | Ob Endnutzer im Widget Spracheingabe nutzen dürfen. |
| `themeMode` | `"light"`/`"dark"` | Standard-Farbschema des Widgets. |
| `lightTheme` | object | Farben des hellen Themes (`backgroundColor`, `primaryColor` als HSVA-Objekte). |
| `darkTheme` | object | Farben des dunklen Themes (`backgroundColor`, `primaryColor` als HSVA-Objekte). |

<Note>
  `appEnabled`, `embedEnabled` und `embedOptions` sind wie alles andere Entwurfs-Einstellungen – [veröffentliche](/api-reference/agents/publish-an-agent) den Agent, damit sie wirksam werden. Das Veröffentlichen eines Agents mit `embedEnabled: true` schaltet das externe Widget live und erfordert daher eine nicht-leere `embedOptions.domainWhitelist`; andernfalls wird die Veröffentlichung mit `400` abgelehnt.
</Note>

```bash theme={null}
curl -X POST https://{customer-tenant}.nuwacom.ai/api/v1/spaces/DEINE_SPACE_ID/agents \
  -H "Authorization: Bearer $NUWACOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website-Assistent",
    "systemInstruction": "Du hilfst Besuchern auf unserer Marketing-Website.",
    "appEnabled": false,
    "embedEnabled": true,
    "embedOptions": {
      "domainWhitelist": ["https://www.example.com"],
      "showSources": false,
      "themeMode": "light"
    }
  }'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.