Агенты

Агент — именованная личность с правами: AI-агент, cron-скрипт или CI-пайплайн. Агент задаёт человеку вопросы, просит согласования и принимает задачи; человек отвечает кнопками в Telegram/Max, приложении или кабинете. Агент создаётся вместе с API-ключом (настройки проекта → «Агенты») или автоматически при подключении MCP-клиента.

Вопрос человеку

Вопрос доставляется собеседникам агента карточкой с кнопками. Ответ — вариант или свободный текст (если разрешён). 1 кредит за доставку.

POST /v1/agent/ask

Authorization: Bearer zn_live_...

{

"question": "Выкатить v2.4.1 в прод?",

"options": ["Да", "Нет"],

"comment": "Все тесты зелёные",

"ttl_minutes": 60

}

→ 202 {

"request_id": "agrq_3xK...",

"status": "pending",

"deliveries": 1

}

Забор ответа — long-poll

Держим соединение до 45 секунд (wait, дефолт 25) — публичный адрес не нужен: работает из cron, CI и с ноутбука. status=pending — зовите снова.

GET /v1/agent/requests/agrq_3xK...?wait=25

→ пока нет ответа: { "status": "pending", ... }

→ человек нажал кнопку: {

"status": "answered",

"answer": "Да",

"reason_code": "answered",

"answered_by": "Пётр",

"answered_via": "telegram"

}

Согласование внешнего действия

Для действий вне Zapnoty (оплата, деплой, удаление). Человек видит [Одобрить]/[Отклонить]. Параметры фиксируются в аудите — передавайте их честно.

POST /v1/agent/approve

{

"action_type": "pay_invoice",

"description": "Оплатить счёт №1042 на 45 000 ₽",

"params": { "invoice": 1042, "amount": 45000 }

}

→ 202 { "request_id": "agrq_...", "status": "pending" }

# reason_code в ответе long-poll:

# approved_full → делайте действие

# rejected_by_human → НЕ делайте и не переспрашивайте

# expired → человек не ответил за TTL

Кому уходит вопрос

По умолчанию вопрос уходит всем собеседникам агента — отвечает тот, кто быстрее, остальные видят «Ответил Пётр». Чтобы спросить конкретного человека, передайте principal: id собеседника из кабинета или sub_… подписчика. Собеседников назначает владелец во вкладке «Агенты» — агент не может добавить их сам.

Права и гранты

Права агента настраиваются по 18 ресурсам: нет · чтение · запись · через запрос. «Через запрос» — вызов возвращает 202 grant_required, человек одобряет разово или на срок, повтор вызова проходит по гранту. 403 scope_forbidden — просите владельца расширить права; 429 budget_exceeded — дневной лимит, остановитесь.

# Ресурс с уровнем «через запрос» (ask)

POST /v1/broadcast → 202 {

"request_id": "agrq_...",

"reason": "grant_required",

"hint": "Опрашивайте запрос; после одобрения повторите вызов"

}

# Человек жмёт «Разрешить на сутки» → грант. Повтор вызова проходит:

POST /v1/broadcast → 200 { "job_id": ... }

Успешный вызов по гранту возвращает заголовок X-Agent-Grant-Expires — момент, до которого грант действует (или never). По нему видно, сколько ещё можно работать, не беспокоя человека повторно.

Команды и задачи (wake)

Агент публикует команды — человек видит кнопки в чате и приложении, может писать свободный текст (если разрешено) и запускать по расписанию (recurring). Push-вебхук agent.task.created — с тарифа «Базовый».

# Публикация команд (кнопки у человека)

PUT /v1/agent/commands

{ "commands": [

{ "key": "deploy", "label": "🚀 Выкатить" },

{ "key": "status", "label": "📊 Статус" }

] }

# Забор задач (long-poll; человек нажал кнопку или написал текст)

GET /v1/agent/tasks?wait=25

→ { "task": { "task_id": "agtk_...", "command": "deploy", "text": "" } }

# Результат — человеку в чат с подписью агента

POST /v1/agent/tasks/agtk_.../complete

{ "result": "Выкатил v2.4.1, ошибок нет" }

Sandbox

С тестовым ключом вопросы не уходят человеку и кредиты не списываются — прогоните весь сценарий, включая отказ и истечение.

# Тестовый ключ zn_test_: вопрос НЕ уходит человеку, исход симулируется

POST /v1/agent/ask

{

"question": "...",

"_test_directives": { "decision": "answered", "answer": "Да", "delay_ms": 2000 }

}

MCP

Claude Code и Cursor подключаются к mcp.zapnoty.com через OAuth с выбором прав («Безопасные» — отправка через подтверждение). Инструменты: zapnoty_ask_user (блокирующий — ждёт ответа человека), zapnoty_request_approval, zapnoty_check_answer, zapnoty_get_tasks и zapnoty_complete_task (задачи от человека), zapnoty_set_commands (кнопки в чате), zapnoty_send_to_thread (сообщение без вопроса), zapnoty_request_key и zapnoty_verify_mandate.

Связанные разделы

Webhooks — входящие события

Входящие события: подписка, доставка, рассылка, тикеты, формы. HMAC-подпись.

Virtual Projects — AI-настройка проекта

AI создаёт и настраивает проект под пользователя через MCP. Пользователь только Accept.

MCP-сервер для AI-агентов

Подключите Zapnoty к AI-агенту через OAuth в один клик: ~60 инструментов поверх API.

Документация API