Agent API

Отправьте сообщение и получите ответ из подключённых знаний с источниками. Поддерживает потоковую передачу. Ранний доступ.

На этой странице

Ранний доступ / предпросмотр. Agent API доступен партнёрам по разработке. Поля и эндпоинты могут измениться до общего релиза.

Agent API отвечает на вопросы только из ваших подключённых знаний — источников, которые вы подключаете через Notion, Slack, Google Drive и другие MCP-коннекторы. Каждый ответ возвращается с `sources`, на которых он основан, чтобы их можно было цитировать и проверять. Использует базовый URL, Bearer-аутентификацию и формат ошибок из обзора API.

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

Агент отвечает только из подключённых знаний. Когда обоснованного ответа нет, он сообщает об этом и возвращает пустой массив `sources`, а не догадывается — см. поле `grounded` ниже.

Отправка сообщения

POST /v1/agent/messages/

Задайте агенту вопрос и получите обоснованный ответ. Передайте `conversation_id`, чтобы продолжить существующую беседу, или опустите его для новой.

Параметр	Тип	Обязательный	Описание
message	string	да	Вопрос или инструкция пользователя.
conversation_id	string	нет	Продолжение прежней беседы для многошагового контекста.
stream	boolean	нет	При `true` передаёт ответ как Server-Sent Events. По умолчанию `false`.
source_ids	array	нет	Ограничивает ответ подмножеством подключённых источников.

curl https://api.praktickai.app/v1/agent/messages/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Какой срок возврата для годовых планов?"
  }'

{
  "id": "msg_5f0c",
  "conversation_id": "cnv_2a",
  "answer": "Годовые планы можно вернуть в течение 30 дней с момента покупки. После этого возврат невозможен, но доступ сохраняется до конца оплаченного периода.",
  "grounded": true,
  "sources": [
    {
      "source_id": "src_notion_07",
      "title": "Правила оплаты и возврата",
      "url": "https://www.notion.so/acme/Billing-Refund-Policy",
      "snippet": "Годовые планы можно вернуть в течение 30 дней...",
      "connector": "notion"
    }
  ],
  "created_at": "2026-07-16T10:04:22Z"
}

Поле	Тип	Описание
id	string	Идентификатор сообщения с префиксом `msg_`.
conversation_id	string	Id беседы — используйте повторно для сохранения контекста.
answer	string	Текст обоснованного ответа.
grounded	boolean	`true`, если ответ подкреплён источниками; `false`, когда у агента не было релевантных знаний.
sources	array	Фрагменты, на которых основан ответ — каждый с `source_id`, `title`, `url`, `snippet` и `connector`.

Потоковая передача

Для чат-интерфейсов задайте `stream: true`, чтобы получать ответ постепенно через Server-Sent Events (`Accept: text/event-stream`). Токены приходят как события `delta`; финальное событие `done` несёт итоговые `sources` и id сообщения.

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": "Кратко опиши чек-лист онбординга", "stream": true }'

event: delta
data: {"text": "В чек-листе онбординга "}

event: delta
data: {"text": "четыре шага: пригласить, подключить, проверить, развернуть."}

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

Отображайте события `delta` по мере поступления для эффекта живого набора, а ссылки на цитаты добавьте из финального события `done`, когда ответ завершён.

Управление источниками знаний

Источники — это подключённый контент, который агенту разрешено читать. Подключайте их через MCP-коннекторы (см. руководство по настройке) и управляйте ими через эти эндпоинты.

GET /v1/agent/knowledge/sources/

Возвращает подключённые источники и их статус синхронизации.

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

{
  "data": [
    {
      "source_id": "src_notion_07",
      "connector": "notion",
      "name": "Справочный центр",
      "status": "synced",
      "documents": 128,
      "last_synced_at": "2026-07-16T08:00:00Z"
    },
    {
      "source_id": "src_slack_01",
      "connector": "slack",
      "name": "канал #support",
      "status": "syncing",
      "documents": 0
    }
  ]
}

POST /v1/agent/knowledge/sources/

Подключает новый источник из авторизованного MCP-коннектора. Сначала авторизуйте коннектор в консоли администратора; затем сошлитесь на него здесь через `connector` и `resource`, который хотите открыть (база Notion, канал Slack, папка Drive).

