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)
• Błędy i stronicowanie — zobacz Błędy i stronicowanie

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.

Jak zbudowany jest Agent #

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

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

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

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.

Parametry zapytania

cURL

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

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

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)

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

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

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

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

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)

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

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

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

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

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

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

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)

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

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.

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.

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)

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

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

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)

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

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

Odpowiedź (201)

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

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

Odpowiedź (200)

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

Zablokowano (409)

{
  "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 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ą.

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

Odpowiedź (200)

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

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.

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)

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

Dodaj regułę tagowania #

POST /agents/{agentId}/tags

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)

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

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.

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.

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)

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

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)

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

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.

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.

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

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)

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

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.

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)

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

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)

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

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

Odpowiedź (200)

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

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

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)

{
  "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ć.

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.

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.

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.

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.

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.

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)

{ "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 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, aby poznać koncepcję, oraz Channels API, aby dowiedzieć się, jak połączyć sam kanał.

Błędy API agentów AI #

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

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

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.

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. 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 — czym jest agent, wyjaśnione prostym językiem.
• Punkty wejścia — w jaki sposób rozmowy są kierowane do agenta.
• API FAQ — budowanie i łączenie wiedzy, na podstawie której odpowiada agent.
• API kanałów — łączenie kanałów, na których odpowiada agent.
• Łączenie serwerów MCP z botem · Funkcje niestandardowe
• Dokumentacja API — pełny interaktywny eksplorator punktów końcowych.