# AI-Agent-API

Ein **AI-Agent** ist das Gehirn hinter Ihrem Bot: seine Anweisungen, Persönlichkeit, Sprache, Wissen und Tools. Sie erstellen einen Agenten einmal und leiten dann den Datenverkehr an ihn weiter. Dieser Leitfaden behandelt alles, was Sie mit einem Agenten über die API tun können — ihn erstellen, konfigurieren, mit Wissen und Tools ausstatten, Entwürfe überprüfen und Konversationen an ihn weiterleiten.

- **Basis-URL** — `https://api.youraiconnector.com/v1`
- **Authentifizierung** — Ihr API-Schlüssel (siehe [Authentifizierung](authentication.md))
- **Fehler & Paginierung** — siehe [Fehler & Paginierung](errors-and-pagination.md)

Alle nachstehenden Beispiele zeigen die `?apiKey=`-Abfrageform in cURL und den `X-API-Key`-Header in JavaScript und Python – beides funktioniert an jedem Endpunkt.

Wenn Sie neu im Konzept der Agenten sind, lesen Sie zuerst [AI-Agenten](../ai-agents/ai-agents.md).


---

## Wie ein Agent aufgebaut ist

Vier Dinge werden separat verwaltet, und es ist hilfreich zu wissen, was was ist, bevor Sie beginnen:

| Komponente | Was es ist | Wo Sie es festlegen |
|---|---|---|
| **Konfiguration** | Anweisungen, Regeln, Ziel, Persönlichkeit, Sprache, KI-Stufe, Buchungs- und Follow-up-Verhalten | `PUT /agents/{agentId}` oder das spezifischere `PUT /agents/{agentId}/bot-config` |
| **Wissen** | FAQs und Wissensquellen (Seiten und Dokumente, die die Plattform für Sie gelesen hat) | [FAQs-API](faqs.md) und `POST /agents/{agentId}/kb-sources` |
| **Tools** | Benutzerdefinierte Funktionen und MCP-Server, die der Agent mitten im Gespräch aufrufen kann | `POST /agents/{agentId}/custom-functions` und `POST /agents/{agentId}/mcp-servers` |
| **Routing** | Welche Kanäle und Konversationen diesen Agenten tatsächlich erreichen | Einstiegspunkte — `PUT /entry-points/channel-defaults` und `POST /agents/{agentId}/entry-points` |

