Агенты¶

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

Маршрут: /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) может попасть в очередь кандидатов.

Как увидеть кандидатов (SDK)¶

Discovery — не сканер ПК. Кандидаты появляются, когда незарегистрированный клиент шлёт события:

Сценарий	Результат
`register()` + `log_action()`	Агент в Agents, события в Audit
`ingest_discovery()` без `register()`	Кандидат в Discovery
OpenAI/LangChain wrapper: audit упал	Fallback → `ingest_discovery()`

Быстрый демо-скрипт (без регистрации агента):

export AEGISAI_API_KEY=<tenant-api-key>
export AEGISAI_BASE_URL=https://agentops.fun
docker compose -f docker-compose.prod.yml exec -T \
  -e AEGISAI_API_KEY -e AEGISAI_BASE_URL \
  app poetry run python scripts/shadow_discovery_demo.py

Без деплоя скрипта — тот же ingest через curl:

curl -sS -X POST "$AEGISAI_BASE_URL/api/v1/discovery/ingest" \
  -H "X-API-Key: $AEGISAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event":{"action":"openai_chat_completion","resource":"llm.openai","source":"openai","integration":"openai","sdk":"openai","orphan_audit":true,"risk_score":0.75}}'

Откройте /discovery → Confirm (создаст агента) или Dismiss.

Для реального LLM-кода используйте обёртки из интеграций (AegisOpenAIWrapper, LangChain callback). Чтобы активность шла в реестр, вызывайте register(); чтобы имитировать «теневой» агент — не регистрируйте и вызывайте ingest_discovery().

Действие	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 AgentOpsClient

async with AgentOpsClient(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:8001/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:8001/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`	Пользовательский	Любой другой