# API pentru Agenți AI

Un **Agent AI** este creierul din spatele botului tău: instrucțiunile, personalitatea, limba, cunoștințele și instrumentele sale. Construiești un Agent o singură dată și apoi direcționezi traficul către acesta. Acest ghid acoperă tot ce poți face cu un Agent prin intermediul API-ului — să-l creezi, să-l configurezi, să-i oferi cunoștințe și instrumente, să-i revizuiești ciornele și să direcționezi conversațiile către el.

- **URL de bază** — `https://api.youraiconnector.com/v1`
- **Autentificare** — cheia ta API (vezi [Autentificare](authentication.md))
- **Erori și paginare** — vezi [Erori și paginare](errors-and-pagination.md)

Toate exemplele de mai jos arată forma de interogare `?apiKey=` în cURL și antetul `X-API-Key` în JavaScript și Python — oricare dintre ele funcționează pe fiecare endpoint.

Dacă ești nou în conceptul de Agenți, citește mai întâi [Agenți AI](../ai-agents/ai-agents.md).


---

## Cum este structurat un Agent

Patru elemente sunt gestionate separat și este util să știi care este care înainte de a începe:

| Element | Ce reprezintă | Unde îl configurezi |
|---|---|---|
| **Configurare** | Instrucțiuni, reguli, obiectiv, personalitate, limbă, nivel AI, comportament de programare și follow-up | `PUT /agents/{agentId}` sau `PUT /agents/{agentId}/bot-config` mai specific |
| **Cunoștințe** | Întrebări frecvente și surse de cunoștințe (pagini și documente pe care platforma le-a citit pentru tine) | [API pentru Întrebări frecvente](faqs.md) și `POST /agents/{agentId}/kb-sources` |
| **Instrumente** | Funcții personalizate și servere MCP pe care Agentul le poate apela în timpul conversației | `POST /agents/{agentId}/custom-functions` și `POST /agents/{agentId}/mcp-servers` |
| **Rutare** | Ce canale și conversații ajung efectiv la acest Agent | Puncte de intrare — `PUT /entry-points/channel-defaults` și `POST /agents/{agentId}/entry-points` |

