OLESA
فارسی
API и интеграции

Запуски агентов и расписания

Ключу требуется право agents. Ресурсы принадлежат аккаунту: другой ключ того же аккаунта видит те же запуски, чужой аккаунт — нет.

Каталог и запуск

GET /v1/agents/ возвращает доступные типы: kind, название, описание и поддержку расписаний. Входные поля зависят от агента.

curl https://api.o-lesa.ru/v1/agents/runs \
  -H "Authorization: Bearer $OLESA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"seo_audit","input":{"url":"https://example.com"}}'

Это ставит платную задачу в очередь и возвращает объект с id. Аудит проверит переданную публичную страницу. Для сравнения конкурентов используйте kind: competitor_scan, input.competitors — массив из 2–5 URL; необязательное input.own_url — ваш сайт.

Получение результата

GET /v1/agents/runs/{run_id} возвращает status, output, error, cost и временные метки. cost — стоимость в валюте баланса аккаунта, не всегда доллары.

Статусы:

  • pending — задача ожидает воркера;
  • running — выполняется;
  • succeeded — завершена, результат в output;
  • no_signal — выполнена, но агент не обнаружил события для уведомления;
  • failed — ошибка выполнения.

Проверяйте статус, например, раз в 5–10 секунд, либо подключите вебхук. Не держите один HTTP-запрос открытым до завершения агента.

GET /v1/agents/runs — история с параметрами kind, status, limit (до 200), offset. DELETE /v1/agents/runs/{run_id} удаляет запись и связанные данные; это не механизм отмены запущенного вычисления. До завершения удалять не рекомендуется.

Расписания

POST /v1/agents/schedules принимает:

{
  "kind": "seo_audit",
  "input": {"url": "https://example.com"},
  "cron": "0 9 * * 1",
  "delivery_channels": [],
  "one_shot": false
}

Cron состоит из пяти полей и использует UTC. Пример — каждый понедельник в 09:00 UTC. Расписание доступно только для schedulable: true.

  • GET /v1/agents/schedules — список.
  • PATCH /v1/agents/schedules/{id} — изменение cron, входных данных или enabled.
  • DELETE /v1/agents/schedules/{id} — удаление расписания.

delivery_channels поддерживает email, telegram, slack при настроенных подключениях. Вебхуки на свои сервисы регистрируются отдельно и получают завершения всех ваших агентов, в том числе запусков по расписанию.

Собственные процессы

API предоставляет операции с черновиками конструктора: /v1/agents/drafts и /v1/agents/drafts/{id}/run. Сначала создайте и проверьте процесс в интерфейсе. Схема графа — формат конструктора O·LESA; он не является универсальным стандартом агентов.

Авторизация не заменяет проверку входа. Для каждого агента передавайте только ожидаемые поля. Не повторяйте POST запуска при сетевой неопределённости без проверки истории: повтор может создать ещё одну задачу и расход.