Параметр	Тип	Обязательный	Описание
connector	string	да	Одно из `notion`, `slack`, `google_drive` (другие через MCP).
resource	string	да	Id контента, специфичный для коннектора (id базы, канала, папки).
name	string	нет	Читаемая метка, показываемая в консоли администратора.
access	string	нет	Область чтения — сейчас только `read`. Агент никогда не пишет в ваши источники.

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": "Справочный центр"
  }'

{
  "source_id": "src_notion_07",
  "connector": "notion",
  "name": "Справочный центр",
  "status": "syncing",
  "access": "read",
  "created_at": "2026-07-16T10:10:00Z"
}

Новые источники начинают в статусе `syncing` и переходят в `synced` после индексации. Агент использует источник только когда его статус `synced`.

Agent API

На этой странице

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

Отправка сообщения

POST /v1/agent/messages/

Параметр	Тип	Обязательный	Описание
message	string	да	Вопрос или инструкция пользователя.
conversation_id	string	нет	Продолжение прежней беседы для многошагового контекста.
stream	boolean	нет	При `true` передаёт ответ как Server-Sent Events. По умолчанию `false`.
source_ids	array	нет	Ограничивает ответ подмножеством подключённых источников.

curl https://api.praktickai.app/v1/agent/messages/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Какой срок возврата для годовых планов?"
  }'

{
  "id": "msg_5f0c",
  "conversation_id": "cnv_2a",
  "answer": "Годовые планы можно вернуть в течение 30 дней с момента покупки. После этого возврат невозможен, но доступ сохраняется до конца оплаченного периода.",
  "grounded": true,
  "sources": [
    {
      "source_id": "src_notion_07",
      "title": "Правила оплаты и возврата",
      "url": "https://www.notion.so/acme/Billing-Refund-Policy",
      "snippet": "Годовые планы можно вернуть в течение 30 дней...",
      "connector": "notion"
    }
  ],
  "created_at": "2026-07-16T10:04:22Z"
}

Поле	Тип	Описание
id	string	Идентификатор сообщения с префиксом `msg_`.
conversation_id	string	Id беседы — используйте повторно для сохранения контекста.
answer	string	Текст обоснованного ответа.
grounded	boolean	`true`, если ответ подкреплён источниками; `false`, когда у агента не было релевантных знаний.
sources	array	Фрагменты, на которых основан ответ — каждый с `source_id`, `title`, `url`, `snippet` и `connector`.

Потоковая передача

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": "Кратко опиши чек-лист онбординга", "stream": true }'

event: delta
data: {"text": "В чек-листе онбординга "}

event: delta
data: {"text": "четыре шага: пригласить, подключить, проверить, развернуть."}

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

Управление источниками знаний

GET /v1/agent/knowledge/sources/

Возвращает подключённые источники и их статус синхронизации.

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

{
  "data": [
    {
      "source_id": "src_notion_07",
      "connector": "notion",
      "name": "Справочный центр",
      "status": "synced",
      "documents": 128,
      "last_synced_at": "2026-07-16T08:00:00Z"
    },
    {
      "source_id": "src_slack_01",
      "connector": "slack",
      "name": "канал #support",
      "status": "syncing",
      "documents": 0
    }
  ]
}

POST /v1/agent/knowledge/sources/

Параметр	Тип	Обязательный	Описание
connector	string	да	Одно из `notion`, `slack`, `google_drive` (другие через MCP).
resource	string	да	Id контента, специфичный для коннектора (id базы, канала, папки).
name	string	нет	Читаемая метка, показываемая в консоли администратора.
access	string	нет	Область чтения — сейчас только `read`. Агент никогда не пишет в ваши источники.

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": "Справочный центр"
  }'

{
  "source_id": "src_notion_07",
  "connector": "notion",
  "name": "Справочный центр",
  "status": "syncing",
  "access": "read",
  "created_at": "2026-07-16T10:10:00Z"
}

Agent API

Отправка сообщения

POST /v1/agent/messages/

Потоковая передача

Управление источниками знаний

GET /v1/agent/knowledge/sources/

POST /v1/agent/knowledge/sources/

Рекомендации

Agent API

Отправка сообщения

POST /v1/agent/messages/

Потоковая передача

Управление источниками знаний

GET /v1/agent/knowledge/sources/

POST /v1/agent/knowledge/sources/

Рекомендации