# API Agentów AI

**Agent AI** to mózg Twojego bota: jego instrukcje, osobowość, język, wiedza i narzędzia. Budujesz Agenta raz, a następnie kierujesz do niego ruch. Ten przewodnik obejmuje wszystko, co możesz zrobić z Agentem za pośrednictwem API — tworzenie, konfigurowanie, nadawanie mu wiedzy i narzędzi, przeglądanie jego wersji roboczych oraz kierowanie do niego rozmów.

- **Podstawowy adres URL** — `https://api.youraiconnector.com/v1`
- **Uwierzytelnianie** — Twój klucz API (zobacz [Uwierzytelnianie](authentication.md))
- **Błędy i stronicowanie** — zobacz [Błędy i stronicowanie](errors-and-pagination.md)

Wszystkie poniższe przykłady pokazują formularz zapytania `?apiKey=` w cURL oraz nagłówek `X-API-Key` w JavaScript i Pythonie — oba działają w każdym punkcie końcowym.

Jeśli koncepcja Agentów jest dla Ciebie nowa, najpierw przeczytaj [Agenci AI](../ai-agents/ai-agents.md).


---

## Jak zbudowany jest Agent

Cztery elementy są zarządzane oddzielnie i warto wiedzieć, który jest który, zanim zaczniesz:

| Element | Czym jest | Gdzie go ustawić |
|---|---|---|
| **Konfiguracja** | Instrukcje, zasady, cel, osobowość, język, poziom AI, zachowanie podczas rezerwacji i działań następczych | `PUT /agents/{agentId}` lub węższy `PUT /agents/{agentId}/bot-config` |
| **Wiedza** | FAQ i źródła wiedzy (strony i dokumenty, które platforma przeczytała za Ciebie) | [API FAQ](faqs.md) oraz `POST /agents/{agentId}/kb-sources` |
| **Narzędzia** | Niestandardowe funkcje i serwery MCP, które Agent może wywołać w trakcie rozmowy | `POST /agents/{agentId}/custom-functions` oraz `POST /agents/{agentId}/mcp-servers` |
| **Routing** | Które kanały i rozmowy faktycznie docierają do tego Agenta | Punkty wejścia — `PUT /entry-points/channel-defaults` oraz `POST /agents/{agentId}/entry-points` |

