agent-tools: Known Failure Modes

agent-tools handles the shallow path: consumes from agent.normalize.request queue, runs tool normalization and distiller, publishes to agent.chat.request.

FAILURE MODES:

1. RabbitMQ disconnect — cannot consume from normalize.request or publish to agent.chat.request. Shallow-path messages are lost or stuck in queue.

2. llm-gateway unavailable — distiller call fails. All tool normalization stops.

3. Qdrant unavailable — distiller_examples few-shot retrieval fails. Distiller falls back to zero-shot or errors.

4. Tool execution failure — individual tools (knowledge_search, graph_lookup, etc.) may fail silently if their backing service is down. Check tool-specific dependencies.

5. Neo4j connection refused — graph_lookup and update_known_person tools fail. Non-fatal for the pipeline but response context is degraded.

6. normalize.request queue depth rising — agent-tools is down or not consuming. Messages accumulate in queue. Consumer count on normalize.request drops to 0.

FIRST CHECKS:

• RabbitMQ: consumer count on agent.normalize.request queue (should be 1). Depth rising = agent-tools not consuming.
• llm-gateway health — distiller dependency.
• Qdrant health: GET http://qdrant:6333/healthz
• Check container status for OOM or startup crash.

DEPLOY TYPE: image-copy. Changes require rebuild + up -d.