> **Ein neuer Agent antwortet niemandem, bis Sie ihn weiterleiten.** Das Erstellen eines Agenten bringt ihn nicht auf einen Kanal. Das ist der Schritt, den die meisten Integrationen übersehen — siehe [Konversationen an einen Agenten weiterleiten](#routing-conversations-to-an-agent) am Ende dieser Seite.

---

## Das Agent-Objekt

Ein vollständiges Agent-Dokument ist groß — mehrere hundert Kilobyte, hauptsächlich seine FAQ-Liste, seine Wissensquellen und alle von Ihrer Website gelesenen Seiteninhalte. Aus diesem Grund gibt die Auflistung eine kurze **Zusammenfassungszeile** pro Agent zurück, wenn Sie danach fragen:

```json
{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}
```

| Feld | Typ | Beschreibung |
|---|---|---|
| `id` | string | Die eindeutige Kennung des Agenten. |
| `name` | string \| null | Name des Agenten, wie im Dashboard angezeigt. |
| `active` | boolean \| null | Ob der Agent derzeit antworten darf. |
| `language` | string \| null | Sprache, in der der Agent antwortet. |
| `goal` | string \| null | Worauf der Agent hinarbeitet, gekürzt auf die ersten 200 Zeichen (ein nachgestelltes Auslassungszeichen bedeutet, dass es gekürzt wurde). |
| `tags` | array \| null | Die Tagging-Regeln des Agenten. |
| `anthropic_model` | string \| null | KI-Qualitätsstufe: `standard`, `economy`, `max` oder `mini`. |
| `ai_speed` | string \| null | Wie viel Überlegung der Agent vor der Antwort anwendet: `fast`, `fast_thinker`, `balanced` oder `thorough`. |
| `enable_bookings` | boolean \| null | Ob der Agent Termine buchen darf. |
| `enable_follow_ups` | boolean \| null | Ob der Agent Follow-up-Nachrichten sendet. |
| `faq_refs_count` | integer | Wie viele FAQs sich in der Wissensdatenbank dieses Agenten befinden. |
| `kb_source_refs_count` | integer | Wie viele Wissensquellen damit verknüpft sind. |
| `created_at` | integer \| null | Erstellungszeitpunkt, Epochen-Millisekunden. |
| `last_modified_at` | integer \| null | Letzte Änderung, Epochen-Millisekunden. |

Das vollständige Dokument fügt alles andere hinzu: `instructions`, `rules`, `personality`, `availability`, `follow_up_config`, die verknüpften FAQ- und Wissensquellenlisten, die generierten Textblöcke und jeden Ausführungsstatus (`tag_generation`, `optimize_run`).

> Einige Antworten enthalten auch `substrate_campaign_id`. Es ist ein interner Datensatz, der bei älteren Konten geführt wird; Sie müssen nie darauf reagieren, und bei neueren Konten ist er `null` oder nicht vorhanden.

---

## Agenten auflisten

`GET /agents` — jeder Agent im Konto, die neuesten zuerst.

Dieser Endpunkt ist **nicht paginiert**. Standardmäßig wird jeder Agent mit seiner vollständigen Konfiguration zurückgegeben, was sehr umfangreich ist: Ein einzelner Agent kann 580 KB erreichen und ein Konto mit 64 Agenten über 3 MB. Übergeben Sie `view=summary` für eine kurze Zeile pro Agent und lesen Sie dann den gewünschten Agenten mit [Agent abrufen](#get-an-agent) aus.

**Abfrageparameter**

| Parameter | Beschreibung |
|---|---|
| `view` | Auf `summary` setzen für kurze Zeilen. Jeder andere Wert gibt `400` zurück. Weglassen für vollständige Dokumente. |
| `fields` | Gilt nur in Verbindung mit `view=summary`. Durch Kommas getrennte Zusammenfassungsschlüssel, die beibehalten werden sollen, zum Beispiel `id,name,active`. `id` ist immer enthalten; unbekannte Namen werden ignoriert. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/agents?view=summary", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agents } = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]
```

**Antwort** (`200`)

```json
{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}
```

---

## Agent erstellen

`POST /agents` — nur `name` wird tatsächlich benötigt; senden Sie jede Konfiguration, die Sie bereits kennen, zusammen damit. Ein neuer Agent ist standardmäßig aktiv.

**Anfragefelder** (alle optional außer `name`)

| Feld | Typ | Beschreibung |
|---|---|---|
| `name` | string | Name des Agenten. |
| `active` | boolean | Ob er sofort antworten darf. Standard ist `true`. |
| `language` | string | Sprache, in der der Agent antwortet. |
| `instructions` | string | Primäre Anweisungen, die steuern, wie er mit Kontakten spricht. |
| `rules` | string | Strenge Regeln, die er immer befolgen muss. |
| `goal` | string | Das Ergebnis, auf das er hinarbeiten soll. |
| `personality` | string | Tonfall und Persönlichkeit. |
| `availability` | object | Aktive Stunden pro Wochentag — siehe [Aktive Stunden festlegen](#set-active-hours). |
| `ai_speed` | string | `fast`, `fast_thinker`, `balanced` oder `thorough`. |
| `anthropic_model` | string | `standard`, `economy`, `max` oder `mini`. |
| `scrape_urls` | string[] | Seiten, die gelesen werden sollen, um die Anweisungen des Agenten zu erstellen. |

**Einen Agenten von Ihrer Website erstellen.** Fügen Sie `scrape_urls` hinzu, und die Plattform liest diese Seiten und schreibt die Anweisungen für Sie. Die Antwort teilt Ihnen mit, ob diese Generierung gestartet wurde, damit Sie wissen, ob Sie den Agenten auf Fortschritte abfragen müssen.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);
```

**Python**

```python
res = requests.post(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])
```

**Antwort** (`201`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}
```

`agent_generation_queued` ist `true`, wenn die Plattform begonnen hat, die Anweisungen von den von Ihnen bereitgestellten Seiten zu schreiben.

Ein `400` bedeutet, dass der Body kein JSON-Objekt war, ein Feld abgelehnt wurde oder der Agent die Konfigurationsgröße überschreitet, die Ihr Plan zulässt. Ein `403` bedeutet, dass das Konto eine der gesendeten Einstellungen nicht verwenden darf — zum Beispiel eine KI-Stufe, die der Kontobetreiber nicht gewährt hat.

---

## Agent abrufen

`GET /agents/{agentId}`

Übergeben Sie `fields` mit einer durch Kommas getrennten Liste, um nur das zurückzuerhalten, was Sie benötigen, zum Beispiel `fields=name,active,goal`. Die `id` ist immer enthalten, und Namen, die auf dem Agenten nicht existieren, werden ignoriert, anstatt abgelehnt zu werden. Lassen Sie es weg, um das gesamte Dokument zu erhalten.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();
```

**Python**

```python
res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]
```

Ein Agent, der in Ihrem Konto nicht existiert, gibt `404` zurück.

---

## Agent aktualisieren

`PUT /agents/{agentId}` — senden Sie nur die Felder, die Sie ändern möchten; alles andere bleibt unverändert.

Verschachtelte Einstellungen können Blatt für Blatt mit einem punktierten Schlüssel adressiert werden, sodass `"availability.monday"` nur den Montag ändert und den Rest der Woche unverändert lässt.

**Hinweise**

- Um zu ändern, für welchen buchbaren Ereignistyp der Agent Buchungen vornimmt, senden Sie `event_id` (die ID des Ereignisses oder `null`, um sie zu löschen). Senden Sie `event_ids` mit einem Array, um mehrere gleichzeitig zu verknüpfen – das erste wird zum primären, und `[]` hebt alle Verknüpfungen auf. `event_id` und `event_ids` schließen sich gegenseitig aus, und das Feld `event` selbst kann nicht direkt beschrieben werden.
- `enable_bookings` muss ein echter boolescher Wert sein, und `booking_provider` muss einer der Werte `default`, `zenchef`, `formitable` sein.
- Felder für Eigentümerschaft und Identität werden ignoriert, ebenso wie der interne Ausführungsstatus (Generierungs- und Optimierungsfortschritt).
- **Das Routing wird hier nicht festgelegt.** Verwenden Sie `PUT /entry-points/channel-defaults`, um den Agenten als Antwortenden für einen Kanal festzulegen, `POST /agents/{agentId}/entry-points` für Schlüsselwort- und Kommentarregeln und `PATCH /agents/{agentId}/active`, um ihn anzuhalten oder fortzusetzen.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'
```

**JavaScript**

```javascript
await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});
```

**Python**

```python
requests.put(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)
```

**Antwort** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

Ein leerer Body gibt `400` mit `"No fields to update"` zurück.

---

## Bot-Einstellungen aktualisieren

`PUT /agents/{agentId}/bot-config` – der gezielte Weg, um nur die Konversationseinstellungen zu ändern.

Ein Agent hat keinen separaten Bot-Bereich: Seine Einstellungen befinden sich direkt auf dem Agenten, daher sind die Feldnamen hier dieselben, die Sie an `PUT /agents/{agentId}` senden würden. Dieser Endpunkt existiert als sichere, fokussierte Methode, um eine Handvoll davon zu ändern. Mindestens ein Feld ist erforderlich.

| Feld | Beschreibung |
|---|---|
| `instructions` | Primäre Anweisungen, die steuern, wie der Agent mit Kontakten spricht. |
| `rules` | Strenge Regeln, die er immer befolgen muss. |
| `goal` | Das Ergebnis, auf das er in jeder Konversation hinarbeiten soll. |
| `personality` | Beschreibung von Tonalität und Persönlichkeit. |
| `language` | Sprache, in der der Agent antwortet. |
| `ai_speed` | `fast`, `fast_thinker`, `balanced` oder `thorough`. |
| `anthropic_model` | `standard`, `economy`, `max` oder `mini`. |
| `max_messages` | Maximale Anzahl an Agenten-Nachrichten pro Konversation. |
| `alert_human_when` | Wann der Agent einen menschlichen Teamkollegen benachrichtigen soll. |
| `ai_transparency` | Ob der Agent offenlegt, dass er eine KI ist. |

> **Feldnamen müssen hier einfache Namen sein** – Buchstaben, Zahlen, Unterstriche und Bindestriche. Punktierte Pfade werden an diesem Endpunkt nicht akzeptiert (im Gegensatz zu `PUT /agents/{agentId}`), daher wird `bot.goal` mit einem `400` abgelehnt.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'
```

