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

# Benutzerdefinierte Aktionen

> Verbinde deine Agenten über HTTP-Integrationen mit externen Systemen

export const Screenshot = ({lightSrc, darkSrc, alt, caption, maxWidth = "880px"}) => {
  return <div style={{
    margin: "1rem auto",
    maxWidth,
    width: "100%"
  }}>
      <Frame>
        <img className="block dark:hidden" src={lightSrc} alt={alt} />
        <img className="hidden dark:block" src={darkSrc} alt={alt} />
      </Frame>
      {caption ? <p style={{
    marginTop: "0.5rem",
    fontSize: "0.875rem",
    color: "inherit",
    opacity: 0.8
  }}>
          {caption}
        </p> : null}
    </div>;
};

**In diesem Leitfaden lernst du:**

* Deinen Agenten mit beliebigen externen APIs zu verbinden
* Authentifizierung zu konfigurieren (Bearer, Basic, API Key)
* Parameter zu definieren, die der Agent vom Anrufer einsammelt
* Tool-Ausführung zu testen und zu debuggen

***

## Wie benutzerdefinierte Aktionen funktionieren

Benutzerdefinierte Aktionen lassen deine KI-Agenten während des Gesprächs mit externen Systemen integrieren. Deine Agenten können Kundendaten abrufen, CRM-Datensätze aktualisieren, Lagerbestand prüfen, Tickets erstellen und Business-Logik ausführen - alles in Echtzeit, während sie mit Kunden sprechen.

<Screenshot lightSrc="/images/operations__api-action-builder_DE-light.png" darkSrc="/images/operations__api-action-builder_DE-dark.png" alt="Custom-Action-Builder mit Endpoint-Konfiguration, HTTP-Methoden-Auswahl, URL-Feld, Auth-Tab, Parameters-Tab und Variables-Tab" />

**So funktioniert es:**

1. **API-Endpunkt konfigurieren** - HTTP-Methode, URL, Authentifizierung, Header und Request Body einrichten
2. **Variablen definieren** - Festlegen, welche Informationen der Agent vor dem API-Aufruf einsammeln muss
3. **Agent nutzt es** - Während des Gesprächs sammelt der Agent die Variablen ein und ruft deine API auf
4. **API antwortet** - Dein System gibt Daten zurück, mit denen der Agent das Gespräch fortsetzt

