> ## 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.

## 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 }
    ]
  }'
```

## 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"
    }
  }'
```