Langer Text wird auf die Konfigurationsgröße angerechnet, die Ihr Plan zulässt, daher kann ein sehr großer Anweisungssatz mit einem `400` abgelehnt werden.

---

## Aktive Stunden festlegen

`PUT /agents/{agentId}/active-hours` – die Stunden, in denen der Agent automatisch antwortet. Außerhalb dieser Zeitfenster bleibt er inaktiv.

Senden Sie ein `availability`-Objekt, das nach Wochentagen (`monday` bis `sunday`) gegliedert ist. Jeder Tag akzeptiert ein einzelnes Zeitfenster oder eine Liste von Fenstern im 24-Stunden-Format `HH:MM`. Tage, die Sie auslassen, behalten ihre bisherigen Einstellungen, und jeder Schlüssel, der kein Wochentag ist, wird abgelehnt – so kann ein Tippfehler nicht unbemerkt bleiben.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'
```

**Antwort** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

Ein ungültiger Wochentags-Schlüssel gibt `400` zurück: `"Invalid availability keys: funday. Allowed keys: monday through sunday."`

---

## Einen Agenten anhalten oder fortsetzen

`PATCH /agents/{agentId}/active` — schaltet den Agenten ein oder aus. Ein pausierter Agent behält seine gesamte Konfiguration bei, antwortet aber sofort nicht mehr; das Fortsetzen wird unmittelbar wirksam.

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});
```

**Antwort** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }
```

`active` muss ein echter boolescher Wert sein – alles andere gibt `400` mit `"active (boolean) is required"` zurück.

---

## Einen Agenten duplizieren

`POST /agents/{agentId}/duplicate` — erstellt eine Kopie unter Beibehaltung der Konfiguration. Die Kopie sendet nichts, bis Sie einen Kanal oder einen Einstiegspunkt darauf verweisen.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"
```

**Antwort** (`201`)

```json
{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }
```

Ein Duplikat zählt bei Ihrem Tarif genauso auf das Agenten-Kontingent wie die Neuerstellung, daher wird es mit `403` abgelehnt, wenn das Konto sein Limit erreicht hat.

---

## Einen Agenten löschen

`DELETE /agents/{agentId}`

Das Löschen wird verweigert, solange der Agent noch mit etwas verknüpft ist, das ohne ihn nicht mehr funktionieren würde – eine Übertragung, ein Einstiegspunkt oder (bei älteren Konten) eine Kampagne. Die Antwort listet auf, was den Agenten blockiert, damit Sie diese Verknüpfungen zuerst lösen und es erneut versuchen können.

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"
```

**Antwort** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

**Blockiert** (`409`)

```json
{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}
```

---

## Entwürfe: Änderungen überprüfen, bevor sie live gehen

Änderungen, die im Editor vorgenommen wurden, sowie alle durch [Mit KI optimieren](#optimize-an-agent-with-ai) erstellten Neufassungen werden als **unveröffentlichter Entwurf** gespeichert, bis Sie sie veröffentlichen. Der Live-Agent antwortet bis dahin weiterhin mit seiner aktuellen Konfiguration.

### Den Entwurf veröffentlichen

`POST /agents/{agentId}/publish-draft` — überträgt den Entwurf auf die Live-Konfiguration und löscht den Entwurf im selben Schritt.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"
```

