32 lines
3.2 KiB
Markdown
32 lines
3.2 KiB
Markdown
# API экземпляров агентов
|
||
|
||
Общие правила: [conventions.md](conventions.md). Все ресурсы scoped к tenant. Viewer читает разрешённые агенты; operator создаёт и настраивает свои, admin — разрешённые tenant-агенты
|
||
|
||
| Метод и путь | Запрос | Ответ | Поведение |
|
||
|---|---|---|---|
|
||
| POST /v1/agents | name, templateVersionId, config, connections | 201 Agent | Создаёт revision=1 после проверки |
|
||
| GET /v1/agents | cursor, limit | 200 Page<Agent> | Только доступные |
|
||
| GET /v1/agents/{id} | — | 200 Agent с currentRevision | Проверка owner/tenant |
|
||
| POST /v1/agents/{id}/config/validate | config, templateVersionId? | 200 ValidationResult | Без сохранения |
|
||
| PUT /v1/agents/{id}/config | config, connections; If-Match | 200 AgentRevision | Полная конфигурация; 412 lost update |
|
||
| GET /v1/agents/{id}/revisions/{revision} | — | 200 AgentRevision | Неизменяемый snapshot |
|
||
| POST /v1/agents/{id}/upgrade-preview | targetTemplateVersionId | 200 UpgradePreview | Diff, requiredPermissions, ошибки |
|
||
| POST /v1/agents/{id}/upgrade | targetTemplateVersionId, config, connections; If-Match | 200 AgentRevision | Новая ревизия, старые Run не меняются |
|
||
| DELETE /v1/agents/{id} | If-Match | 202 operationId | Архивирует; активные Run требуют отдельной отмены |
|
||
|
||
Agent: id, tenantId, ownerId, name, currentRevision, archivedAt?, createdAt. AgentRevision: id, agentId, revision, templateVersionId, configSchemaDigest, config, connections, createdAt. Connections — map логического имени на connectionId, без секретов
|
||
|
||
ValidationResult: valid:boolean, errors:[{path, code, message}], effectiveConfig. При семантически невалидной конфигурации endpoint validate возвращает 200 valid=false; endpoints сохранения возвращают 422. Ссылки на чужие подключения не раскрываются в errors
|
||
|
||
UpgradePreview: fromVersionId, toVersionId, changes:[{path, kind}], validation, addedPermissions. Preview не разрешает новые доступы автоматически. Принятие upgrade заново проверяет rights и policy
|
||
|
||
## Пример создания
|
||
|
||
```json
|
||
{"name":"Обзор компаний","templateVersionId":"version_company_1","config":{"lookbackDays":90,"reportLanguage":"ru","includeSources":true},"connections":{}}
|
||
```
|
||
|
||
## Подключения
|
||
|
||
GET /v1/connections возвращает Page<ConnectionSummary> с cursor и limit, без credentials. Подключения создаются через provider authorization flow; единый контракт и защищённая передача API key описаны в [Provider API](provider-api.md). DELETE /v1/connections/{id} отзывает платформенный доступ и при возможности выполняет revoke у провайдера. Повторное использование в новом Run после отзыва запрещено
|