Agents-API Übersicht

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 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
`POST`	`/api/v1/spaces/{spaceId}/agents`	Neuen Agent erstellen
`GET`	`/api/v1/spaces/{spaceId}/agents/{agentId}`	Agent-Details abrufen
`PATCH`	`/api/v1/spaces/{spaceId}/agents/{agentId}`	Agent aktualisieren
`POST`	`/api/v1/spaces/{spaceId}/agents/{agentId}/publish`	Agent veröffentlichen
`POST`	`/api/v1/spaces/{spaceId}/agents/{agentId}/unpublish`	Veröffentlichung zurückziehen
`DELETE`	`/api/v1/spaces/{spaceId}/agents/{agentId}`	Agent löschen

Methode	Endpunkt	Beschreibung
`POST`	`/api/v1/openai/chat/completions`	Mit einem Agent chatten über die Option `agentId`
`GET`	`/api/ai/models`	Verfügbare Modelle auflisten

Pagination

Agents auflisten 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.

{
  "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:

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 und übergib die ID des Agents als agentId. Die komplette Konfiguration des Agents (System-Prompt, Wissensquellen, Modell-Optionen) wird automatisch angewendet:

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

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 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. 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 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-Servers oder Actions einer verbundenen Integration (Gmail, Outlook, …). Konfiguriere sie über das actions-Array beim Erstellen und Aktualisieren. 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.

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.

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 den Agent, damit sie für die Completion-API wirksam werden.

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 und Aktualisieren:

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

appEnabled, embedEnabled und embedOptions sind wie alles andere Entwurfs-Einstellungen – veröffentliche 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.

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

Übersicht

AI

Assets

Completion API

Agents

Bevor du startest

Base URL

Verfügbare Endpunkte

Agents

Verwandte Endpunkte

Mit einem Agent chatten

Beispiel: Agent erstellen

Actions

Eingebaute nuwacom-Action-Keys

Verfügbarkeit: App und externes Embed

​Bevor du startest

​Base URL

​Verfügbare Endpunkte

​Agents

​Verwandte Endpunkte

​Pagination

​Mit einem Agent chatten

​Beispiel: Agent erstellen

​Actions

​Eingebaute nuwacom-Action-Keys

​Verfügbarkeit: App und externes Embed

Bevor du startest

Base URL

Verfügbare Endpunkte

Agents

Verwandte Endpunkte

Pagination

Mit einem Agent chatten

Beispiel: Agent erstellen

Actions

Eingebaute nuwacom-Action-Keys

Verfügbarkeit: App und externes Embed