**Antwort** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }
```

`published_keys` listet die Einstellungen auf, die vom Entwurf auf den Live-Agenten übertragen wurden, damit Sie sehen können, was sich geändert hat.

> **Prüfen Sie vor dem Aufruf, ob ein Entwurf existiert.** Das Veröffentlichen eines Agenten ohne Entwurf ist kein unterstützter Aufruf und führt derzeit zu einem `500` mit einer allgemeinen Meldung, nicht mit einer spezifischen. Um einen Entwurf stattdessen zu verwerfen, verwenden Sie unten „Verwerfen“.

### Entwurf verwerfen

`POST /agents/{agentId}/discard-draft` – verwirft den Entwurf und belässt die Live-Konfiguration unverändert. Kann sicher aufgerufen werden, wenn kein Entwurf vorhanden ist; es passiert nichts.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"
```

---

## Einen Agenten mit KI optimieren

`POST /agents/{agentId}/optimize` – schreibt die Konfiguration des Agenten basierend auf Ihrem Feedback um („er bietet ständig Rabatte an“, „die Antworten sind zu lang“) und speichert die Überarbeitung **als Entwurf**, anstatt sie live zu schalten.

Senden Sie entweder `user_feedback` (eine einfache Anweisung) oder, wenn Sie auf eine bestimmte schlechte Antwort reagieren, `thumbs_down_feedback` zusammen mit der fehlerhaften `thumbs_down_message`. Mindestens eines der beiden muss Text enthalten.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'
```

**Antwort** (`202`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

Die Arbeit läuft im Hintergrund und der Aufruf kehrt sofort zurück. Lesen Sie den Agenten mit `GET /agents/{agentId}` und beobachten Sie `optimize_run.status`; sobald der Status wieder `Draft` ist, wartet die Überarbeitung als Entwurf des Agenten. Überprüfen Sie diese und veröffentlichen oder verwerfen Sie sie anschließend.

Nur ein Durchlauf gleichzeitig pro Agent – ein zweiter Aufruf, während einer aktiv ist, gibt `409` zurück. Dies verbraucht KI-Credits.

---

## Tagging-Regeln

Eine Tagging-Regel besteht aus einem Tag und einer Beschreibung, wann es angewendet werden soll. Während eines Gesprächs liest der Agent diese Beschreibung und versieht den Kontakt mit dem Tag, wenn es passt. So werden Tag-basierte Automatisierungen ausgelöst.

**Das Regel-Objekt**

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `name` | Ja | Das anzuwendende Tag, zum Beispiel `hot-lead`. |
| `description` | Nein | Wann der Agent es anwenden soll, geschrieben als Anweisung, der er folgt. |
| `webhook` | Nein | URL, die aufgerufen wird, wenn der Agent dieses Tag anwendet. |
| `ai_can_remove` | Nein | Ob der Agent das Tag auch wieder entfernen darf. Standardmäßig `false`. |
| `tag_id` | Nein | ID eines bestehenden Tags in Ihrem Konto, um die Regel damit zu verknüpfen. Ohne diese Angabe wird die Regel mit dem Tag gleichen Namens verknüpft und erstellt dieses, falls es noch nicht existiert – so kann jede Regel nachträglich über die Tag-ID adressiert werden. |

### Tagging-Regel hinzufügen

`POST /agents/{agentId}/tags`

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'
```

**Antwort** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }
```

### Tagging-Regel ersetzen

`PUT /agents/{agentId}/tags/{tagId}` – die Regel wird anhand der Tag-ID im Pfad gefunden und **vollständig ersetzt**, nicht zusammengeführt. Senden Sie daher die vollständige Regel und nicht nur den Teil, den Sie ändern möchten. Das Tag, auf das sie verweist, bleibt erhalten, selbst wenn Sie `tag_id` weglassen; eine Bearbeitung kann die Regel also nicht von ihrem Tag trennen.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'
```

### Eine Tagging-Regel entfernen

`DELETE /agents/{agentId}/tags/{tagId}` – der Agent wendet dieses Tag nicht mehr an. Das Tag selbst und alle Kontakte, die es bereits tragen, bleiben unverändert.

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"
```

Beide Endpunkte geben `404` zurück, wenn der Agent nicht existiert **oder** wenn er keine Regel für dieses Tag hat.

### Ein Tag-Set mit KI generieren

`POST /agents/{agentId}/tags/generate` – entwirft ein vollständiges Set an Regeln (die Tag-Namen und die Formulierung „Anwenden, wenn…“ hinter jedem), indem die eigenen Anweisungen und Ziele des Agenten gelesen werden.

| Feld | Beschreibung |
|---|---|
| `mode` | `merge` (der Standardwert) behält die bereits auf dem Agenten vorhandenen Regeln bei und ergänzt sie. `replace` entwirft das Set von Grund auf neu. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'
```

