Здоровье агента: триаж и починка

🔵 Как инженеру (admin) разбирать падающего агента: найти сбой, понять причину, внести минимальную правку и доказать её прогоном. Отчёт без проверки — не результат.

1. Найти сбойную сессию

Шаг	Инструмент	Что смотреть
Сессии с ошибками	`trace_sessions(only_errors=true)`	`tool_errors`, `errors`, `warnings`, `agent`, `end_type`
Точечно по агенту	`trace_sessions(agent=<template>)`	последние сессии шаблона
Поиск по тексту	`trace_search(query="error")`	сами строки ошибок и их сессии
Диалог	`trace_transcript(session_id)`	запрос → ответ, какие тулы звались
Таймлайн	`trace_events(session_id)`	порядок `tool_call`/`tool_result`, `success:false`

Метрика warnings считает и декларативные предупреждения тулов, и extractor-warning (_warnings: отсутствующее/необязательное поле ответа). Ненулевой warnings при tool_errors=0 — сигнал о «мягком» сбое (поиск вернул пусто, поле не нашлось).

2. Прочитать конфигурацию агента

agent_config_show(name) — метаданные бандла (список файлов), затем agent_config_file(name, "tools/x.yaml") — по одному нужному файлу.
Защищённые admin/trace через builder не читаются (403) — это ожидаемо.
Если 404 «unknown agent» — это либо отсутствует в config/agents/, либо встроенный бандл модуля (например, coder из code): он есть в templates_list, но не в agent_configs_list.

3. Классифицировать причину

Симптом в трассе	Вероятная причина	Правка
`Error: env var 'X' is not set`	секрет не в окружении	`env_set(X, …)` (секрет — только в env)
`oauth.token_file '…': expected value at line 1 column 1`	пустой/битый JSON токена	переавторизация: `oauth_connect`/reconnect, авто-refresh в инструкции
`Tool 'X' is not allowed for this process`	тул зовётся напрямую, не через `tool_call`	переписать вызов через `tool_call(name,args)` или `tool_attach`
`Network error … /v1/tools/…` (после ~60с)	вложенный loopback-вызов завис/не обслужился	НЕ ретраить; заменить на реальный файл + `tool_call`
`No such file or directory` у `script_tool`	`tool_run_yaml` не тянет sibling-скрипт	завести `tools/<file>.yaml` + `tool_attach`
Один и тот же тул повторяется с той же ошибкой	нет «stop-правила» в инструкции	добавить запрет повтора и следующий шаг
`no human response within … — approval timed out`	gated-тул без человека	`delegate` вместо `agent_run` (approval всплывает в чат)
403/404 на `/v1/builder/*`	builder-модуль не активен	сказать прямо, не выдумывать поля

4. Минимальная правка

Меняй одно за раз: инструкцию, один тул, один хук, переменную среды. Не переписывай весь бандл. Для agent.yaml — agent_config_file → правка → agent_config_validate → agent_config_upsert(agent_yaml=…); остальные файлы остаются нетронутыми.

5. Доказать результат

Быстро: agent_run(template, message) — один ход; затем trace_transcript(session_id) — что реально произошло.
Надёжно: bench_run(template) (дешёвый прогон) и bench_run_show(run_id) — сравнить ходы/тулы/токены до и после. Правка «готова» только когда прогон это подтверждает.
Показывай before/after и честно говори, что улучшилось, а что нет.

6. Отчёт

Коротко: (1) что падало и где (session id, точная ошибка), (2) причина, (3) что изменено (файл + суть), (4) чем подтверждено (прогон, метрики), (5) что осталось.

Безопасность

Перед разрушительным (agent_kill, session_close, module_disable, agent_config_delete, env_unset, platform_restart) — предупредить и спросить подтверждение.
admin и trace защищены: их можно только tool_attach/tool_detach.
Не выдумывать эндпоинты, поля и ключи конфига — читать реальный бандл.