Agent API

Odešlete zprávu a získejte odpověď z připojených znalostí, včetně zdrojů. Podporuje streamování. Předběžný přístup.

Na této stránce

Předběžný přístup / preview. Agent API je dostupné vývojovým partnerům. Pole a endpointy se mohou před obecnou dostupností změnit.

Agent API odpovídá na dotazy pouze z vašich připojených znalostí — ze zdrojů, které připojíte přes Notion, Slack, Google Drive a další MCP konektory. Každá odpověď se vrací se `sources`, o které se opírala, takže je můžete citovat a odpověď auditovat. Sdílí základní URL, Bearer autentizaci a formát chyb z přehledu API.

https://api.praktickai.app/v1/agent

Agent odpovídá jen z připojených znalostí. Když nenajde podloženou odpověď, řekne to a vrátí prázdné pole `sources` místo hádání — viz pole `grounded` níže.

Odeslání zprávy

POST /v1/agent/messages/

Položte agentovi dotaz a získejte podloženou odpověď. Předejte `conversation_id` pro pokračování existujícího vlákna, nebo ho vynechte pro nové.

Parametr	Typ	Povinné	Popis
message	string	ano	Dotaz nebo pokyn uživatele.
conversation_id	string	ne	Pokračování dřívější konverzace pro víceotázkový kontext.
stream	boolean	ne	Při `true` streamuje odpověď jako Server-Sent Events. Výchozí `false`.
source_ids	array	ne	Omezí odpověď na podmnožinu připojených zdrojů.

curl https://api.praktickai.app/v1/agent/messages/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Jaká je lhůta pro vrácení peněz u ročních plánů?"
  }'

{
  "id": "msg_5f0c",
  "conversation_id": "cnv_2a",
  "answer": "Roční plány lze vrátit do 30 dnů od nákupu. Poté jsou nevratné, ale přístup máte do konce zúčtovacího období.",
  "grounded": true,
  "sources": [
    {
      "source_id": "src_notion_07",
      "title": "Zásady fakturace a vracení",
      "url": "https://www.notion.so/acme/Billing-Refund-Policy",
      "snippet": "Roční plány jsou vratné do 30 dnů...",
      "connector": "notion"
    }
  ],
  "created_at": "2026-07-16T10:04:22Z"
}

Pole	Typ	Popis
id	string	Identifikátor zprávy s prefixem `msg_`.
conversation_id	string	Id vlákna — použijte znovu pro udržení kontextu mezi otázkami.
answer	string	Text podložené odpovědi.
grounded	boolean	`true`, pokud je odpověď podepřená zdroji; `false`, když agent neměl relevantní znalosti.
sources	array	Pasáže, o které se odpověď opírala — každá se `source_id`, `title`, `url`, `snippet` a `connector`.

Streamování

Pro chatová rozhraní nastavte `stream: true` a přijímejte odpověď postupně přes Server-Sent Events (`Accept: text/event-stream`). Tokeny přicházejí jako události `delta`; závěrečná událost `done` nese výsledné `sources` a id zprávy.

curl -N https://api.praktickai.app/v1/agent/messages/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{ "message": "Shrň onboarding checklist", "stream": true }'

event: delta
data: {"text": "Onboarding checklist má "}

event: delta
data: {"text": "čtyři kroky: pozvat, připojit, ověřit, nasadit."}

event: done
data: {"id": "msg_77", "conversation_id": "cnv_2a", "grounded": true, "sources": [{"source_id": "src_gdrive_02", "title": "Onboarding Checklist", "connector": "google_drive"}]}

Vykreslujte události `delta` průběžně pro živý efekt psaní a odkazy na citace připojte ze závěrečné události `done`, jakmile je odpověď hotová.

Správa znalostních zdrojů

Zdroje jsou připojený obsah, který agent smí číst. Připojte je přes MCP konektory (viz průvodce nastavením) a spravujte je těmito endpointy.

GET /v1/agent/knowledge/sources/

Vypíše připojené zdroje a jejich stav synchronizace.

curl https://api.praktickai.app/v1/agent/knowledge/sources/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx"

{
  "data": [
    {
      "source_id": "src_notion_07",
      "connector": "notion",
      "name": "Nápověda",
      "status": "synced",
      "documents": 128,
      "last_synced_at": "2026-07-16T08:00:00Z"
    },
    {
      "source_id": "src_slack_01",
      "connector": "slack",
      "name": "kanál #support",
      "status": "syncing",
      "documents": 0
    }
  ]
}

POST /v1/agent/knowledge/sources/

Připojí nový zdroj z autorizovaného MCP konektoru. Konektor nejprve autorizujte v admin konzoli; poté ho zde odkažte pomocí `connector` a `resource`, který chcete zpřístupnit (databáze Notionu, kanál Slacku, složka na Disku).

Parametr	Typ	Povinné	Popis
connector	string	ano	Jedno z `notion`, `slack`, `google_drive` (další přes MCP).
resource	string	ano	Id obsahu specifické pro konektor (id databáze, kanálu, složky).
name	string	ne	Čitelný název zobrazený v admin konzoli.
access	string	ne	Rozsah čtení — aktuálně jen `read`. Agent do vašich zdrojů nikdy nezapisuje.

curl https://api.praktickai.app/v1/agent/knowledge/sources/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "notion",
    "resource": "db_9f2c1a",
    "name": "Nápověda"
  }'

{
  "source_id": "src_notion_07",
  "connector": "notion",
  "name": "Nápověda",
  "status": "syncing",
  "access": "read",
  "created_at": "2026-07-16T10:10:00Z"
}

Nové zdroje začínají ve stavu `syncing` a po naindexování přejdou na `synced`. Agent zdroj použije, až je ve stavu `synced`.

Doporučené postupy

Udržujte konverzace opětovným použitím conversation_id, aby navazující dotazy měly kontext.
Vždy ve svém rozhraní zobrazujte vrácené zdroje, aby si uživatelé mohli odpovědi ověřit.
Použijte source_ids pro omezení odpovědí, když má workflow čerpat jen z konkrétního obsahu.
Před zobrazením odpovědi zkontrolujte příznak grounded — pokud je false, nabídněte předání člověku.