**Antwort** (`202`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }
```

Die Arbeit läuft im Hintergrund. Lesen Sie den Agenten aus und beobachten Sie `tag_generation.status`; die Regeln selbst landen im `tags` des Agenten. Es ist immer nur ein Durchlauf pro Agent möglich (`409` andernfalls), und es werden KI-Credits verbraucht.

---

## Wissensquellen

Wissensquellen sind die Seiten und Dokumente, die die Plattform für Sie gelesen hat. Wenn Sie eine solche an einen Agenten anhängen, kann dieser auf Basis dieser Inhalte antworten.

**Woher Quellen-IDs stammen.** Fügen Sie Inhalte mit den Knowledge-Base-Endpunkten hinzu – `POST /kb-sources/url` für eine Seite, `POST /kb-sources/file` für ein Dokument, `POST /kb-sources/bulk-import` für eine ganze Website. Diese geben eine `source_id` zurück, die Sie mit `GET /kb-sources/{sourceId}` abfragen, bis sie bereit ist. `POST /kb-sources/url` akzeptiert auch `autoLinkToAgentId`, wodurch die Quelle an einen Agenten angehängt wird, sobald der Import abgeschlossen ist, sodass Sie den unten stehenden „Attach“-Aufruf überspringen können.

### Wissensquellen anhängen

`POST /agents/{agentId}/kb-sources` – senden Sie `kb_source_ids` mit einer Liste, um ein ganzes Set in einem Aufruf anzuhängen (was Sie nach dem Crawlen einer Website wünschen), oder `kb_source_id` für eine einzelne Quelle. Senden Sie entweder das eine oder das andere. Das Anhängen von etwas, das bereits angehängt ist, ändert nichts.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'
```

**Antwort** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}
```

### Wissensquellen trennen

`DELETE /agents/{agentId}/kb-sources/{kbSourceId}` für einen oder `POST /agents/{agentId}/kb-sources/bulk-remove` mit `kb_source_ids` für mehrere. Das Massenlöschen ist ein `POST`, da die Liste der IDs im Body übertragen wird.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'
```

Die Quellen selbst werden nicht gelöscht und bleiben für Ihre anderen Agents verfügbar. Das Trennen einer nicht verknüpften Quelle bewirkt nichts.

### FAQs

FAQs werden über eigene Endpunkte verwaltet und von dort aus mit einem Agent verknüpft: `POST /faqs/{faqId}/link` mit `{ "agent_id": "ag7HkQ2ZpLxR3mNb" }`, und `POST /faqs/{faqId}/unlink`, um die Verknüpfung wieder aufzuheben. Ein FAQ kann von beliebig vielen Agents gemeinsam genutzt werden. Siehe die [FAQs API](faqs.md).

> Ein FAQ wird nur von den Agents verwendet, mit denen es verknüpft ist – das Erstellen allein reicht nicht aus.

---

## Tools

### Benutzerdefinierte Funktionen

`POST /agents/{agentId}/custom-functions` ermöglicht es dem Agent, während Unterhaltungen eine Ihrer benutzerdefinierten Funktionen aufzurufen. Es können nur Funktionen verknüpft werden, die zum selben Konto gehören; das Verknüpfen einer bereits verknüpften Funktion bewirkt nichts.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'
```

`DELETE /agents/{agentId}/custom-functions/{customFunctionId}` trennt die Verbindung. Die Funktion selbst wird nicht gelöscht und bleibt für Ihre anderen Agents verfügbar.

Verwalten Sie die Funktionen selbst unter `/custom-functions` – siehe [Benutzerdefinierte Funktionen](../ai-automation/custom-functions.md), um zu erfahren, worum es sich dabei handelt.

### MCP-Server

Ein MCP-Server ist ein fertiges Paket von Tools, die Ihr Agent selbst entdecken und aufrufen kann – siehe [Verbinden von MCP-Servern mit Ihrem Bot](../ai-automation/mcp-servers.md). Server werden einmalig für das Konto registriert und dann den Agents zugewiesen, die sie verwenden sollen.

> MCP-Server erfordern die Funktion **Benutzerdefinierte Funktionen** in Ihrem Plan. Ohne diese geben die `/mcp-servers`-Endpunkte auf Kontoebene `403` zurück. Das Zuweisen eines bereits registrierten Servers zu einem Agent ist nicht eingeschränkt.

#### Einen Server registrieren

`POST /mcp-servers`

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `name` | Ja | Eine Bezeichnung für den Server. |
| `url` | Ja | Die Adresse des Servers. Muss über das öffentliche Internet erreichbar sein. |
| `auth_type` | Nein | `header` (Standard) für einen statischen Authentifizierungs-Header oder `oauth2`. |
| `auth_header_name` | Nein | Header, in dem die Anmeldeinformationen gesendet werden. Standard ist `Authorization`. |
| `auth_header_value` | Nein | Die Anmeldeinformation selbst. Wird niemals in einer Antwort zurückgegeben. |
| `enabled` | Nein | Ob der Server für Agents verfügbar ist. Standard ist `true`. |
| `enabled_tools` | Nein | Positivliste der Tool-Namen. `null` bedeutet, dass jedes vom Server angebotene Tool aktiviert ist. |
| `tool_policies` | Nein | Limits pro Tool, sortiert nach Tool-Name – wie oft ein Tool ausgeführt werden darf, Ergebnis-Caching und ein Schreibschutz-Override. Übergeben Sie `null`, um alle zu löschen. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'
```

