Агенты¶

Раздел Агенты — реестр всех зарегистрированных ИИ-агентов вашего арендатора.

Маршрут: /agents

Список агентов¶

Таблица с пагинацией:

Колонка	Описание
Имя	Отображаемое имя агента
Тип	`llm`, `rag`, `action`, `orchestrator`, …
Predicted	ML-прогноз типа по embeddings
Риск	Risk score из недавних audit
Статус	`active`, `inactive`, `suspended`
Версия	Версия агента
Последний раз	Время последнего heartbeat
Действия	Просмотр / удаление

Фильтрация и поиск¶

Семантический поиск — GET /api/v1/agents/search?q=... (hashed embeddings). Header search и фильтр на Agents ведут на /agents?q=....
Embeddings обновляются при register, heartbeat (если stale) и после audit write.
Фильтр по статусу / типу агента

Shadow AI Discovery¶

Маршрут: /discovery

Незарегистрированная активность (orphan audit, webhook без agent_id, LangChain/OpenAI discovery fallback) может попасть в очередь кандидатов:

Действие	API	Описание
Список	`GET /api/v1/discovery/candidates`	Pending кандидаты с score и evidence
Ingest	`POST /api/v1/discovery/ingest`	Одно событие
Batch	`POST /api/v1/discovery/ingest/batch`	Пакет + clustering
Cluster	`POST /api/v1/discovery/cluster`	Async merge похожих pending
Подтвердить	`POST /api/v1/discovery/candidates/{id}/confirm`	HITL → `register` + link fingerprint
Отклонить	`POST /api/v1/discovery/candidates/{id}/dismiss`	Закрыть кандидата

Подтверждение создаёт агента в реестре. Метрики: shadow_candidates_total, shadow_time_to_confirm_seconds.

Детали агента¶

Маршрут: /agents/:id

Общая информация¶

Поле	Описание
ID	UUID агента
Имя	Имя при регистрации
Тип	Категория агента
Predicted Type	Прогноз типа + confidence
Embedding Risk	Risk из embeddings
Статус	Текущее состояние
Capabilities	`observe`, `track`, `execute` и др.
Permissions	JSON с разрешениями

Активность¶

Последние 20 записей аудита агента
Средний risk score
Количество аномалий

Действия¶

Действие	Роль	Описание
Редактировать	Developer+	Изменить имя, capabilities
Приостановить	Admin+	Установить статус `suspended`
Удалить	Admin+	Удалить агента из реестра

Удаление агента

Удаление необратимо. Связанные записи аудита сохраняются, но агент перестаёт принимать запросы.

Регистрация агента¶

Агенты регистрируются программно через SDK или API:

Python SDKREST API

from aegisai.sdk import AegisAIClient

async with AegisAIClient(api_key="...", agent_name="Sales Bot") as client:
    reg = await client.register(
        capabilities=["observe", "track"],
        permissions={"max_risk": 0.5},
    )
    print(reg.id)

curl -X POST http://localhost:8000/api/v1/agents/register \
  -H "X-API-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Bot",
    "type": "llm",
    "capabilities": ["observe", "track"]
  }'

Heartbeat¶

Агенты должны периодически отправлять heartbeat для подтверждения активности:

curl -X POST http://localhost:8000/api/v1/agents/<agent_id>/heartbeat \
  -H "X-API-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

Рекомендация

Отправляйте heartbeat каждые 30–60 секунд. Агенты без heartbeat более 5 минут помечаются как inactive.

Типы агентов¶

Тип	Описание	Пример
`llm`	LLM-агент (GPT, Claude и др.)	Чат-бот поддержки
`tool`	Инструментальный агент	API-интеграция
`workflow`	Оркестратор (LangGraph)	Multi-step pipeline
`custom`	Пользовательский	Любой другой