<Info>
  Benutzerdefinierte Aktionen laufen **synchron** während des Gesprächs. Für Operationen, die keine sofortige Antwort brauchen, etwa Logging, Insights-Auswertung oder Post-Call-Verarbeitung, nutze stattdessen [Webhooks](/de/accounts/integrations#webhooks).
</Info>

***

## Beispielablauf

```
Customer: "What's the status of my order?"

Agent: (collects order number from customer)

[Agent calls API]
-> GET https://api.company.com/orders/12345
<- { "status": "shipped", "tracking": "1Z999AA10123456789" }

Agent: "Your order has shipped! Your tracking number is
       1Z999AA10123456789 and it should arrive by Friday."
```

<Warning>
  **Security: Verify customer identity before exposing sensitive data.** Authentifiziere Kunden immer, bevor du APIs aufrufst, die persönliche Informationen, Bestelldetails oder Account-Daten zurückgeben.
</Warning>

***

## Eine benutzerdefinierte Aktion erstellen

<Steps>
  <Step title="Zu Tools navigieren">
    Gehe im Agent-Editor zu **Tools** > **Hinzufügen** > **Benutzerdefinierte Aktion**.
  </Step>

  <Step title="Basisinfos konfigurieren">
    * **Name**: Beschreibender Name, zum Beispiel "Lookup Order Status"
    * **Beschreibung**: Wann dieses Tool verwendet werden soll (10-200 Zeichen). Das hilft der KI, den Aufruf zu entscheiden.
  </Step>

  <Step title="Endpoint konfigurieren">
    Wähle die HTTP-Methode und gib die Endpoint-URL ein. Siehe Endpoint Configuration unten.
  </Step>

  <Step title="Authentifizierung einrichten">
    Wähle eine Authentifizierungsmethode. Siehe Authentication Methods unten.
  </Step>

  <Step title="Header und Body hinzufügen">
    Konfiguriere benutzerdefinierte Header, Query-Parameter und den Request Body im Parameters-Tab.
  </Step>

  <Step title="Variablen definieren">
    Füge Variablen hinzu, die der Agent aus dem Gespräch einsammeln soll. Siehe Variables unten.
  </Step>

  <Step title="Tool testen">
    Speichere und teste die Action über **Agent testen** mit einem browserbasierten Gespräch, Telefonanruf oder einer Chat-Session.
  </Step>
</Steps>

***

## Endpoint-Konfiguration

### HTTP-Methode

| Methode    | Anwendungsfall                                      |
| ---------- | --------------------------------------------------- |
| **GET**    | Daten abrufen (Order-Status, Kundeninfos)           |
| **POST**   | Datensätze erstellen (Tickets, Leads, Bestellungen) |
| **PUT**    | Ganze Datensätze ersetzen                           |
| **PATCH**  | Bestimmte Felder aktualisieren                      |
| **DELETE** | Datensätze entfernen                                |

### Endpoint-URL

Gib die volle API-URL ein. Die Plattform setzt automatisch `https://` davor, wenn du das Protokoll weglässt.

```text theme={null}
https://api.company.com/customers
```

<Note>
  Die Endpoint-URL selbst ist statisch. Verwende Query-Parameter oder den JSON-Request-Body für `{{variable_name}}`-Substitutionen.
</Note>

***

## Authentifizierungsmethoden

<AccordionGroup>
  <Accordion title="Keine" icon="lock-open">
    Keine Authentifizierung erforderlich. Für öffentliche APIs oder interne Endpunkte in privaten Netzwerken.
  </Accordion>

  <Accordion title="Bearer Token" icon="key">
    Am häufigsten für moderne APIs. Sendet den Header `Authorization: Bearer {your_token}`.

    **Use for:** OAuth-2.0-Access-Tokens, JWT-Authentifizierung, moderne REST APIs.
  </Accordion>

  <Accordion title="Basic Auth" icon="user-lock">
    Username/Passwort-Authentifizierung. Sendet den Header `Authorization: Basic {base64(username:password)}`.

    **Use for:** Legacy-APIs, einfache Authentifizierungsschemata.
  </Accordion>

  <Accordion title="Header" icon="list">
    Benutzerdefinierte Header-basierte Authentifizierung, z. B. `X-API-Key: {your_api_key}`.

    **Use for:** API-Key-Authentifizierung, benutzerdefinierte Schemata.
  </Accordion>

  <Accordion title="Body" icon="file-code">
    Credentials im Request Body gesendet, z. B. `{"api_key": "{your_key}"}`.

    **Use for:** Nicht-standardisierte Authentifizierung, Login-Endpunkte.
  </Accordion>
</AccordionGroup>

<Warning>
  Für Bearer-, Basic-Passwort-, Header-Wert- und Body-Wert-Authentifizierung wähle oder erstelle ein gespeichertes Credential aus **Secrets**. Bestehende Credentials bleiben beim Bearbeiten erhalten; wähle nur dann ein neues, wenn du sie ersetzen willst.
</Warning>

***

## Parameter-Konfiguration

<Badge>Profi</Badge>

### Headers

Füge benutzerdefinierte HTTP-Header als Key-Value-Paare hinzu. Beispiel: `Content-Type: application/json`

### Query Parameters (GET requests)

Füge URL-Query-Parameter als Key-Value-Paare hinzu. Template-Variablen werden in Query-Parameter-Werten unterstützt.

Beispiel:

```text theme={null}
order_id={{order_id}}
include=tracking
```

### Request Body (POST/PUT/PATCH)

Schreibe deinen JSON-Request-Body im Editor. Nutze `{{variable_name}}`-Syntax, um Werte aus dem Gespräch einzufügen.

```json theme={null}
{
  "customer_id": "{{customer_id}}",
  "status": "contacted",
  "timestamp": "{{current_datetime}}"
}
```

***

## Variablen - Parameter-Mapping aus dem Gesprächskontext

<Badge>Profi</Badge>

Variablen definieren, welche Informationen dein Agent vor dem API-Aufruf aus dem Gespräch einsammeln muss. Jede Variable sagt der KI, welche Information sie vor der Anfrage vom Anrufer sammeln soll.

### Variablenfelder

| Feld             | Beschreibung                                                                            |
| ---------------- | --------------------------------------------------------------------------------------- |
| **Name**         | Variablenname, zum Beispiel `order_number`, `customer_email`                            |
| **Typ**          | Datentyp: string, integer, float, boolean, date, email, phone                           |
| **Beschreibung** | Wofür diese Variable ist (hilft der KI zu verstehen, wann sie die Info einsammeln soll) |
| **Beispiel**     | Beispielwert (zeigt der KI das erwartete Format)                                        |
| **Erforderlich** | Wenn true, muss die KI diese Info vor dem API-Aufruf einsammeln                         |
| **Standardwert** | Wird genutzt, wenn die Variable nicht erforderlich ist und der Kunde sie nicht liefert  |

### Beispiel-Variable

```
Name: order_number
Typ: string
Beschreibung: Bestellnummer des Kunden, beginnt normalerweise mit ORD-
Beispiel: ORD-12345
Erforderlich: Ja
```

Die KI weiß dann, dass sie den Kunden vor der Anfrage nach der Bestellnummer fragen muss.

### Laufzeitvariablen

Benutzerdefinierte Aktions-Templates nutzen flache `{{variable_name}}`-Platzhalter in Headern, Query-Parametern und im Request Body. Diese Laufzeitwerte sind verfügbar, wenn sie existieren:

```text theme={null}
{{agent_number}}
{{agent_uuid}}
{{contact_number}}
{{direction}}
{{medium}}
{{current_datetime}}
{{timezone}}
```

Werte aus [Dynamic Context](/de/build/advanced/dynamic-context) sind ebenfalls unter ihrem Top-Level-Key verfügbar, etwa `{{account_id}}` oder `{{cal_email}}`.

<Warning>
  Geschachtelte Prompt-Variablen wie `{{contact.email}}` sind für die Prompt-Renderung gedacht, nicht für die Substitution in Custom-Action-Payloads. Wenn die Action einen Namen oder eine E-Mail des Anrufers braucht, definiere eine Variable, die der Agent einsammeln soll, oder liefere einen flachen Key über Dynamic Context.
</Warning>

***

## Tools testen

<Steps>
  <Step title="Endpoint unabhängig testen">
    Nutze Postman oder cURL, um zu prüfen, ob der Endpoint erreichbar ist, die Authentifizierung funktioniert und das Request-Format korrekt ist.
  </Step>

  <Step title="Mit statischen Werten starten">
    Konfiguriere die Action zuerst mit fest codierten Werten ohne Variablen, um die Grundfunktion zu prüfen.
  </Step>

  <Step title="Variablen hinzufügen">
    Ersetze die fest codierten Werte durch flache Template-Variablen wie `{{order_id}}`.
  </Step>

  <Step title="Im Agenten testen">
    Starte **Agent testen** und führe ein browserbasiertes Gespräch, einen Telefonanruf oder eine Chat-Session aus. Löse die Action im Gespräch aus und verifiziere:

    * Der Agent sammelt Variablen korrekt ein
    * Die API wird mit den richtigen Daten aufgerufen
    * Der Agent nutzt die Antwort passend
  </Step>

  <Step title="Fehlerszenarien testen">
    Prüfe das Verhalten des Agenten bei API-Fehlern:

    * 404 (not found)
    * 401 (authentication failed)
    * 500 (server error)
    * Timeout
  </Step>
</Steps>

***

## Fehlerbehandlung

Konfiguriere deinen Prompt so, dass API-Fehler sauber behandelt werden:

```
When using the 'Lookup Order Status' tool:

If the tool returns an error:
- 404: "I don't see an order with that number. Could you double-check?"
- 500: "I'm having trouble accessing the system right now."
- Timeout: "The system is taking longer than expected."
- For any error, offer to have someone call them back.
```

***

## Fehlerbehebung

<AccordionGroup>
  <Accordion title="401 Unauthorized" icon="lock-open">
    **Ursache:** Ungültige Credentials oder falscher Auth-Typ.

    **Lösung:** Prüfe die Credentials, vergleiche den Auth-Typ mit den Anforderungen der API, teste mit Postman und denselben Credentials und prüfe, ob das Token abgelaufen ist.
  </Accordion>

  <Accordion title="404 Not Found" icon="magnifying-glass">
    **Ursache:** Falsche URL oder Ressource existiert nicht.

    **Lösung:** Prüfe die statische Endpoint-URL, kontrolliere, ob Query-Parameter oder Body-Variablen korrekt eingesetzt werden, und teste zuerst mit statischen Werten.
  </Accordion>

  <Accordion title="Agent sammelt Variablen nicht ein" icon="robot">
    **Ursache:** Variablen nicht konfiguriert oder Beschreibungen unklar.

    **Lösung:** Prüfe, ob Variablen im Variablen-Tab definiert sind, füge klare Beschreibungen und Beispiele hinzu, setze required=true für essenzielle Variablen und referenziere das Tool im Prompt mit genauem Namen.
  </Accordion>

  <Accordion title="Variablen werden im Request nicht ersetzt" icon="brackets-curly">
    **Ursache:** Falsche Syntax oder Variable existiert nicht.

    **Lösung:** Verwende exakt `{{variable_name}}`, prüfe, ob die Variable definiert ist, und vermeide dotted Platzhalter wie `{{contact.email}}` in Custom-Action-Templates.
  </Accordion>

  <Accordion title="Timeout-Fehler" icon="clock">
    **Ursache:** API antwortet zu langsam.

    **Lösung:** Optimiere die Antwortzeit der API, verwende für langsame Operationen Webhooks und cache häufig genutzte Daten.
  </Accordion>
</AccordionGroup>

***

## Sicherheitsempfehlungen

* **Nur HTTPS verwenden** für alle API-Endpunkte
* **Credentials absichern** - niemals in URLs hardcoden, Schlüssel regelmäßig rotieren
* **Berechtigungen begrenzen** - für Lookup-Aktionen nur Read-only-Schlüssel verwenden
* **Eingaben validieren** - deine API sollte auf Injections prüfen und Datentypen validieren
* **Identität prüfen** - Kunden authentifizieren, bevor sensible Daten angezeigt werden

***

## Praxisbeispiele

<AccordionGroup>
  <Accordion title="CRM Customer Lookup" icon="user-check">
    * **Method:** GET
    * **URL:** `https://api.salesforce.com/customers`
    * **Auth:** Bearer token
    * **Variable:** `customer_id` (string, required)
    * **Query parameter:** `customer_id={{customer_id}}`
  </Accordion>

  <Accordion title="Support-Ticket erstellen" icon="ticket">
    * **Method:** POST
    * **URL:** `https://company.zendesk.com/api/v2/tickets`
    * **Auth:** Basic (email/token)
    * **Variables:** `issue_description` (string), `priority_level` (string)
    * **Body:**

    ```json theme={null}
    {
      "ticket": {
        "subject": "Call with {{caller_name}}",
        "description": "{{issue_description}}",
        "priority": "{{priority_level}}"
      }
    }
    ```
  </Accordion>

  <Accordion title="Produktbestand prüfen" icon="boxes-stacked">
    * **Method:** GET
    * **URL:** `https://inventory.company.com/products/availability`
    * **Auth:** Header (`X-API-Key`)
    * **Variable:** `sku` (string, required, example: "PROD-12345")
    * **Query parameter:** `sku={{sku}}`
  </Accordion>
</AccordionGroup>

***

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="Tools-Übersicht" icon="bolt" href="/de/build/tools/overview">
    Mehr über alle Tool-Typen erfahren
  </Card>

  <Card title="Fehlerbehebung benutzerdefinierter Aktionen" icon="wrench" href="/de/troubleshooting/custom-actions">
    Auth-, Payload-, Timeout- und Response-Probleme diagnostizieren
  </Card>

  <Card title="Buchungs-Tools" icon="calendar" href="/de/build/tools/booking-calendar">
    Cal.com-Terminplanung einrichten
  </Card>

  <Card title="Gesprächsdatenfluss" icon="arrows-turn-right" href="/de/build/conversation/runtime-data-flow">
    Verstehen, woher Variablen kommen und was nach der Tool-Ausführung passiert
  </Card>

  <Card title="Template-Syntax" icon="brackets-curly" href="/de/build/conversation/template-syntax">
    Template-Variablen meistern
  </Card>

  <Card title="MCP-Server" icon="server" href="/de/build/advanced/mcp-servers">
    MCP-Server für fortgeschrittene Integrationen verbinden
  </Card>
</CardGroup>