**Antwort** (`201`)

```json
{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}
```

Beim Speichern verbindet sich die Plattform mit dem Server und speichert die Liste der angebotenen Tools zwischen. **Ein Server, der nicht erreicht werden kann, wird dennoch gespeichert**, mit dem Grund in `last_error` und einer leeren Tool-Liste – so können Sie sich zuerst registrieren und die Konnektivität später beheben.

Ein `auth_type` von `oauth2` speichert die Registrierung mit `oauth_connected: false` und ohne Tools: Es gibt noch kein Token. Die Autorisierung eines OAuth-Servers erfordert eine Anmeldung über den Browser und erfolgt über das Dashboard, nicht über die API.

#### Server auflisten, aktualisieren und löschen

- `GET /mcp-servers` — jeder registrierte Server, neueste zuerst, unter `servers`.
- `PUT /mcp-servers/{serverId}` — senden Sie nur das, was Sie ändern möchten. Das Ändern der URL oder der Auth-Felder testet die Verbindung erneut und aktualisiert die zwischengespeicherte Tool-Liste.
- `DELETE /mcp-servers/{serverId}` — entfernt die Registrierung und hebt die Verknüpfung mit jedem Agenten und jeder Kampagne auf, für die er aktiviert war.

```bash
curl "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY"
```

**Geheimnisse werden nie zurückgegeben.** Antworten enthalten `auth_header_value_set` (ein `true`/`false`-Flag, das angibt, dass ein Wert gespeichert ist) anstelle der Anmeldedaten, und OAuth-Token sowie Client-Geheimnisse bleiben serverseitig. Alles andere wird zurückgegeben: `name`, `url`, `enabled`, `auth_type`, `auth_header_name`, `tools`, `enabled_tools`, `tool_policies`, `oauth_connected`, `tools_cached_at`, `last_connected_at`, `last_error`, `created_at`, `updated_at`.

#### Verbindung testen

`POST /mcp-servers/test-connection` — verbindet sich mit einem Server und listet dessen Tools auf. Zwei Möglichkeiten, dies aufzurufen:

- mit `server_id` — testet die **gespeicherte** Konfiguration und aktualisiert die zwischengespeicherte Tool-Liste;
- mit einem Inline-`url` (plus `auth_header_name` / `auth_header_value`) — ein Test vor dem Speichern, der nichts speichert.

```bash
curl -X POST "https://api.youraiconnector.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'
```

**Antwort** (`200`)

```json
{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}
```

Ein Verbindungsfehler ist **kein** HTTP-Fehler – Sie erhalten ein `200` mit `success: false` und eine `error`, die beschreibt, was schiefgelaufen ist, sodass Sie dies neben dem Feld anzeigen können, das der Benutzer gerade bearbeitet.

#### Server an einen Agenten anhängen

Die Registrierung eines Servers gibt keinem Agenten Zugriff darauf. Hängen Sie ihn an:

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'
```

**Antwort** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }
```

`DELETE /agents/{agentId}/mcp-servers/{mcpServerId}` trennt die Verbindung wieder. Der Server selbst wird nicht gelöscht und bleibt für Ihre anderen Agenten verfügbar. Das Anhängen oder Trennen von etwas, das sich bereits in diesem Zustand befindet, ändert nichts.

---

## Medienbibliothek

Die Medienbibliothek enthält die Dateien, die ein Agent während eines Gesprächs senden darf – ein Menü, eine Preisliste, ein Produktfoto. Ein Agent kann maximal **50 Elemente** enthalten.

### Medien auflisten

`GET /agents/{agentId}/media-library`

```bash
curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"
```

**Antwort** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}
```

Elemente, die auf dem Agenten gespeichert sind, kommen zuerst, gefolgt von älteren Elementen, die noch auf der Kampagne gespeichert sind, aus der der Agent erstellt wurde; `media_home` (`agent` oder `campaign`) gibt an, was was ist. Innerhalb jeder Gruppe erscheint das Neueste zuerst.

> **`media_url` läuft nach 7 Tagen ab.** Es handelt sich um den Download-Link, der beim Hochladen der Datei erstellt wurde – betrachten Sie einen alten Link eher als veraltet denn als defekt und lesen Sie die Liste erneut, um einen neuen Link zu erhalten.

### Medien hochladen

`POST /agents/{agentId}/media-library` – die Datei wird inline als base64 hochgeladen, bis zu **10 MB**. Der Aufruf kehrt zurück, sobald die Datei gespeichert ist, planen Sie also etwas mehr Zeit ein als für eine normale Anfrage. Beachten Sie, dass dieser Body camelCase-Feldnamen verwendet.

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `base64Data` | Ja | Dateiinhalt, base64-kodiert, ohne data-URL-Präfix. |
| `mimeType` | Ja | MIME-Typ der Datei. |
| `fileName` | Ja | Ursprünglicher Dateiname, der zur Benennung der gespeicherten Datei verwendet wird. |
| `title` | Nein | Kurze Bezeichnung, die in der Bibliothek angezeigt wird. |
| `description` | Nein | Die Anweisung „Wann soll der Agent dies senden“. |
| `sendMessage` | Nein | Bevorzugter Wortlaut, den der Agent verwendet, wenn er das Element sendet. Auf 500 Zeichen gekürzt. |
| `maxSendsPerConversation` | Nein | Wie oft es an denselben Kontakt in einer Konversation gesendet werden darf. Standardwert ist `1`. |
| `sendAsVoiceNote` | Nein | Nur Audio-Uploads – speichert die Datei als WhatsApp-Sprachnachricht. Wird bei anderen Dateitypen ignoriert. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'
```

