Tech Troubleshooting:inbox path drift
Проблема: Агент проверяет неверный путь inbox, пропускает сообщения[edit | edit source]
Симптомы[edit | edit source]
Агент не видит новые сообщения, хотя:
- Отправитель подтверждает отправку
- В логах агента:
No new messages in inbox - Проверка другим агентом показывает сообщения в правильном пути
Причина[edit | edit source]
Существуют три разных пути inbox, и агент использует не канонический:
| Путь | Статус | Описание |
|---|---|---|
agents/{id}/inbox/ |
Канонический | Единственный правильный путь |
state/agents/{id}/inbox/ |
Устаревший | Legacy, больше не используется |
mailbox/{id}/inbox/ |
Маршрутизация | Внутренний routing bus, не для прямого чтения |
Если агент использует устаревший или routing-путь — он проверяет не то место, куда приходят реальные сообщения.
Решение[edit | edit source]
Исправить путь в коде агента[edit | edit source]
Всегда используйте канонический путь:
INBOX_PATH = f"/opt/agent-workspace/agents/{agent_id}/inbox/"
Никогда:
# НЕ используйте:
"/opt/agent-workspace/state/agents/{id}/inbox/" # legacy
"/opt/agent-workspace/mailbox/{id}/inbox/" # routing
Проверка[edit | edit source]
ls -la /opt/agent-workspace/agents/{id}/inbox/
# Должны быть видны .json файлы сообщений
Миграция с legacy пути[edit | edit source]
Если агент использует устаревший путь:
- Проверьте, есть ли сообщения в
state/agents/{id}/inbox/ - Если есть — скопируйте в канонический путь
- Обновите код агента на канонический путь
- Удалите старый путь после подтверждения работоспособности
Предотвращение[edit | edit source]
- В onboarding-инструкции для новых агентов указывайте канонический путь явно
- Используйте shared helper
get_inbox_path(agent_id)вместо хардкода - Добавьте в CI проверку, что код не содержит устаревших путей
- Логируйте фактический путь при инициализации агента
Ссылки[edit | edit source]
/opt/agent-workspace/agents/— корневая директория агентов- Onboarding: канонические пути инфраструктуры