> **Nowy Agent nikomu nie odpowiada, dopóki nie skierujesz do niego ruchu.** Utworzenie Agenta nie umieszcza go na żadnym kanale. To krok, który pomija większość integracji — zobacz [Kierowanie rozmów do Agenta](#routing-conversations-to-an-agent) na końcu tej strony.

---

## Obiekt Agent

Pełny dokument Agenta jest duży — zajmuje kilkaset kilobajtów, głównie ze względu na listę FAQ, źródła wiedzy i treść stron przeczytanych z Twojej witryny. Z tego powodu lista zwraca krótki **wiersz podsumowania** dla każdego Agenta, gdy o to poprosisz:

```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
}
```

| Pole | Typ | Opis |
|---|---|---|
| `id` | string | Unikalny identyfikator Agenta. |
| `name` | string \| null | Nazwa Agenta, widoczna w panelu nawigacyjnym. |
| `active` | boolean \| null | Czy Agent ma obecnie uprawnienia do odpowiadania. |
| `language` | string \| null | Język, w którym odpowiada Agent. |
| `goal` | string \| null | Cel pracy Agenta, skrócony do pierwszych 200 znaków (wielokropek na końcu oznacza skrócenie). |
| `tags` | array \| null | Zasady tagowania Agenta. |
| `anthropic_model` | string \| null | Poziom jakości AI: `standard`, `economy`, `max` lub `mini`. |
| `ai_speed` | string \| null | Poziom rozumowania stosowany przez Agenta przed udzieleniem odpowiedzi: `fast`, `fast_thinker`, `balanced` lub `thorough`. |
| `enable_bookings` | boolean \| null | Czy Agent może dokonywać rezerwacji spotkań. |
| `enable_follow_ups` | boolean \| null | Czy Agent wysyła wiadomości następcze. |
| `faq_refs_count` | integer | Liczba FAQ w bazie wiedzy tego Agenta. |
| `kb_source_refs_count` | integer | Liczba źródeł wiedzy powiązanych z Agentem. |
| `created_at` | integer \| null | Czas utworzenia, milisekundy epoki. |
| `last_modified_at` | integer \| null | Ostatnia zmiana, milisekundy epoki. |

Pełny dokument dodaje wszystko inne: `instructions`, `rules`, `personality`, `availability`, `follow_up_config`, listy powiązanych FAQ i źródeł wiedzy, wygenerowane bloki tekstu oraz wszelkie stany uruchomienia (`tag_generation`, `optimize_run`).

> Niektóre odpowiedzi zawierają również `substrate_campaign_id`. Jest to wewnętrzny rekord przechowywany na starszych kontach; nigdy nie musisz na nim polegać, a na nowszych kontach jest on `null` lub nieobecny.

---

## Lista Agentów

`GET /agents` — każdy Agent na koncie, najnowsze jako pierwsze.

Ten punkt końcowy **nie jest stronicowany**. Domyślnie każdy Agent jest zwracany z pełną konfiguracją, co jest obciążające: pojedynczy Agent może zajmować 580 KB, a konto z 64 Agentami ponad 3 MB. Przekaż `view=summary`, aby uzyskać krótki wiersz dla każdego Agenta, a następnie odczytaj wybrany przez siebie za pomocą [Pobierz Agenta](#get-an-agent).

**Parametry zapytania**

| Parametr | Opis |
|---|---|
| `view` | Ustaw na `summary`, aby uzyskać krótkie wiersze. Każda inna wartość zwraca `400`. Pomiń, aby uzyskać pełne dokumenty. |
| `fields` | Ma zastosowanie tylko razem z `view=summary`. Rozdzielona przecinkami lista kluczy podsumowania do zachowania, na przykład `id,name,active`. `id` jest zawsze uwzględniany; nieznane nazwy są ignorowane. |

**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"]
```

**Odpowiedź** (`200`)

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

---

## Utwórz Agenta

`POST /agents` — tylko `name` jest naprawdę wymagane; wyślij wraz z nim każdą konfigurację, którą już znasz. Nowy Agent jest domyślnie aktywny.

**Pola żądania** (wszystkie opcjonalne z wyjątkiem `name`)

| Pole | Typ | Opis |
|---|---|---|
| `name` | string | Nazwa Agenta. |
| `active` | boolean | Czy może odpowiadać od razu. Domyślnie `true`. |
| `language` | string | Język, w którym odpowiada Agent. |
| `instructions` | string | Główne instrukcje, które kierują sposobem rozmowy z kontaktami. |
| `rules` | string | Sztywne zasady, których musi zawsze przestrzegać. |
| `goal` | string | Wynik, do którego powinien dążyć. |
| `personality` | string | Ton głosu i osobowość. |
| `availability` | object | Godziny aktywności w poszczególne dni tygodnia — zobacz [Ustaw godziny aktywności](#set-active-hours). |
| `ai_speed` | string | `fast`, `fast_thinker`, `balanced` lub `thorough`. |
| `anthropic_model` | string | `standard`, `economy`, `max` lub `mini`. |
| `scrape_urls` | string[] | Strony do odczytania, na podstawie których zostaną zbudowane instrukcje Agenta. |

**Budowanie Agenta na podstawie Twojej witryny.** Dołącz `scrape_urls`, a platforma odczyta te strony i napisze instrukcje za Ciebie. Odpowiedź informuje, czy generowanie się rozpoczęło, dzięki czemu wiesz, czy odpytywać Agenta o postępy.

**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"])
```

**Odpowiedź** (`201`)

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

`agent_generation_queued` to `true`, gdy platforma rozpoczęła pisanie instrukcji na podstawie dostarczonych stron.

Kod `400` oznacza, że treść nie była obiektem JSON, pole zostało odrzucone lub Agent przekracza rozmiar konfiguracji dozwolony w Twoim planie. Kod `403` oznacza, że konto nie ma uprawnień do korzystania z jednego z wysłanych ustawień — na przykład poziomu AI, którego nie przyznał dostawca konta.

---

## Pobierz Agenta

`GET /agents/{agentId}`

Przekaż `fields` z rozdzieloną przecinkami listą, aby otrzymać tylko to, czego potrzebujesz, na przykład `fields=name,active,goal`. Pole `id` jest zawsze uwzględniane, a nazwy, które nie istnieją w Agencie, są ignorowane, a nie odrzucane. Pomiń to, aby otrzymać cały dokument.

**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"]
```

Agent, który nie istnieje na Twoim koncie, zwraca `404`.

---

## Zaktualizuj Agenta

`PUT /agents/{agentId}` — wyślij tylko te pola, które chcesz zmienić; wszystko inne pozostaje bez zmian.

Zagnieżdżone ustawienia można modyfikować pojedynczo za pomocą klucza z kropką, więc `"availability.monday"` zmienia tylko poniedziałek, pozostawiając resztę tygodnia bez zmian.

**Uwagi**

- Aby zmienić typ wydarzenia, który rezerwuje Agent, wyślij `event_id` (identyfikator wydarzenia lub `null`, aby go wyczyścić). Wyślij `event_ids` z tablicą, aby połączyć kilka jednocześnie — pierwszy stanie się głównym, a `[]` odłączy wszystko. `event_id` i `event_ids` wykluczają się wzajemnie, a pola `event` nie można zapisać bezpośrednio.
- `enable_bookings` musi być wartością logiczną, a `booking_provider` musi być jedną z `default`, `zenchef`, `formitable`.
- Pola własności i tożsamości są ignorowane, podobnie jak wewnętrzny stan uruchomienia (postęp generowania i optymalizacji).
- **Routing nie jest tutaj ustawiany.** Użyj `PUT /entry-points/channel-defaults`, aby Agent odpowiadał na kanale, `POST /agents/{agentId}/entry-points` dla reguł słów kluczowych i komentarzy oraz `PATCH /agents/{agentId}/active`, aby go wstrzymać lub wznowić.

**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"},
)
```

**Odpowiedź** (`200`)

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

Puste ciało żądania zwraca `400` z `"No fields to update"`.

---

## Aktualizacja ustawień bota

`PUT /agents/{agentId}/bot-config` — zawężony sposób zmiany tylko ustawień konwersacji.

Agent nie posiada oddzielnej sekcji bota: jego ustawienia znajdują się bezpośrednio w obiekcie Agenta, więc nazwy pól są tutaj takie same, jak te, które wysłałbyś do `PUT /agents/{agentId}`. Ten punkt końcowy istnieje jako bezpieczny, ukierunkowany sposób na zmianę kilku z nich. Wymagane jest co najmniej jedno pole.

| Pole | Opis |
|---|---|
| `instructions` | Główne instrukcje, które kierują sposobem rozmowy Agenta z kontaktami. |
| `rules` | Sztywne zasady, których musi zawsze przestrzegać. |
| `goal` | Wynik, do którego powinien dążyć w każdej konwersacji. |
| `personality` | Opis tonu głosu i osobowości. |
| `language` | Język, w którym Agent odpowiada. |
| `ai_speed` | `fast`, `fast_thinker`, `balanced` lub `thorough`. |
| `anthropic_model` | `standard`, `economy`, `max` lub `mini`. |
| `max_messages` | Maksymalna liczba wiadomości Agenta w konwersacji. |
| `alert_human_when` | Kiedy Agent powinien powiadomić członka zespołu. |
| `ai_transparency` | Czy Agent ujawnia, że jest sztuczną inteligencją. |

> **Nazwy pól muszą być tutaj prostymi nazwami** — litery, cyfry, podkreślniki i myślniki. Ścieżki z kropkami nie są akceptowane w tym punkcie końcowym (w przeciwieństwie do `PUT /agents/{agentId}`), więc `bot.goal` zostanie odrzucone z `400`.

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

Długi tekst wpływa na rozmiar konfiguracji dozwolony w Twoim planie, więc bardzo duży zestaw instrukcji może zostać odrzucony z `400`.

---

## Ustawianie godzin aktywności

`PUT /agents/{agentId}/active-hours` — godziny, w których Agent odpowiada automatycznie. Poza tymi oknami pozostaje nieaktywny.

Wyślij obiekt `availability` z kluczami odpowiadającymi dniom tygodnia (`monday` do `sunday`). Każdy dzień przyjmuje pojedyncze okno czasowe lub listę okien w formacie 24-godzinnym `HH:MM`. Dni, które pominiesz, zachowają poprzednie ustawienia, a każdy klucz, który nie jest dniem tygodnia, zostanie odrzucony — dzięki temu literówka nie spowoduje cichego braku działania.

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

**Odpowiedź** (`200`)

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

Błędny klucz dnia tygodnia zwraca `400`: `"Invalid availability keys: funday. Allowed keys: monday through sunday."`

---

## Wstrzymywanie lub wznawianie Agenta

`PATCH /agents/{agentId}/active` — włącza lub wyłącza Agenta. Wstrzymany Agent zachowuje całą swoją konfigurację, ale natychmiast przestaje odpowiadać; wznowienie działania następuje od razu.

```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 }),
});
```

**Odpowiedź** (`200`)

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

`active` musi być wartością logiczną (boolean) — każda inna wartość spowoduje zwrócenie `400` wraz z `"active (boolean) is required"`.

---

## Powielanie Agenta

`POST /agents/{agentId}/duplicate` — tworzy kopię z zachowaniem konfiguracji. Kopia nie wysyła żadnych danych, dopóki nie zostanie do niej przypisany kanał lub punkt wejścia (Entry Point).

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

**Odpowiedź** (`201`)

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

Duplikat wlicza się do limitu Agentów w Twoim planie dokładnie tak samo, jak utworzenie nowego od podstaw, dlatego operacja zostanie odrzucona z komunikatem `403`, jeśli konto osiągnęło swój limit.

---

## Usuwanie Agenta

`DELETE /agents/{agentId}`

Usunięcie zostało odrzucone, ponieważ Agent jest nadal powiązany z elementem, który przestałby działać bez niego — transmisją, punktem wejścia (Entry Point) lub (w starszych kontach) kampanią. Odpowiedź zawiera listę elementów blokujących, dzięki czemu można je najpierw odłączyć i spróbować ponownie.

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

**Odpowiedź** (`200`)

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

**Zablokowano** (`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": []
}
```

---

## Wersje robocze: przeglądaj zmiany przed ich opublikowaniem

Edycje wprowadzone w edytorze oraz wszelkie poprawki wygenerowane przez [Optymalizację z AI](#optimize-an-agent-with-ai) są przechowywane jako **nieopublikowana wersja robocza** do momentu ich opublikowania. Do tego czasu aktywny Agent nadal odpowiada zgodnie z bieżącą konfiguracją.

### Opublikuj wersję roboczą

`POST /agents/{agentId}/publish-draft` — przenosi wersję roboczą do aktywnej konfiguracji i jednocześnie usuwa wersję roboczą.

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

**Odpowiedź** (`200`)

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

`published_keys` wyświetla listę ustawień, które zostały przeniesione z wersji roboczej do aktywnego Agenta, dzięki czemu można sprawdzić, co uległo zmianie.

> **Przed wywołaniem tej funkcji sprawdź, czy istnieje wersja robocza.** Publikowanie Agenta, który nie posiada wersji roboczej, nie jest obsługiwanym wywołaniem i obecnie zwraca `500` z ogólnym komunikatem, a nie szczegółowym. Aby zamiast tego odrzucić wersję roboczą, użyj poniższej funkcji odrzucania (discard).

### Odrzuć wersję roboczą

`POST /agents/{agentId}/discard-draft` — odrzuca wersję roboczą i pozostawia bieżącą konfigurację bez zmian. Można bezpiecznie wywołać, gdy nie ma wersji roboczej; nic się nie stanie.

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

---

## Optymalizacja Agenta za pomocą AI

`POST /agents/{agentId}/optimize` — przepisuje konfigurację Agenta na podstawie Twoich opinii („nadal oferuje zniżki”, „odpowiedzi są zbyt długie”) i zapisuje poprawioną wersję **jako wersję roboczą**, zamiast od razu ją publikować.

Wyślij `user_feedback` (zwykłą instrukcję) lub, w przypadku reakcji na konkretną błędną odpowiedź, `thumbs_down_feedback` wraz z błędną `thumbs_down_message`. Przynajmniej jeden z tych dwóch elementów musi zawierać tekst.

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

**Odpowiedź** (`202`)

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

Praca wykonywana jest w tle, a wywołanie zwraca wynik natychmiast. Odczytaj Agenta za pomocą `GET /agents/{agentId}` i obserwuj `optimize_run.status`; gdy status zmieni się na `Draft`, poprawiona wersja będzie czekać jako wersja robocza Agenta. Przejrzyj ją, a następnie opublikuj lub odrzuć.

Tylko jedno zadanie na raz dla każdego Agenta — drugie wywołanie w trakcie trwania pierwszego zwróci `409`. To zużywa kredyty AI.

---

## Reguły tagowania

Reguła tagowania to tag oraz opis sytuacji, w której ma on zastosowanie. Podczas rozmowy Agent czyta ten opis i taguje kontakt, gdy sytuacja do niego pasuje; w ten sposób uruchamiane są automatyzacje oparte na tagach.

**Obiekt reguły**

| Pole | Wymagane | Opis |
|---|---|---|
| `name` | Tak | Tag do zastosowania, na przykład `hot-lead`. |
| `description` | Nie | Kiedy Agent powinien go zastosować, zapisane jako instrukcja, której ma przestrzegać. |
| `webhook` | Nie | Adres URL wywoływany, gdy Agent zastosuje ten tag. |
| `ai_can_remove` | Nie | Czy Agent może również usunąć tag. Domyślnie `false`. |
| `tag_id` | Nie | Identyfikator istniejącego tagu na Twoim koncie, z którym ma zostać powiązana reguła. Bez niego reguła łączy się z tagiem o tej samej nazwie, tworząc go, jeśli nie istnieje — dzięki temu każdą regułę można później zaadresować za pomocą identyfikatora tagu. |

### Dodaj regułę tagowania

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

**Odpowiedź** (`200`)

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

### Zastąp regułę tagowania

`PUT /agents/{agentId}/tags/{tagId}` — reguła jest wyszukiwana według identyfikatora tagu w ścieżce i **zastępowana w całości**, a nie scalana, dlatego należy przesłać pełną regułę, a nie tylko zmienianą część. Tag, na który wskazuje, jest zachowywany nawet w przypadku pominięcia `tag_id`, więc edycja nie może odłączyć reguły od jej tagu.

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

### Usuwanie reguły tagowania

`DELETE /agents/{agentId}/tags/{tagId}` — Agent przestaje stosować dany tag. Sam tag oraz wszyscy kontakty, którzy już go posiadają, pozostają nienaruszeni.

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

Oba punkty końcowe zwracają `404`, gdy Agent nie istnieje **lub** gdy nie posiada reguły dla danego tagu.

### Generowanie zestawu tagów za pomocą AI

`POST /agents/{agentId}/tags/generate` — projektuje cały zestaw reguł (nazwy tagów oraz sformułowania „zastosuj, gdy…” dla każdej z nich) poprzez odczytanie instrukcji i celu samego Agenta.

| Pole | Opis |
|---|---|
| `mode` | `merge` (wartość domyślna) zachowuje reguły już przypisane do Agenta i dodaje do nich nowe. `replace` projektuje zestaw od podstaw. |

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

**Odpowiedź** (`202`)

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

Praca wykonywana jest w tle. Przeczytaj dokumentację Agenta i obserwuj `tag_generation.status`; same reguły trafiają do `tags` Agenta. Na jednego Agenta przypada tylko jedno uruchomienie w danym momencie (w przeciwnym razie `409`) i zużywa ono kredyty AI.

---

## Źródła wiedzy

Źródła wiedzy to strony i dokumenty, które platforma przeczytała dla Ciebie. Dołączenie źródła do Agenta pozwala mu odpowiadać na podstawie tej zawartości.

**Skąd pochodzą identyfikatory źródeł.** Dodaj zawartość za pomocą punktów końcowych bazy wiedzy — `POST /kb-sources/url` dla strony, `POST /kb-sources/file` dla dokumentu, `POST /kb-sources/bulk-import` dla całej witryny. Zwracają one `source_id`, który należy odpytywać za pomocą `GET /kb-sources/{sourceId}`, aż będzie gotowy. `POST /kb-sources/url` przyjmuje również `autoLinkToAgentId`, co dołącza źródło do Agenta natychmiast po zakończeniu importu, dzięki czemu można pominąć poniższe wywołanie dołączenia.

### Dołączanie źródeł wiedzy

`POST /agents/{agentId}/kb-sources` — wyślij `kb_source_ids` z listą, aby dołączyć cały zestaw w jednym wywołaniu (co jest przydatne po zaindeksowaniu witryny), lub `kb_source_id` dla pojedynczego źródła. Wyślij jedno lub drugie. Dołączenie czegoś, co jest już dołączone, nic nie zmienia.

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

**Odpowiedź** (`200`)

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

### Odłączanie źródeł wiedzy

`DELETE /agents/{agentId}/kb-sources/{kbSourceId}` dla jednego lub `POST /agents/{agentId}/kb-sources/bulk-remove` z `kb_source_ids` dla kilku. Masowe usuwanie to `POST`, ponieważ lista identyfikatorów jest przesyłana w treści żądania.

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

Same źródła nie są usuwane i pozostają dostępne dla innych Twoich Agentów. Odłączenie czegoś, co nie jest podłączone, niczego nie zmienia.

### FAQ

FAQ są zarządzane we własnych punktach końcowych i stamtąd przypisywane do Agenta: `POST /faqs/{faqId}/link` za pomocą `{ "agent_id": "ag7HkQ2ZpLxR3mNb" }`, a `POST /faqs/{faqId}/unlink`, aby je usunąć. FAQ może być współdzielone przez dowolną liczbę Agentów. Zobacz [API FAQ](faqs.md).

> FAQ jest używane tylko przez Agentów, do których jest przypisane — samo utworzenie go nie wystarczy.

---

## Narzędzia

### Funkcje niestandardowe

`POST /agents/{agentId}/custom-functions` pozwala Agentowi wywoływać jedną z Twoich funkcji niestandardowych podczas rozmów. Można dołączać tylko funkcje należące do tego samego konta, a dołączenie funkcji, która jest już dołączona, niczego nie zmienia.

```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}` odłącza ją. Sama funkcja nie jest usuwana i pozostaje dostępna dla innych Twoich Agentów.

Zarządzaj samymi funkcjami w `/custom-functions` — zobacz [Funkcje niestandardowe](../ai-automation/custom-functions.md), aby dowiedzieć się, czym są.

### Serwery MCP

Serwer MCP to gotowy pakiet narzędzi, które Twój Agent może samodzielnie wykryć i wywołać — zobacz [Podłączanie serwerów MCP do Twojego bota](../ai-automation/mcp-servers.md). Serwery są rejestrowane raz na koncie, a następnie przypisywane do Agentów, którzy mają z nich korzystać.

> Serwery MCP wymagają funkcji **funkcji niestandardowych** w Twoim planie. Bez niej punkty końcowe `/mcp-servers` na poziomie konta zwracają `403`. Przypisywanie już zarejestrowanego serwera do Agenta nie jest ograniczone.

#### Rejestracja serwera

`POST /mcp-servers`

| Pole | Wymagane | Opis |
|---|---|---|
| `name` | Tak | Etykieta serwera. |
| `url` | Tak | Adres serwera. Musi być osiągalny przez publiczny internet. |
| `auth_type` | Nie | `header` (domyślnie) dla statycznego nagłówka autoryzacji lub `oauth2`. |
| `auth_header_name` | Nie | Nagłówek, w którym przesyłane są dane uwierzytelniające. Domyślnie `Authorization`. |
| `auth_header_value` | Nie | Same dane uwierzytelniające. Nigdy nie są zwracane w żadnej odpowiedzi. |
| `enabled` | Nie | Czy serwer jest dostępny dla Agentów. Domyślnie `true`. |
| `enabled_tools` | Nie | Lista dozwolonych nazw narzędzi. `null` oznacza, że każde narzędzie oferowane przez serwer jest włączone. |
| `tool_policies` | Nie | Limity dla poszczególnych narzędzi, kluczowane nazwą narzędzia — jak często narzędzie może być wywoływane, buforowanie wyników i nadpisanie tylko do odczytu. Przekaż `null`, aby wyczyścić je wszystkie. |

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

**Odpowiedź** (`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", "...": "..." }
}
```

Podczas zapisu platforma łączy się z serwerem i buforuje listę oferowanych przez niego narzędzi. **Serwer, którego nie można osiągnąć, nadal zostanie zapisany**, z przyczyną w `last_error` i pustą listą narzędzi — dzięki temu możesz najpierw zarejestrować serwer, a później naprawić połączenie.

`auth_type` o wartości `oauth2` zapisuje rejestrację z `oauth_connected: false` i bez narzędzi: token jeszcze nie istnieje. Autoryzacja serwera OAuth wymaga logowania przez przeglądarkę i odbywa się z poziomu pulpitu nawigacyjnego, a nie przez API.

#### Wyświetlanie, aktualizacja i usuwanie serwerów

- `GET /mcp-servers` — każdy zarejestrowany serwer, od najnowszego, w `servers`.
- `PUT /mcp-servers/{serverId}` — wyślij tylko to, co chcesz zmienić. Zmiana adresu URL lub pól autoryzacji powoduje ponowne przetestowanie połączenia i odświeżenie buforowanej listy narzędzi.
- `DELETE /mcp-servers/{serverId}` — usuwa rejestrację i odłącza ją od każdego Agenta i kampanii, w których była włączona.

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

**Sekrety nigdy nie wracają.** Odpowiedzi zawierają `auth_header_value_set` (flagę `true`/`false` informującą, że wartość jest zapisana) zamiast danych uwierzytelniających, a tokeny OAuth i sekrety klienta pozostają po stronie serwera. Wszystko inne jest zwracane: `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`.

#### Testowanie połączenia

`POST /mcp-servers/test-connection` — łączy się z serwerem i wyświetla listę jego narzędzi. Można go wywołać na dwa sposoby:

- za pomocą `server_id` — testuje **zapisaną** konfigurację i odświeża listę narzędzi w pamięci podręcznej;
- za pomocą wbudowanego `url` (oraz `auth_header_name` / `auth_header_value`) — test przed zapisem, który niczego nie przechowuje.

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

**Odpowiedź** (`200`)

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

Awaria połączenia **nie jest** błędem HTTP — otrzymujesz `200` z `success: false` oraz `error` opisującym przyczynę problemu, dzięki czemu możesz go wyświetlić obok pola edytowanego przez operatora.

#### Przypisz serwer do Agenta

Rejestracja serwera nie zapewnia do niego dostępu żadnemu Agentowi. Przypisz go:

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

**Odpowiedź** (`200`)

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

`DELETE /agents/{agentId}/mcp-servers/{mcpServerId}` odłącza go ponownie. Sam serwer nie jest usuwany i pozostaje dostępny dla innych Twoich Agentów. Przypisywanie lub odłączanie czegoś, co już znajduje się w tym stanie, niczego nie zmienia.

---

## Biblioteka mediów

Biblioteka mediów przechowuje pliki, które Agent może wysłać podczas rozmowy — menu, cennik, zdjęcie produktu. Agent może przechowywać maksymalnie **50 elementów**.

### Lista mediów

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

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

**Odpowiedź** (`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
    }
  ]
}
```

Elementy przechowywane na Agencie znajdują się na początku, a następnie starsze elementy nadal przechowywane w kampanii, na podstawie której zbudowano Agenta; `media_home` (`agent` lub `campaign`) wskazuje, który jest który. W obrębie każdej grupy najnowsze elementy znajdują się na początku.

> **`media_url` wygasa po 7 dniach.** Jest to link do pobrania utworzony w momencie przesłania pliku — traktuj stary link jako nieaktualny, a nie uszkodzony, i odczytaj listę ponownie, aby uzyskać świeży link.

### Prześlij media

`POST /agents/{agentId}/media-library` — plik jest przesyłany w treści żądania jako base64, do **10 MB**. Wywołanie kończy się po zapisaniu pliku, więc należy przewidzieć nieco więcej czasu niż w przypadku zwykłego żądania. Pamiętaj, że to ciało żądania używa nazw pól w formacie camelCase.

| Pole | Wymagane | Opis |
|---|---|---|
| `base64Data` | Tak | Zawartość pliku, zakodowana w base64, bez prefiksu data-URL. |
| `mimeType` | Tak | Typ MIME pliku. |
| `fileName` | Tak | Oryginalna nazwa pliku, używana do nazwania zapisanego pliku. |
| `title` | Nie | Krótka etykieta wyświetlana w bibliotece. |
| `description` | Nie | Instrukcja „kiedy Agent powinien to wysłać”. |
| `sendMessage` | Nie | Preferowane sformułowanie, które Agent wypowiada podczas wysyłania elementu. Przycięte do 500 znaków. |
| `maxSendsPerConversation` | Nie | Ile razy może zostać wysłany do tego samego kontaktu w jednej konwersacji. Domyślnie `1`. |
| `sendAsVoiceNote` | Nie | Tylko przesyłanie dźwięku — zapisz plik jako notatkę głosową WhatsApp. Ignorowane dla innych typów plików. |

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

Dwie rzeczy dzieją się automatycznie: animowany plik GIF jest konwertowany na wideo, aby odtwarzał się na każdym kanale, a platforma tworzy krótkie podsumowanie tego, co faktycznie znajduje się w pliku, aby Agent wiedział, kiedy pasuje.

Błąd `400` obejmuje brakujące pola, nieobsługiwany typ pliku, pusty lub zbyt duży plik oraz osiągnięcie limitu 50 elementów. Błąd `403` oznacza, że biblioteka mediów jest wyłączona dla tego konta.

### Aktualizacja elementu multimedialnego

`PATCH /agents/{agentId}/media-library/{itemId}` — tylko metadane. Samego pliku nie można zastąpić; prześlij nowy element i usuń stary. To ciało żądania używa formatu snake_case: `title`, `description`, `send_message`, `max_sends_per_conversation` (nieujemna liczba całkowita lub `null`, aby wyczyścić limit).

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

**Odpowiedź** (`200`)

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

### Usuwanie elementu multimedialnego

`DELETE /agents/{agentId}/media-library/{itemId}` — usuwa element i jego zapisany plik. Usunięcie elementu, który już nie istnieje, kończy się powodzeniem i zwraca `deleted: false`, więc wywołanie można bezpiecznie ponowić.

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

---

## Generowanie wiadomości uzupełniających

`POST /agents/{agentId}/template-generation` — pisze dla Ciebie wiadomości uzupełniające Agenta (przypomnienia, które wysyła, gdy konwersacja cichnie), w oparciu o cel, do którego służy Agent.

| Pole | Opis |
|---|---|
| `type` | `all` (domyślnie) zapisuje cały zestaw. `cold_only` zapisuje tylko wiadomości dla kontaktów, które nigdy nie odpowiedziały. |

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

Istnieją dwa sposoby powrotu tej informacji, a pole `target` informuje, który z nich wystąpił:

- **`target: "agent"` z `200`** — wiadomości zostały zapisane podczas połączenia, a wynik znajduje się w `data`. Odczytaj je z `follow_up_config` Agenta. Jest to typowy przypadek.
- **`target: "campaign"` z `202`** — praca została dodana do kolejki w kampanii o nazwie `campaign_id`. Obserwuj `template_generation_status` tej kampanii, aż do jej zakończenia.

`cold_only` wymaga wychodzącej kampanii i jest odrzucane z błędem `409` (`reason: "cold_only_requires_campaign"`) w przypadku Agenta, który jej nie posiada. `403` oznacza, że automatyczne działania następcze nie są włączone dla tego konta. Funkcja ta wykorzystuje kredyty AI, a `400` z `"Insufficient credits."` oznacza, że konto je wyczerpało.

---

## Kierowanie konwersacji do Agenta

Agent odpowiada tylko na konwersacje przesyłane przez **Punkt wejścia** (Entry Point). Dopóki kanał go nie posiada, pierwsza wiadomość od osoby, z którą nigdy nie rozmawiałeś, jest przechowywana, ale nikt jej nie odbiera i żaden asystent nie odpowiada.

| Co chcesz zrobić | Wywołanie |
|---|---|
| Uczynić Agenta osobą odpowiadającą dla całego kanału | `PUT /entry-points/channel-defaults` z `{ "channel": "instagram", "agent_id": "AGENT_ID" }` |
| Dodać węższą regułę (słowa kluczowe, komentarze, nowi obserwujący) | `POST /agents/{agentId}/entry-points` |
| Zobaczyć reguły wskazujące na jednego Agenta | `GET /agents/{agentId}/entry-points` |
| Pozostawić kanał bez osoby odpowiadającej | `DELETE /entry-points/channel-defaults?channel=instagram` |

### Wyświetlanie punktów wejścia Agenta

`GET /agents/{agentId}/entry-points` — reguły routingu, które wysyłają konwersacje do tego Agenta, od najnowszych. Zwracane są zarówno bieżące, jak i wycofane reguły; wycofana reguła posiada `enabled: false`.

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

Aby uzyskać domyślne ustawienia kanałów dla całego konta, w tym kanału celowo ustawionego na brak obsługi, odczytaj zamiast tego `GET /entry-points/channel-defaults`.

### Tworzenie punktu wejścia

`POST /agents/{agentId}/entry-points` — Agent w ścieżce zawsze wygrywa, więc reguła nigdy nie może zostać utworzona dla innego Agenta niż ten znajdujący się w adresie URL.

| `type` | Co to robi |
|---|---|
| `channel_default` | Agent odpowiada na każdy nowy kontakt na wymienionych kanałach. Preferuj `PUT /entry-points/channel-defaults` w tym celu — wycofuje to poprzedniego odbiorcę, czego utworzenie drugiego domyślnego ustawienia tutaj nie robi. |
| `keyword` | Agent przejmuje konwersację, gdy pierwsza wiadomość zawiera jedno z `match_config.keywords`. Wymagane jest co najmniej jedno słowo kluczowe. |
| `instagram_comment` / `facebook_comment` | Agent odpowiada na komentarze pod Twoimi postami. Pasujący kanał musi być wymieniony w `channels`. |
| `instagram_follower` | Agent wita nowych obserwujących. |

`channels` jest wymagane i określa, które kanały obejmuje reguła — na przykład `whatsapp`, `whatsapp_web`, `instagram`, `messenger`, `telegram`, `sms`, `email`, `chat_widget` lub `custom_channel`. Nowe reguły są włączone, chyba że określisz inaczej.

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

**Odpowiedź** (`201`)

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

**Która reguła wygrywa, gdy kilka może mieć zastosowanie:** trwająca konwersacja lub ręczne przypisanie zachowuje Agenta, którego już posiada; w przeciwnym razie reguły słów kluczowych przeważają nad regułami komentarzy, które przeważają nad regułami obserwujących, a domyślne ustawienie kanału jest ostatecznością. Informacja o tym, czy te reguły już o czymkolwiek decydują na koncie, jest raportowana przez `GET /entry-points/routing-status`.

To jest wersja skrócona. Przewodnik po [Entry Points API](entry-points.md) zawiera pełne zasady dotyczące drabinki, komentarzy i obserwujących, jednego Agenta na numer WhatsApp oraz zmiany lub usuwania reguły. Zobacz [Entry Points](../ai-agents/entry-points.md), aby poznać koncepcję, oraz [Channels API](channels.md), aby dowiedzieć się, jak połączyć sam kanał.

---

## Błędy API agentów AI

Punkty końcowe agenta zwracają standardową kopertę błędu:

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

| Status | Kiedy występuje w punkcie końcowym agenta |
|---|---|
| `400` | Brakuje wymaganego pola lub jest ono nieprawidłowe — pusta treść aktualizacji, wartość spoza dozwolonej listy (`ai_speed`, `anthropic_model`, `booking_provider`, `mode`, `type`), klucz inny niż dzień tygodnia w `availability`, nazwa pola z kropką w `bot-config` lub błędny identyfikator w ścieżce. |
| `403` | Konto nie ma uprawnień do użycia wysłanego ustawienia, osiągnięto limit agentów w planie lub funkcja wymagana przez ten punkt końcowy (biblioteka mediów, działania następcze, funkcje niestandardowe dla serwerów MCP) jest wyłączona. Zmiana przekraczająca rozmiar konfiguracji dozwolony w planie jest odrzucana z `400`. |
| `404` | Agent, reguła tagowania, element multimedialny lub serwer MCP nie zostały znalezione — albo nie istnieją, albo należą do innego konta. |
| `409` | Coś jest już w toku lub blokuje działanie: trwa optymalizacja lub generowanie tagów, agent jest nadal przypisany do transmisji, punktu wejścia lub kampanii, albo zażądano `cold_only` bez wychodzącej kampanii. |

Wspólne kody, które może zwrócić każdy punkt końcowy — `401`, `403` (Twój plan nie obejmuje dostępu do API), `429` (limit szybkości) oraz `500` — zostały wymienione wraz ze wskazówkami dotyczącymi ponawiania prób w sekcji [Błędy i stronicowanie](errors-and-pagination.md).

> **Uwaga dotycząca eksploratora.** Punkty końcowe `/agents` znajdują się w opublikowanej specyfikacji OpenAPI, więc możesz przeglądać ich dokładne pola i uruchamiać żądania na żywo w [Dokumentacji API](reference.md). Punkty końcowe `/mcp-servers` na poziomie konta również znajdują się w specyfikacji, więc tam również możesz je eksplorować.


---

## Powiązane

- [Agenci AI](../ai-agents/ai-agents.md) — czym jest agent, wyjaśnione prostym językiem.
- [Punkty wejścia](../ai-agents/entry-points.md) — w jaki sposób rozmowy są kierowane do agenta.
- [API FAQ](faqs.md) — budowanie i łączenie wiedzy, na podstawie której odpowiada agent.
- [API kanałów](channels.md) — łączenie kanałów, na których odpowiada agent.
- [Łączenie serwerów MCP z botem](../ai-automation/mcp-servers.md) · [Funkcje niestandardowe](../ai-automation/custom-functions.md)
- [Dokumentacja API](reference.md) — pełny interaktywny eksplorator punktów końcowych.