Zwei Dinge geschehen automatisch: Ein animiertes GIF wird in ein Video konvertiert, damit es auf jedem Kanal abgespielt werden kann, und die Plattform schreibt eine kurze Zusammenfassung dessen, was sich tatsächlich in der Datei befindet, damit der Agent weiß, wann sie passt.

Ein `400` deckt fehlende Felder, einen nicht unterstützten Dateityp, eine leere oder zu große Datei sowie das Erreichen des Limits von 50 Elementen ab. Ein `403` bedeutet, dass die Medienbibliothek für das Konto deaktiviert ist.

### Ein Medienelement aktualisieren

`PATCH /agents/{agentId}/media-library/{itemId}` – nur Metadaten. Die Datei selbst kann nicht ersetzt werden; laden Sie ein neues Element hoch und löschen Sie das alte. Dieser Body verwendet snake_case: `title`, `description`, `send_message`, `max_sends_per_conversation` (eine nicht-negative ganze Zahl oder `null`, um das Limit aufzuheben).

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'
```

**Antwort** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}
```

### Ein Medienelement löschen

`DELETE /agents/{agentId}/media-library/{itemId}` – entfernt das Element und die zugehörige gespeicherte Datei. Das Löschen eines bereits entfernten Elements ist erfolgreich und meldet `deleted: false`, sodass der Aufruf sicher wiederholt werden kann.

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"
```

---

## Follow-up-Nachrichten generieren

`POST /agents/{agentId}/template-generation` – schreibt die Follow-up-Nachrichten des Agenten für Sie (die Stupser, die er sendet, wenn eine Konversation ruhig wird), basierend auf dem Zweck des Agenten.

| Feld | Beschreibung |
|---|---|
| `type` | `all` (Standard) schreibt den gesamten Satz. `cold_only` schreibt nur die Nachrichten für Kontakte, die nie geantwortet haben. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'
```

Es gibt zwei Möglichkeiten, wie dies zurückgegeben wird, und das Feld `target` gibt an, welche:

- **`target: "agent"` mit einem `200`** — die Nachrichten wurden während des Anrufs geschrieben und das Ergebnis befindet sich in `data`. Lesen Sie diese aus dem `follow_up_config` des Agenten aus. Dies ist der Normalfall.
- **`target: "campaign"` mit einem `202`** — die Arbeit wurde für die in `campaign_id` benannte Kampagne in die Warteschlange gestellt. Überwachen Sie den `template_generation_status` dieser Kampagne, bis sie abgeschlossen ist.

`cold_only` benötigt eine ausgehende Kampagne und wird mit `409` (`reason: "cold_only_requires_campaign"`) abgelehnt, wenn der Agent keine hat. Ein `403` bedeutet, dass automatische Nachfassaktionen für das Konto nicht aktiviert sind. Dies verbraucht KI-Credits, und ein `400` mit `"Insufficient credits."` bedeutet, dass das Konto keine mehr hat.

---

## Konversationen an einen Agenten weiterleiten

Ein Agent beantwortet nur die Konversationen, die ihm von einem **Einstiegspunkt** gesendet werden. Bis ein Kanal einen solchen hat, wird die erste Nachricht von jemandem, mit dem Sie noch nie gesprochen haben, zwar gespeichert, aber niemand nimmt sie entgegen und kein Assistent antwortet.

| Was Sie tun möchten | Aufruf |
|---|---|
| Einen Agenten zum Antwortenden für einen ganzen Kanal machen | `PUT /entry-points/channel-defaults` mit `{ "channel": "instagram", "agent_id": "AGENT_ID" }` |
| Eine engere Regel hinzufügen (Schlüsselwörter, Kommentare, neue Follower) | `POST /agents/{agentId}/entry-points` |
| Die Regeln anzeigen, die auf einen Agenten verweisen | `GET /agents/{agentId}/entry-points` |
| Einen Kanal ohne Antwortenden hinterlassen | `DELETE /entry-points/channel-defaults?channel=instagram` |

### Einstiegspunkte eines Agenten auflisten

`GET /agents/{agentId}/entry-points` — die Routing-Regeln, die Konversationen an diesen Agenten senden, beginnend mit der neuesten. Sowohl aktuelle als auch zurückgezogene Regeln werden zurückgegeben; eine zurückgezogene Regel hat `enabled: false`.

```bash
curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"
```

Für die Kanal-Standardeinstellungen des gesamten Kontos, einschließlich eines Kanals, der absichtlich auf „niemand“ gesetzt wurde, lesen Sie stattdessen `GET /entry-points/channel-defaults`.

### Einen Einstiegspunkt erstellen

`POST /agents/{agentId}/entry-points` — der Agent im Pfad gewinnt immer, daher kann niemals eine Regel für einen anderen Agenten erstellt werden als den, der in der URL angegeben ist.

