EGGENT документация
English github Открыть Eggent Cloud ▸
Содержание
Автоматизация и интеграции

HTTP API для интеграций

Как подключить Eggent к своему сайту, CRM, боту или автоматизации — получить токен, отправить сообщение, передать файл, получать ответ потоком и сохранять разговор между запросами.

Внешний API — способ дать задачу агенту из другой программы: бэкенда сайта, CRM, n8n или Make, своего бота, фоновой задачи. Ты отправляешь сообщение, Eggent выполняет его как обычный чат и возвращает ответ.

Адрес

Где Eggent Базовый адрес
Облако https://имя.cloud.eggent.ai
Свой сервер адрес, по которому открывается Eggent, например https://eggent.example.com

Получить токен

  1. Открой Настройки → API.
  2. Сгенерируй токен внешнего API.
  3. Сохрани его в своей системе как секрет.

Токен передаётся в заголовке Authorization: Bearer <токен>. Не вставляй его в код, который выполняется в браузере: с ним можно давать агенту любые задачи. На своём сервере вместо генерации можно задать переменную EXTERNAL_API_TOKEN; токен из настроек главнее.

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

POST /api/external/message
Authorization: Bearer <токен>
Content-Type: application/json

curl -X POST https://имя.cloud.eggent.ai/api/external/message \
  -H "Authorization: Bearer $EGGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "crm:client-42",
    "projectName": "Продажи",
    "message": "Напиши короткое письмо клиенту по последним заметкам"
  }'

Поля запроса

Поле Обязательно Что это
sessionId да Постоянный ключ разговора. Один на пользователя, тред, клиента или задачу
message да Текст задачи, непустой
projectId нет id проекта (или точное имя, если оно одно)
projectName нет Точное имя проекта
chatId нет Существующий чат. Обычно не нужен
currentPath нет Подсказка рабочей папки для задач с файлами

Без проекта сообщение уходит оркестратору.

Ответ

{
  "success": true,
  "sessionId": "crm:client-42",
  "reply": "Здравствуйте, Анна! …",
  "context": {
    "activeProjectId": "sales",
    "activeProjectName": "Продажи",
    "activeChatId": "0a2f…",
    "activeChatTitle": "Звонок с Анной",
    "currentPath": ""
  },
  "chatChanged": false,
  "switchedProject": null,
  "createdProject": null
}

Если агент во время работы переключил или создал проект, это видно в switchedProject и createdProject. chatChanged равно true, когда разговор теперь в другом чате, чем до этого сообщения — агент его перевёл, — а activeChatTitle называет этот чат.

Как работает sessionId

Eggent помнит для каждого sessionId текущий проект, текущий чат и рабочую папку. Повторяй тот же sessionId — и агент продолжит тот же разговор, с историей. Новый sessionId — новый разговор.

Хорошие ключи: telegram:<user-id>, crm:<client-id>, slack:<channel>:<thread>, job:daily-report.

Ответ потоком

Если добавить заголовок Accept: text/event-stream, ответ придёт потоком событий (SSE) — удобно, чтобы показывать текст по мере написания. Каждое событие — JSON в строке data::

Событие Что значит
{"type":"text","delta":"…"} Очередной кусок ответа
{"type":"tool","name":"…","phase":"start"} Агент начал или закончил ("end") использовать инструмент
{"type":"done","result":{…}} Готово; result — тот же JSON, что и без потока
{"type":"error","status":500,"payload":{…}} Ошибка с тем кодом, который вернулся бы без потока

Если клиент отключился посреди ответа, работа не прерывается: агент доделает её, и результат сохранится в чате.

Отправить файл

POST /api/external/media-message
Authorization: Bearer <токен>
Content-Type: multipart/form-data

Поля те же, что у /message, плюс file и kind (document, photo, audio, video, voice, file). Файл сохраняется во вложения чата, агент его видит. Голосовое (kind=voice) сначала расшифровывается в текст.

curl -X POST https://имя.cloud.eggent.ai/api/external/media-message \
  -H "Authorization: Bearer $EGGENT_API_TOKEN" \
  -F "sessionId=crm:client-42" \
  -F "message=Выпиши из договора все сроки" \
  -F "kind=document" \
  -F "file=@./contract.pdf"

Ошибки

Код Причина Что сделать
400 Нет sessionId или message Передай оба непустыми строками
401 Нет токена или он неверный Проверь заголовок Authorization: Bearer …
404 Проект или чат не найден Проверь id и имена проектов
409 Имя проекта неоднозначно или чат из другого проекта Используй projectId или убери chatId
503 Токен не настроен Сгенерируй его в Настройки → API

Советы

  • Вызывай API только с сервера и только по HTTPS.
  • Ставь большой таймаут: сложная задача может выполняться несколько минут. Или используй поток.
  • Один реальный разговор — один sessionId.
  • Сообщение, которое начинается с @ и названия проекта, поручает задачу этому проекту, как в приложении: проект работает в своём чате, а его ответ входит в ответ API. См. Проекты.
  • Ответы через API тратят баланс так же, как чат, и всегда работают в полном режиме.

Эта страница в Markdown