> **Un Agent nou nu răspunde nimănui până când nu direcționezi traficul către el.** Crearea unui Agent nu îl plasează pe un canal. Acesta este pasul pe care majoritatea integrărilor îl omit — vezi [Direcționarea conversațiilor către un Agent](#routing-conversations-to-an-agent) la sfârșitul acestei pagini.

---

## Obiectul Agent

Un document complet al unui Agent este mare — câteva sute de kiloocteți, în principal lista sa de întrebări frecvente, sursele sale de cunoștințe și orice conținut de pagină citit de pe site-ul tău. Din acest motiv, listarea returnează un **rând rezumat** scurt pentru fiecare Agent atunci când îl soliciți:

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

| Câmp | Tip | Descriere |
|---|---|---|
| `id` | string | Identificatorul unic al Agentului. |
| `name` | string \| null | Numele Agentului, așa cum apare în tabloul de bord. |
| `active` | boolean \| null | Dacă Agentului îi este permis în prezent să răspundă. |
| `language` | string \| null | Limba în care răspunde Agentul. |
| `goal` | string \| null | Obiectivul Agentului, scurtat la primele 200 de caractere (o elipsă la final înseamnă că a fost scurtat). |
| `tags` | array \| null | Regulile de etichetare ale Agentului. |
| `anthropic_model` | string \| null | Nivelul de calitate AI: `standard`, `economy`, `max` sau `mini`. |
| `ai_speed` | string \| null | Cât de mult raționează Agentul înainte de a răspunde: `fast`, `fast_thinker`, `balanced` sau `thorough`. |
| `enable_bookings` | boolean \| null | Dacă Agentul poate programa întâlniri. |
| `enable_follow_ups` | boolean \| null | Dacă Agentul trimite mesaje de follow-up. |
| `faq_refs_count` | integer | Câte întrebări frecvente sunt în baza de cunoștințe a acestui Agent. |
| `kb_source_refs_count` | integer | Câte surse de cunoștințe sunt legate de acesta. |
| `created_at` | integer \| null | Timpul creării, milisecunde epocă. |
| `last_modified_at` | integer \| null | Ultima modificare, milisecunde epocă. |

Documentul complet adaugă tot restul: `instructions`, `rules`, `personality`, `availability`, `follow_up_config`, listele legate de întrebări frecvente și surse de cunoștințe, blocurile de text generate și orice stare de execuție (`tag_generation`, `optimize_run`).

> Unele răspunsuri conțin și `substrate_campaign_id`. Este o înregistrare internă păstrată în conturile mai vechi; nu trebuie să acționezi niciodată asupra ei, iar în conturile mai noi este `null` sau lipsește.

---

## Listarea Agenților

`GET /agents` — fiecare Agent din cont, cele mai noi primele.

Acest endpoint **nu este paginat**. În mod implicit, fiecare Agent este returnat cu configurația sa completă, care este voluminoasă: un singur Agent poate ajunge la 580 KB, iar un cont cu 64 de Agenți la peste 3 MB. Transmite `view=summary` pentru a obține un rând scurt per Agent, apoi citește-l pe cel dorit folosind [Obține un Agent](#get-an-agent).

**Parametri de interogare**

| Parametru | Descriere |
|---|---|
| `view` | Setează la `summary` pentru rânduri scurte. Orice altă valoare returnează `400`. Omite pentru documente complete. |
| `fields` | Se aplică doar împreună cu `view=summary`. Chei de rezumat separate prin virgulă de păstrat, de exemplu `id,name,active`. `id` este întotdeauna inclus; numele necunoscute sunt ignorate. |

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

**Răspuns** (`200`)

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

---

## Creează un Agent

`POST /agents` — doar `name` este cu adevărat necesar; trimite orice configurație pe care o cunoști deja împreună cu acesta. Un Agent nou este activ în mod implicit.

**Câmpuri de solicitare** (toate opționale, cu excepția `name`)

| Câmp | Tip | Descriere |
|---|---|---|
| `name` | string | Numele Agentului. |
| `active` | boolean | Dacă poate răspunde imediat. Implicit este `true`. |
| `language` | string | Limba în care răspunde Agentul. |
| `instructions` | string | Instrucțiuni principale care ghidează modul în care comunică cu contactele. |
| `rules` | string | Reguli stricte pe care trebuie să le respecte întotdeauna. |
| `goal` | string | Rezultatul către care ar trebui să tindă. |
| `personality` | string | Tonul vocii și personalitatea. |
| `availability` | object | Orele de activitate pe zi a săptămânii — vezi [Setează orele de activitate](#set-active-hours). |
| `ai_speed` | string | `fast`, `fast_thinker`, `balanced` sau `thorough`. |
| `anthropic_model` | string | `standard`, `economy`, `max` sau `mini`. |
| `scrape_urls` | string[] | Pagini de citit din care să se construiască instrucțiunile Agentului. |

**Construirea unui Agent de pe site-ul tău.** Include `scrape_urls`, iar platforma citește acele pagini și scrie instrucțiunile pentru tine. Răspunsul îți indică dacă acea generare a început, astfel încât să știi dacă trebuie să interoghezi Agentul pentru progres.

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

**Răspuns** (`201`)

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

`agent_generation_queued` este `true` atunci când platforma a început să scrie instrucțiunile din paginile pe care le-ați furnizat.

O `400` înseamnă că corpul cererii nu a fost un obiect JSON, un câmp a fost respins sau Agentul depășește dimensiunea de configurare permisă de planul dumneavoastră. O `403` înseamnă că contului nu îi este permis să utilizeze una dintre setările pe care le-ați trimis — de exemplu, un nivel AI pe care furnizorul contului său nu l-a acordat.

---

## Obțineți un Agent

`GET /agents/{agentId}`

Transmiteți `fields` cu o listă separată prin virgulă pentru a primi înapoi doar ceea ce aveți nevoie, de exemplu `fields=name,active,goal`. `id` este întotdeauna inclus, iar numele care nu există în Agent sunt ignorate în loc să fie respinse. Omiteți-l pentru a obține întregul document.

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

Un Agent care nu există în contul dumneavoastră returnează `404`.

---

## Actualizați un Agent

`PUT /agents/{agentId}` — trimiteți doar câmpurile pe care doriți să le modificați; tot restul rămâne neatins.

Setările imbricate pot fi adresate frunză cu frunză folosind o cheie punctată, astfel încât `"availability.monday"` modifică doar ziua de luni și lasă restul săptămânii intact.

**Note**

- Pentru a schimba tipul de eveniment rezervabil în care Agentul face rezervări, trimiteți `event_id` (id-ul evenimentului sau `null` pentru a-l șterge). Trimiteți `event_ids` cu o matrice pentru a conecta mai multe simultan — primul devine cel principal, iar `[]` deconectează totul. `event_id` și `event_ids` se exclud reciproc, iar câmpul `event` în sine nu poate fi scris direct.
- `enable_bookings` trebuie să fie un boolean real, iar `booking_provider` trebuie să fie unul dintre `default`, `zenchef`, `formitable`.
- Câmpurile de proprietate și identitate sunt ignorate, la fel ca starea internă de execuție (progresul generării și optimizării).
- **Rutarea nu este setată aici.** Utilizați `PUT /entry-points/channel-defaults` pentru a face Agentul să răspundă pe un canal, `POST /agents/{agentId}/entry-points` pentru regulile de cuvinte cheie și comentarii și `PATCH /agents/{agentId}/active` pentru a-l întrerupe sau relua.

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

**Răspuns** (`200`)

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

Un corp gol returnează `400` cu `"No fields to update"`.

---

## Actualizarea setărilor botului

`PUT /agents/{agentId}/bot-config` — modalitatea restrânsă de a modifica doar setările conversaționale.

Un Agent nu are o secțiune separată pentru boți: setările sale se află direct pe Agent, deci numele câmpurilor de aici sunt aceleași pe care le-ați trimite către `PUT /agents/{agentId}`. Acest endpoint există ca o modalitate sigură și concentrată de a modifica câteva dintre ele. Este necesar cel puțin un câmp.

| Câmp | Descriere |
|---|---|
| `instructions` | Instrucțiuni principale care ghidează modul în care Agentul vorbește cu contactele. |
| `rules` | Reguli stricte pe care trebuie să le respecte întotdeauna. |
| `goal` | Rezultatul către care ar trebui să tindă în fiecare conversație. |
| `personality` | Descrierea tonului vocii și a personalității. |
| `language` | Limba în care răspunde Agentul. |
| `ai_speed` | `fast`, `fast_thinker`, `balanced` sau `thorough`. |
| `anthropic_model` | `standard`, `economy`, `max` sau `mini`. |
| `max_messages` | Numărul maxim de mesaje ale Agentului per conversație. |
| `alert_human_when` | Când ar trebui Agentul să alerteze un coleg uman. |
| `ai_transparency` | Dacă Agentul dezvăluie că este un AI. |

> **Numele câmpurilor trebuie să fie nume simple aici** — litere, cifre, caractere de subliniere și cratime. Căile punctate nu sunt acceptate pe acest endpoint (spre deosebire de `PUT /agents/{agentId}`), deci `bot.goal` este respins cu un `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" }'
```

Textul lung contează în limita dimensiunii de configurare permisă de planul dvs., deci un set de instrucțiuni foarte mare poate fi refuzat cu un `400`.

---

## Setarea orelor de activitate

`PUT /agents/{agentId}/active-hours` — orele în care Agentul răspunde automat. În afara acelor ferestre, acesta rămâne inactiv.

Trimiteți un obiect `availability` cu chei reprezentând ziua săptămânii (`monday` până la `sunday`). Fiecare zi acceptă o singură fereastră de timp sau o listă de ferestre, în format `HH:MM` de 24 de ore. Zilele pe care le omiteți își păstrează setările anterioare, iar orice cheie care nu reprezintă o zi a săptămânii este respinsă — astfel, o greșeală de scriere nu poate trece neobservată.

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

**Răspuns** (`200`)

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

O cheie de zi a săptămânii incorectă returnează `400`: `"Invalid availability keys: funday. Allowed keys: monday through sunday."`

---

## Întreruperea sau reluarea unui Agent

`PATCH /agents/{agentId}/active` — pornește sau oprește Agentul. Un Agent întrerupt își păstrează toată configurația, dar încetează imediat să mai răspundă; reluarea activității are efect imediat.

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

**Răspuns** (`200`)

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

`active` trebuie să fie o valoare booleană reală — orice altceva returnează `400` cu `"active (boolean) is required"`.

---

## Duplicarea unui Agent

`POST /agents/{agentId}/duplicate` — creează o copie cu configurația păstrată. Copia nu trimite nimic până când nu direcționați un canal sau un Punct de Intrare către aceasta.

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

**Răspuns** (`201`)

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

Un duplicat este luat în calculul limitei de Agenți a planului dumneavoastră exact ca și cum ați crea unul de la zero, deci este refuzat cu `403` atunci când contul a atins limita.

---

## Ștergerea unui Agent

`DELETE /agents/{agentId}`

Ștergerea este refuzată cât timp Agentul este încă atașat de ceva care nu ar mai funcționa fără el — o difuzare, un Punct de Intrare sau (în cazul conturilor mai vechi) o campanie. Răspunsul listează elementele care îl rețin, astfel încât să le puteți detașa mai întâi și să reîncercați.

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

**Răspuns** (`200`)

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

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

---

## Ciorne: revizuiți modificările înainte ca acestea să devină active

Editările efectuate în editor și orice rescriere produsă prin [Optimizează cu AI](#optimize-an-agent-with-ai) sunt păstrate ca o **ciornă nepublicată** până când le publicați. Agentul activ continuă să răspundă cu configurația sa actuală până în acel moment.

### Publicarea ciornei

`POST /agents/{agentId}/publish-draft` — mută ciorna în configurația activă și șterge ciorna în același pas.

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

**Răspuns** (`200`)

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

`published_keys` listează setările care au fost mutate din ciornă în Agentul activ, astfel încât să puteți vedea ce s-a schimbat.

> **Verificați dacă există o ciornă înainte de a apela această funcție.** Publicarea unui Agent care nu are nicio ciornă nu este un apel suportat și în prezent returnează un `500` cu un mesaj generic, nu unul specific. Pentru a renunța la o ciornă, utilizați eliminarea de mai jos.

### Renunță la ciornă

`POST /agents/{agentId}/discard-draft` — elimină ciorna și lasă configurația activă exact așa cum este. Este sigur de apelat atunci când nu există nicio ciornă; nu se întâmplă nimic.

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

---

## Optimizarea unui Agent cu AI

`POST /agents/{agentId}/optimize` — rescrie configurația Agentului pe baza feedback-ului tău („continuă să ofere reduceri”, „răspunsurile sunt prea lungi”) și salvează rescrierea **ca ciornă** în loc să o facă activă.

Trimite fie `user_feedback` (o instrucțiune simplă), fie, atunci când reacționezi la un răspuns necorespunzător specific, `thumbs_down_feedback` împreună cu `thumbs_down_message` problematic. Cel puțin unul dintre cele două trebuie să conțină text.

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

**Răspuns** (`202`)

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

Procesul rulează în fundal, iar apelul returnează imediat un rezultat. Citește Agentul cu `GET /agents/{agentId}` și urmărește `optimize_run.status`; odată ce revine la `Draft`, rescrierea va fi disponibilă ca ciornă a Agentului. Revizuiește-o, apoi public-o sau renunță la ea.

Doar o singură execuție simultan per Agent — un al doilea apel în timp ce unul este în desfășurare va returna `409`. Această acțiune consumă credite AI.

---

## Reguli de etichetare

O regulă de etichetare reprezintă o etichetă plus o descriere a momentului în care se aplică. În timpul unei conversații, Agentul citește acea descriere și etichetează contactul atunci când se potrivește, acesta fiind modul în care sunt declanșate automatizările bazate pe etichete.

**Obiectul regulă**

| Câmp | Obligatoriu | Descriere |
|---|---|---|
| `name` | Da | Eticheta de aplicat, de exemplu `hot-lead`. |
| `description` | Nu | Când ar trebui Agentul să o aplice, scrisă sub formă de instrucțiune pe care acesta o urmează. |
| `webhook` | Nu | URL apelat atunci când Agentul aplică această etichetă. |
| `ai_can_remove` | Nu | Dacă Agentul poate, de asemenea, să elimine eticheta. Valoarea implicită este `false`. |
| `tag_id` | Nu | ID-ul unei etichete existente în contul tău pentru a asocia regula cu aceasta. Fără acesta, regula se asociază cu eticheta cu același nume, creând-o dacă nu există — astfel încât fiecare regulă să poată fi adresată ulterior prin ID-ul etichetei. |

### Adăugarea unei reguli de etichetare

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

**Răspuns** (`200`)

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

### Înlocuirea unei reguli de etichetare

`PUT /agents/{agentId}/tags/{tagId}` — regula este găsită după id-ul etichetei din cale și **înlocuită complet**, nu îmbinată, așa că trimiteți regula întreagă în loc de doar partea pe care o modificați. Eticheta către care indică este păstrată chiar dacă omiteți `tag_id`, deci o editare nu poate detașa regula de eticheta sa.

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

### Eliminarea unei reguli de etichetare

`DELETE /agents/{agentId}/tags/{tagId}` — Agentul încetează să mai aplice acea etichetă. Eticheta în sine și orice contacte care o poartă deja rămân intacte.

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

Ambele puncte finale returnează `404` atunci când Agentul nu există **sau** când nu are nicio regulă pentru acea etichetă.

### Generarea unui set de etichete cu AI

`POST /agents/{agentId}/tags/generate` — concepe un set întreg de reguli (numele etichetelor și formularea „aplică atunci când…” din spatele fiecăreia) prin citirea instrucțiunilor și a obiectivului propriu al Agentului.

| Câmp | Descriere |
|---|---|
| `mode` | `merge` (implicit) păstrează regulile deja existente pe Agent și le adaugă pe cele noi. `replace` concepe setul de la zero. |

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

**Răspuns** (`202`)

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

Procesul rulează în fundal. Citiți Agentul și urmăriți `tag_generation.status`; regulile propriu-zise ajung în `tags` al Agentului. Doar o singură execuție simultan per Agent (`409` în caz contrar), și utilizează credite AI.

---

## Surse de cunoștințe

Sursele de cunoștințe sunt paginile și documentele pe care platforma le-a citit pentru dumneavoastră. Atașarea uneia la un Agent îi permite acestuia să răspundă pe baza acelui conținut.

**De unde provin id-urile surselor.** Adăugați conținut cu punctele finale ale bazei de cunoștințe — `POST /kb-sources/url` pentru o pagină, `POST /kb-sources/file` pentru un document, `POST /kb-sources/bulk-import` pentru un întreg site. Acestea returnează un `source_id` pe care îl interogați cu `GET /kb-sources/{sourceId}` până când este gata. `POST /kb-sources/url` acceptă de asemenea `autoLinkToAgentId`, care atașează sursa la un Agent imediat ce importul se finalizează, astfel încât să puteți omite apelul de atașare de mai jos.

### Atașarea surselor de cunoștințe

`POST /agents/{agentId}/kb-sources` — trimiteți `kb_source_ids` cu o listă pentru a atașa un set întreg într-un singur apel (ceea ce doriți după indexarea unui site), sau `kb_source_id` pentru una singură. Trimiteți una sau alta. Atașarea a ceva deja atașat nu schimbă nimic.

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

**Răspuns** (`200`)

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

### Detașarea surselor de cunoștințe

`DELETE /agents/{agentId}/kb-sources/{kbSourceId}` pentru unul, sau `POST /agents/{agentId}/kb-sources/bulk-remove` cu `kb_source_ids` pentru mai multe. Eliminarea în masă este un `POST` deoarece lista de ID-uri este transmisă în corp.

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

Sursele în sine nu sunt șterse și rămân disponibile pentru ceilalți Agenți ai tăi. Detașarea a ceva ce nu este atașat nu schimbă nimic.

### Întrebări frecvente (FAQ)

Întrebările frecvente sunt gestionate prin propriile lor endpoint-uri și legate de un Agent de acolo: `POST /faqs/{faqId}/link` cu `{ "agent_id": "ag7HkQ2ZpLxR3mNb" }`, și `POST /faqs/{faqId}/unlink` pentru a o elimina din nou. O întrebare frecventă poate fi partajată de orice număr de Agenți. Consultă [API-ul pentru FAQ](faqs.md).

> O întrebare frecventă este utilizată doar de Agenții de care este legată — crearea uneia nu este suficientă de la sine.

---

## Instrumente

### Funcții personalizate

`POST /agents/{agentId}/custom-functions` permite Agentului să apeleze una dintre funcțiile tale personalizate în timpul conversațiilor. Doar funcțiile care aparțin aceluiași cont pot fi atașate, iar atașarea uneia care este deja atașată nu schimbă nimic.

```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}` o detașează. Funcția în sine nu este ștearsă și rămâne disponibilă pentru ceilalți Agenți ai tăi.

Gestionează funcțiile în sine pe `/custom-functions` — consultă [Funcții personalizate](../ai-automation/custom-functions.md) pentru a vedea ce sunt acestea.

### Servere MCP

Un server MCP este un pachet gata de utilizare de instrumente pe care Agentul tău le poate descoperi și apela singur — consultă [Conectarea serverelor MCP la botul tău](../ai-automation/mcp-servers.md). Serverele sunt înregistrate o singură dată în cont, apoi atașate oricăror Agenți care ar trebui să le utilizeze.

> Serverele MCP necesită funcționalitatea de **funcții personalizate** în planul tău. Fără aceasta, endpoint-urile `/mcp-servers` la nivel de cont returnează `403`. Atașarea unui server deja înregistrat la un Agent nu este restricționată.

#### Înregistrarea unui server

`POST /mcp-servers`

| Câmp | Obligatoriu | Descriere |
|---|---|---|
| `name` | Da | O etichetă pentru server. |
| `url` | Da | Adresa serverului. Trebuie să fie accesibilă prin internetul public. |
| `auth_type` | Nu | `header` (implicit) pentru un antet de autentificare static, sau `oauth2`. |
| `auth_header_name` | Nu | Antetul în care se trimite acreditarea. Implicit este `Authorization`. |
| `auth_header_value` | Nu | Acreditarea propriu-zisă. Nu este returnată niciodată în niciun răspuns. |
| `enabled` | Nu | Dacă serverul este disponibil pentru Agenți. Implicit este `true`. |
| `enabled_tools` | Nu | Listă permisă de nume de instrumente. `null` înseamnă că fiecare instrument oferit de server este activat. |
| `tool_policies` | Nu | Limite per instrument, identificate prin numele instrumentului — cât de des poate fi declanșat un instrument, stocarea în cache a rezultatelor și o suprascriere de tip read-only. Trimiteți `null` pentru a le șterge pe toate. |

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

**Răspuns** (`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", "...": "..." }
}
```

La salvare, platforma se conectează la server și stochează în cache lista de instrumente pe care acesta le oferă. **Un server care nu poate fi accesat este totuși salvat**, cu motivul în `last_error` și o listă de instrumente goală — astfel încât să puteți înregistra mai întâi și să remediați conectivitatea ulterior.

Un `auth_type` de tip `oauth2` salvează înregistrarea cu `oauth_connected: false` și fără instrumente: nu există încă niciun token. Autorizarea unui server OAuth necesită o autentificare prin browser și se face din tabloul de bord, nu prin API.

#### Listarea, actualizarea și ștergerea serverelor

- `GET /mcp-servers` — fiecare server înregistrat, cele mai noi primele, sub `servers`.
- `PUT /mcp-servers/{serverId}` — trimiteți doar ceea ce doriți să modificați. Modificarea URL-ului sau a câmpurilor de autentificare retestează conexiunea și reîmprospătează lista de instrumente stocată în cache.
- `DELETE /mcp-servers/{serverId}` — elimină înregistrarea și o deconectează de la fiecare Agent și campanie care o avea activată.

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

**Secretele nu se întorc niciodată.** Răspunsurile conțin `auth_header_value_set` (un flag `true`/`false` care indică faptul că o valoare este stocată) în loc de acreditare, iar tokenurile OAuth și secretele clientului rămân pe partea de server. Tot restul este returnat: `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`.

#### Testarea unei conexiuni

`POST /mcp-servers/test-connection` — se conectează la un server și listează instrumentele acestuia. Două moduri de a-l apela:

- cu `server_id` — testează configurația **salvată** și reîmprospătează lista de instrumente stocată în cache;
- cu un `url` inline (plus `auth_header_name` / `auth_header_value`) — un test înainte de salvare care nu stochează nimic.

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

**Răspuns** (`200`)

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

O eroare de conexiune **nu** este o eroare HTTP — primiți un `200` cu `success: false` și un `error` care descrie ce a mers prost, astfel încât să îl puteți afișa lângă câmpul pe care îl editează operatorul.

#### Atașarea unui server la un Agent

Înregistrarea unui server nu oferă niciunui Agent acces la acesta. Atașați-l:

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

**Răspuns** (`200`)

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

`DELETE /agents/{agentId}/mcp-servers/{mcpServerId}` îl detașează din nou. Serverul în sine nu este șters și rămâne disponibil pentru ceilalți Agenți ai dumneavoastră. Atașarea sau detașarea a ceva ce se află deja în acea stare nu schimbă nimic.

---

## Biblioteca media

Biblioteca media conține fișierele pe care un Agent le poate trimite în timpul unei conversații — un meniu, o listă de prețuri, o fotografie de produs. Un Agent poate deține cel mult **50 de elemente**.

### Listare conținut media

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

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

**Răspuns** (`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
    }
  ]
}
```

Elementele stocate pe Agent apar primele, urmate de orice elemente mai vechi încă stocate în campania din care a fost creat Agentul; `media_home` (`agent` sau `campaign`) indică care este care. În cadrul fiecărui grup, cele mai noi apar primele.

> **`media_url` expiră după 7 zile.** Acesta este linkul de descărcare creat în momentul încărcării fișierului — tratați un link vechi ca fiind expirat, nu defect, și recitiți lista pentru a obține un link nou.

### Încărcare conținut media

`POST /agents/{agentId}/media-library` — fișierul este încărcat inline ca base64, până la **10 MB**. Apelul returnează un răspuns odată ce fișierul este stocat, așa că acordați puțin mai mult timp decât pentru o cerere obișnuită. Rețineți că acest corp folosește nume de câmpuri în format camelCase.

| Câmp | Obligatoriu | Descriere |
|---|---|---|
| `base64Data` | Da | Conținutul fișierului, codificat base64, fără prefix data-URL. |
| `mimeType` | Da | Tipul MIME al fișierului. |
| `fileName` | Da | Numele original al fișierului, folosit pentru a denumi fișierul stocat. |
| `title` | Nu | Etichetă scurtă afișată în bibliotecă. |
| `description` | Nu | Instrucțiunea „când ar trebui Agentul să trimită acest lucru”. |
| `sendMessage` | Nu | Formularea preferată pe care o folosește Agentul când trimite elementul. Trunchiată la 500 de caractere. |
| `maxSendsPerConversation` | Nu | De câte ori poate fi trimis aceluiași contact într-o conversație. Valoarea implicită este `1`. |
| `sendAsVoiceNote` | Nu | Doar pentru încărcări audio — stochează fișierul ca notă vocală WhatsApp. Ignorat pentru alte tipuri de fișiere. |

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

Două lucruri se întâmplă automat: un GIF animat este convertit în video pentru a fi redat pe orice canal, iar platforma scrie un scurt rezumat al conținutului fișierului, astfel încât Agentul să știe când este potrivit să îl folosească.

O eroare `400` acoperă câmpurile lipsă, un tip de fișier neacceptat, un fișier gol sau prea mare și atingerea limitei de 50 de elemente. O eroare `403` înseamnă că biblioteca media este dezactivată pentru cont.

### Actualizarea unui element media

`PATCH /agents/{agentId}/media-library/{itemId}` — doar metadate. Fișierul în sine nu poate fi înlocuit; încărcați un element nou și ștergeți-l pe cel vechi. Acest corp folosește snake_case: `title`, `description`, `send_message`, `max_sends_per_conversation` (un număr întreg nenegativ sau `null` pentru a șterge limita).

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

**Răspuns** (`200`)

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

### Ștergerea unui element media

`DELETE /agents/{agentId}/media-library/{itemId}` — elimină elementul și fișierul stocat aferent. Ștergerea unui element care a fost deja eliminat reușește și raportează `deleted: false`, deci apelul poate fi reîncercat în siguranță.

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

---

## Generarea mesajelor de follow-up

`POST /agents/{agentId}/template-generation` — scrie mesajele de follow-up ale Agentului pentru dumneavoastră (atenționările pe care le trimite când o conversație devine inactivă), pe baza scopului Agentului.

| Câmp | Descriere |
|---|---|
| `type` | `all` (implicit) scrie întregul set. `cold_only` scrie doar mesajele pentru contactele care nu au răspuns niciodată. |

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

Există două moduri în care acesta revine, iar câmpul `target` vă indică care dintre ele:

- **`target: "agent"` cu un `200`** — mesajele au fost scrise în timpul apelului, iar rezultatul se află în `data`. Citiți-le din `follow_up_config` Agentului. Acesta este cazul obișnuit.
- **`target: "campaign"` cu un `202`** — lucrarea a fost pusă la coadă în campania numită în `campaign_id`. Urmăriți `template_generation_status` acelei campanii până când se finalizează.

`cold_only` necesită o campanie de ieșire și este refuzat cu `409` (`reason: "cold_only_requires_campaign"`) pe un Agent care nu are niciuna. Un `403` înseamnă că urmăririle automate nu sunt activate pentru cont. Aceasta utilizează credite AI, iar un `400` cu `"Insufficient credits."` înseamnă că contul nu mai are credite.

---

## Direcționarea conversațiilor către un Agent

Un Agent răspunde doar la conversațiile trimise de un **Punct de intrare**. Până când un canal are unul, un prim mesaj de la cineva cu care nu ați mai vorbit este stocat, dar nimic nu îl preia și niciun asistent nu răspunde.

| Ce doriți să faceți | Apel |
|---|---|
| Faceți un Agent să răspundă pentru un întreg canal | `PUT /entry-points/channel-defaults` cu `{ "channel": "instagram", "agent_id": "AGENT_ID" }` |
| Adăugați o regulă mai specifică (cuvinte cheie, comentarii, urmăritori noi) | `POST /agents/{agentId}/entry-points` |
| Vedeți regulile care indică spre un Agent | `GET /agents/{agentId}/entry-points` |
| Lăsați un canal fără nimeni care să răspundă | `DELETE /entry-points/channel-defaults?channel=instagram` |

### Listați punctele de intrare ale unui Agent

`GET /agents/{agentId}/entry-points` — regulile de direcționare care trimit conversații către acest Agent, cele mai noi primele. Atât regulile curente, cât și cele retrase sunt returnate; o regulă retrasă are `enabled: false`.

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

Pentru setările implicite ale canalului întregului cont, inclusiv un canal setat în mod deliberat să nu aibă pe nimeni, citiți `GET /entry-points/channel-defaults` în schimb.

### Creați un punct de intrare

`POST /agents/{agentId}/entry-points` — Agentul din cale câștigă întotdeauna, deci o regulă nu poate fi creată niciodată pentru un alt Agent decât cel din URL.

| `type` | Ce face |
|---|---|
| `channel_default` | Agentul răspunde fiecărui contact nou pe canalele listate. Preferați `PUT /entry-points/channel-defaults` pentru acest lucru — acesta retrage automat respondentul anterior, ceea ce crearea unui al doilea implicit aici nu face. |
| `keyword` | Agentul preia controlul când primul mesaj conține unul dintre `match_config.keywords`. Este necesar cel puțin un cuvânt cheie. |
| `instagram_comment` / `facebook_comment` | Agentul răspunde la comentariile de pe postările dvs. Canalul corespondent trebuie să fie listat în `channels`. |
| `instagram_follower` | Agentul salută noii urmăritori. |

`channels` este obligatoriu și specifică ce canale acoperă regula — de exemplu `whatsapp`, `whatsapp_web`, `instagram`, `messenger`, `telegram`, `sms`, `email`, `chat_widget` sau `custom_channel`. Regulile noi sunt activate, cu excepția cazului în care specificați altfel.

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

**Răspuns** (`201`)

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

**Ce regulă câștigă atunci când mai multe ar putea:** o conversație în curs sau o atribuire manuală păstrează Agentul pe care îl are deja; în caz contrar, regulile bazate pe cuvinte cheie prevalează asupra regulilor de comentarii, care prevalează asupra regulilor de urmăritori, iar o setare implicită a canalului este ultima soluție. Dacă aceste reguli decid ceva în acest moment pe un cont este raportat de `GET /entry-points/routing-status`.

Aceasta este versiunea scurtă. Ghidul [Entry Points API](entry-points.md) acoperă întreaga ierarhie, regulile pentru comentarii și urmăritori, un singur Agent per număr de WhatsApp, precum și modificarea sau ștergerea unei reguli. Consultați [Entry Points](../ai-agents/entry-points.md) pentru concept și [Channels API](channels.md) pentru conectarea canalului propriu-zis.

---

## Erori API Agenți AI

Endpoint-urile pentru agenți returnează plicul standard de eroare:

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

| Status | Când apare pe un endpoint de Agent |
|---|---|
| `400` | Un câmp obligatoriu lipsește sau este invalid — un corp de actualizare gol, o valoare în afara unei liste permise (`ai_speed`, `anthropic_model`, `booking_provider`, `mode`, `type`), o cheie care nu este zi lucrătoare în `availability`, un nume de câmp cu punct în `bot-config` sau un id malformat în cale. |
| `403` | Contul nu are permisiunea de a utiliza o setare trimisă, ați atins limita de agenți a planului dvs. sau o funcționalitate de care are nevoie acest endpoint (bibliotecă media, follow-up-uri, funcții personalizate pentru servere MCP) este dezactivată. O modificare care depășește dimensiunea de configurare permisă de planul dvs. este refuzată cu `400`. |
| `404` | Agentul, regula de etichetare, elementul media sau serverul MCP nu a fost găsit — fie nu există, fie aparține unui alt cont. |
| `409` | Ceva este deja în curs de desfășurare sau blochează acțiunea: o optimizare sau generare de etichete rulează, Agentul este încă atașat unei difuzări, unui Punct de intrare sau unei campanii, sau `cold_only` a fost solicitat fără o campanie de ieșire. |

Codurile partajate pe care orice endpoint le poate returna — `401`, `403` (planul dvs. nu include acces API), `429` (limită de rată) și `500` — sunt listate cu îndrumări pentru reîncercare în [Erori și Paginare](errors-and-pagination.md).

> **O notă despre explorator.** Endpoint-urile `/agents` se află în specificația OpenAPI publicată, astfel încât puteți naviga prin câmpurile lor exacte și puteți rula cereri live în [Referința API](reference.md). Endpoint-urile `/mcp-servers` la nivel de cont sunt, de asemenea, în specificație, deci le puteți explora și acolo.


---

## Legate

- [Agenți AI](../ai-agents/ai-agents.md) — ce este un Agent, explicat pe înțelesul tuturor.
- [Puncte de intrare](../ai-agents/entry-points.md) — cum sunt direcționate conversațiile către un Agent.
- [API Întrebări frecvente](faqs.md) — construiți și conectați cunoștințele din care răspunde Agentul dvs.
- [API Canale](channels.md) — conectați canalele pe care răspunde un Agent.
- [Conectați servere MCP la botul dvs.](../ai-automation/mcp-servers.md) · [Funcții personalizate](../ai-automation/custom-functions.md)
- [Referință API](reference.md) — exploratorul interactiv complet de endpoint-uri.