| `type` | Was es bewirkt |
|---|---|
| `channel_default` | Der Agent antwortet jedem neuen Kontakt auf den aufgeführten Kanälen. Bevorzugen Sie hierfür `PUT /entry-points/channel-defaults` – dies zieht den vorherigen Antwortenden für Sie zurück, was das Erstellen eines zweiten Standards an dieser Stelle nicht tut. |
| `keyword` | Der Agent übernimmt, wenn die erste Nachricht eines der `match_config.keywords` enthält. Mindestens ein Schlüsselwort ist erforderlich. |
| `instagram_comment` / `facebook_comment` | Der Agent antwortet auf Kommentare zu Ihren Beiträgen. Der passende Kanal muss in `channels` aufgeführt sein. |
| `instagram_follower` | Der Agent begrüßt neue Follower. |

`channels` ist erforderlich und gibt an, welche Kanäle die Regel abdeckt – zum Beispiel `whatsapp`, `whatsapp_web`, `instagram`, `messenger`, `telegram`, `sms`, `email`, `chat_widget` oder `custom_channel`. Neue Regeln sind aktiviert, sofern Sie nichts anderes angeben.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'
```

**Antwort** (`201`)

```json
{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }
```

**Welche Regel gewinnt, wenn mehrere zutreffen könnten:** Eine laufende Konversation oder eine manuelle Zuweisung behält den Agenten, den sie bereits hat; ansonsten haben Schlüsselwortregeln Vorrang vor Kommentarregeln, diese vor Follower-Regeln, und ein Kanal-Standard ist das letzte Mittel. Ob diese Regeln auf einem Konto bereits etwas entscheiden, wird durch `GET /entry-points/routing-status` gemeldet.

Dies ist die Kurzfassung. Der Leitfaden zur [Entry Points API](entry-points.md) behandelt die vollständige Hierarchie, Regeln für Kommentare und Follower, einen Agenten pro WhatsApp-Nummer sowie das Ändern oder Löschen einer Regel. Siehe [Entry Points](../ai-agents/entry-points.md) für das Konzept und die [Channels API](channels.md) für die Verbindung des Kanals selbst.

---

## Fehler der AI Agents API

Agent-Endpunkte geben das Standard-Fehler-Envelope zurück:

```json
{
  "success": false,
  "error": "Agent not found"
}
```

| Status | Wann dies bei einem Agent-Endpunkt auftritt |
|---|---|
| `400` | Ein erforderliches Feld fehlt oder ist ungültig – ein leerer Update-Body, ein Wert außerhalb einer zulässigen Liste (`ai_speed`, `anthropic_model`, `booking_provider`, `mode`, `type`), ein Schlüssel, der kein Wochentag ist, in `availability`, ein punktierter Feldname in `bot-config` oder eine falsch formatierte ID im Pfad. |
| `403` | Das Konto darf eine von Ihnen gesendete Einstellung nicht verwenden, Sie haben das Agent-Limit Ihres Tarifs erreicht oder eine Funktion, die dieser Endpunkt benötigt (Mediathek, Follow-ups, benutzerdefinierte Funktionen für MCP-Server), ist deaktiviert. Eine Änderung, die die in Ihrem Tarif zulässige Konfigurationsgröße überschreitet, wird mit `400` abgelehnt. |
| `404` | Der Agent, die Tag-Regel, das Medienelement oder der MCP-Server wurde nicht gefunden – entweder existiert er nicht oder er gehört zu einem anderen Konto. |
| `409` | Etwas ist bereits in Bearbeitung oder im Weg: Eine Optimierung oder Tag-Generierung läuft, der Agent ist noch mit einem Broadcast, einem Einstiegspunkt oder einer Kampagne verknüpft, oder `cold_only` wurde ohne ausgehende Kampagne angefordert. |

Die gemeinsamen Codes, die jeder Endpunkt zurückgeben kann — `401`, `403` (Ihr Plan beinhaltet keinen API-Zugriff), `429` (Ratenbegrenzung) und `500` — sind zusammen mit Hinweisen zur Wiederholung unter [Fehler & Paginierung](errors-and-pagination.md) aufgeführt.

> **Ein Hinweis zum Explorer.** Die `/agents`-Endpunkte sind in der veröffentlichten OpenAPI-Spezifikation enthalten, sodass Sie deren genaue Felder durchsuchen und Live-Anfragen in der [API-Referenz](reference.md) ausführen können. Die `/mcp-servers`-Endpunkte auf Kontoebene sind ebenfalls in der Spezifikation enthalten, sodass Sie diese dort ebenfalls erkunden können.


---

## Verwandte Themen

- [AI Agents](../ai-agents/ai-agents.md) – was ein Agent ist, in einfacher Sprache erklärt.
- [Einstiegspunkte](../ai-agents/entry-points.md) – wie Konversationen an einen Agenten weitergeleitet werden.
- [FAQs API](faqs.md) – erstellen und verknüpfen Sie das Wissen, aus dem Ihr Agent Antworten generiert.
- [Channels API](channels.md) – verbinden Sie die Kanäle, auf denen ein Agent antwortet.
- [Verbinden von MCP-Servern mit Ihrem Bot](../ai-automation/mcp-servers.md) · [Benutzerdefinierte Funktionen](../ai-automation/custom-functions.md)
- [API-Referenz](reference.md) – der vollständige interaktive Endpunkt-Explorer.