3.6 KiB
API запусков и расписаний
Общие правила: conventions.md. Operator запускает и отменяет доступные ему агенты; viewer читает разрешённые Run. Доступ к самому агенту не заменяет проверку прав на его connections.
| Метод и путь | Запрос | Ответ | Особенности |
|---|---|---|---|
| POST /v1/runs | agentId, agentRevision, input, poolId?, limits? | 202 Run | Idempotency-Key, policy и квоты |
| GET /v1/runs | agentId?, status?, cursor, limit | 200 Page | Tenant-scoped |
| GET /v1/runs/{id} | — | 200 Run | Каноническое состояние |
| GET /v1/runs/{id}/events | Last-Event-ID | SSE RunEvent | 410 при истёкшем cursor |
| GET /v1/runs/{id}/artifacts | cursor, limit | 200 Page | Без долгоживущих URL |
| POST /v1/runs/{id}/artifacts/{artifactId}/download | — | 200 DownloadGrant | Повторная проверка прав |
| POST /v1/runs/{id}/cancel | reason? | 202 Run | Идемпотентная команда; terminal run → 409 |
| POST /v1/runs/{id}/retry | acknowledgedExternalEffects:boolean | 202 новый Run | parentRunId, новый ключ, проверка policy |
| POST /v1/runs/{id}/responses | responseId, inputRequestId, value | 202 Run | Только waiting_input; схема ответа и права |
| POST /v1/schedules | agentId, cron, timezone, overlapPolicy | 201 Schedule | operator; cron и timezone валидируются |
| PATCH /v1/schedules/{id} | cron?, timezone?, enabled?, overlapPolicy?; If-Match | 200 Schedule | 412 conflict |
| GET /v1/schedules | cursor, limit | 200 Page | Tenant-scoped |
| DELETE /v1/schedules/{id} | If-Match | 204 | Останавливает будущие, не текущие Run |
Run: id, tenantId, agentId, agentRevisionId, status, specDigest, createdAt, startedAt?, finishedAt?, attemptCount, parentRunId?, error?, resultManifest?, inputRequest?. Полный spec доступен только субъектам с run:read-config; обычный status не содержит конфигурацию.
Schedule: id, tenantId, agentId, cron, timezone, overlapPolicy (skip/queue), enabled, nextRunAt, revision. Каждое срабатывание фиксирует текущую ревизию агента; уже созданный Run не меняется при обновлении агента. Cron интерпретируется как пять полей (минута, час, день месяца, месяц, день недели); шаг менее минуты не поддерживается.
Limits: cpuMillis, memoryBytes, timeoutSeconds, outputBytes. Пользователь может запросить меньше предела policy; превышение даёт 422, а не скрытое повышение прав. Input — JSON по input schema template. PoolId не даёт доступ к чужому пулу.
Пример
{"agentId":"agent_company","agentRevision":1,"input":{"company":"Example Company"},"limits":{"cpuMillis":1000,"memoryBytes":1073741824,"timeoutSeconds":900,"outputBytes":104857600}}
Отмена не гарантирует отмену уже совершённого внешнего действия. Reconcile технического статуса выполняет сервис исполнения; пользовательский запрос не переписывает состояние Runner произвольно.