API чату з агентом

Santiago постачається з вбудованим AI-агентом, що працює всередині демона: ви надсилаєте йому інструкцію природною мовою, і він керує запущеним профілем за вас, використовуючи API автоматизації та скіл агента. Ця сторінка документує власну HTTP-поверхню агента — перевірку того, чи налаштовано LLM, збереження API-ключа, стримінг чату як Server-Sent Events та керування історією для кожного профілю.

Усі ендпоінти живуть під базою демона http://localhost:7891/api і використовують стандартний конверт: { "ok": true, "data": {...} } при успіху або { "ok": false, "error": { "code", "message" } } при невдачі. Демон слухає лише localhost.

Зведення ендпоінтів

Метод	Шлях	Призначення
`GET`	`/api/agent/status`	Чи налаштовано LLM? Список доступних моделей.
`GET`	`/api/agent/api-key`	Отримати налаштований ключ для провайдера (замаскований).
`POST`	`/api/agent/api-key`	Встановити API-ключ для провайдера.
`DELETE`	`/api/agent/api-key`	Видалити API-ключ для провайдера.
`GET`	`/api/agent/:profileId/history`	Прочитати збережені повідомлення чату для профілю.
`POST`	`/api/agent/:profileId/chat`	Надіслати повідомлення → SSE-стрим запуску агента.
`POST`	`/api/agent/:profileId/stop`	Перервати поточне виконання агента.
`DELETE`	`/api/agent/:profileId`	Очистити історію та знищити сесію.

Провайдер за замовчуванням — openai, коли поле provider або параметр запиту опущено.

Налаштування ключа LLM

Перш ніж агент зможе працювати, йому потрібен API-ключ LLM. Ключі зберігаються для кожного провайдера в локальному сховищі автентифікації демона, а не в профілі.

Перевірка статусу

GET /api/agent/status повідомляє, чи налаштовано ключ хоча б одного провайдера і які моделі доступні.

curl -s http://localhost:7891/api/agent/status | jq .data

{
  "configured": true,
  "models": [
    { "provider": "openai", "id": "gpt-5", "name": "GPT-5" }
  ]
}

Коли ключ не встановлено, демон повертає { "configured": false, "models": [] } — на цьому ендпоінті він ніколи не видає помилку.

Встановлення ключа

POST /api/agent/api-key зберігає ключ для провайдера. Поле apiKey є обов’язковим; порожнє значення або значення лише з пробілів повертає 400 BAD_REQUEST.

curl -s http://localhost:7891/api/agent/api-key -X POST \
  -H 'Content-Type: application/json' -d '{
    "provider": "openai",
    "apiKey": "sk-..."
  }'

{ "ok": true }

Отримання ключа (замаскованого)

GET /api/agent/api-key повертає збережений ключ для провайдера, замаскований до перших і останніх чотирьох символів. Передайте ?provider=, щоб вказати провайдера, відмінного від типового.

curl -s "http://localhost:7891/api/agent/api-key?provider=openai" | jq .data

{ "provider": "openai", "hasKey": true, "maskedKey": "sk-1…7f9c" }

Якщо ключ не збережено, hasKey має значення false, а maskedKey — null.

Видалення ключа

curl -s "http://localhost:7891/api/agent/api-key?provider=openai" -X DELETE

{ "ok": true }

Чат з агентом (SSE)

POST /api/agent/:profileId/chat надсилає одне повідомлення користувача й стримить запуск агента назад як Server-Sent Events. Профіль має бути запущеним — якщо це не так, демон відповідає 404 із PROFILE_NOT_RUNNING. Порожнє message повертає 400 BAD_REQUEST.

curl -N -s http://localhost:7891/api/agent/$PROFILE/chat -X POST \
  -H 'Content-Type: application/json' -d '{
    "message": "Go to example.com and tell me the page title"
  }'

Прапорець -N вимикає буферизацію curl, тож ви бачите події в міру їх надходження. Відповідь має Content-Type: text/event-stream; кожна подія — це рядок у формі data: <json>\n\n.

Форми подій SSE

Кожен рядок data: несе JSON-об’єкт із дискримінатором type. Це події, які демон видає під час запуску:

`type`	Поля	Значення
`tool_start`	`name`, `params`	Агент розпочав виклик інструмента автоматизації (напр. `navigate`, `click`).
`tool_end`	`name`, `ok`	Цей виклик інструмента завершився; `ok: false` означає, що він завершився з помилкою.
`text_delta`	`content`	Фрагмент текстової відповіді агента — конкатенуйте дельти по порядку.
`usage`	`input`, `output`, `total`	Підсумки токенів, надсилаються один раз після завершення запуску.
`done`	—	Агент завершив цей хід.
`error`	`message`	Запуск завершився невдачею; повідомлення також зберігається в історії.

data: {"type":"tool_start","name":"navigate","params":{"url":"https://example.com"}}

data: {"type":"tool_end","name":"navigate","ok":true}

data: {"type":"tool_start","name":"snapshot","params":{}}

data: {"type":"tool_end","name":"snapshot","ok":true}

data: {"type":"text_delta","content":"The page title is "}

data: {"type":"text_delta","content":"\"Example Domain\"."}

data: {"type":"done"}

data: {"type":"usage","input":4821,"output":137,"total":4958}

Зупинка запуску

Щоб перервати тривалий хід, викличте ендпоінт зупинки з тим самим id профілю. Він повертає, чи було перервано активний запуск.

curl -s http://localhost:7891/api/agent/$PROFILE/stop -X POST | jq .data

{ "aborted": true }

Історія

Кожен профіль зберігає власну історію чату в демоні. Повідомлення зберігаються в міру спілкування — повідомлення користувача, виклики інструментів агентом, текст агента та будь-які помилки.

Читання історії

curl -s http://localhost:7891/api/agent/$PROFILE/history | jq .data

{
  "messages": [
    { "type": "user", "content": "Go to example.com and tell me the page title" },
    { "type": "tool", "content": "", "toolName": "navigate", "params": { "url": "https://example.com" } },
    { "type": "agent", "content": "The page title is \"Example Domain\"." }
  ]
}

type повідомлення — одне з user, tool (несе toolName і params), agent або error.

Очищення історії та завершення сесії

DELETE /api/agent/:profileId очищає збережені повідомлення та знищує in-memory сесію агента для цього профілю. Наступний чат починається з чистого аркуша (і повторно інжектує скіл).

curl -s http://localhost:7891/api/agent/$PROFILE -X DELETE

{ "ok": true }

Помилки

Статус	`code`	Коли
`400`	`BAD_REQUEST`	`apiKey` або `message` відсутні/порожні.
`404`	`PROFILE_NOT_RUNNING`	Цільовий профіль не запущено.
`500`	`AGENT_ERROR`	Не вдалося створити сесію.
`500`	`INTERNAL_ERROR`	Не вдалося зберегти або видалити ключ.

Невдачі посеред стриму під час чату не є HTTP-помилками — з’єднання вже повернуло 200, тож невдача надходить натомість як SSE-подія error.

Пов’язане

Локальний HTTP API — базові шляхи, конверт і модель безпеки localhost.
Встановлення скіла агента — запустіть власного агента проти API автоматизації натомість.
Довідник API — повний каталог дій автоматизації для кожної дії, якими керує агент.
Автономний режим — тривалі сесії агента із заданою тривалістю роботи.