How It Works#

The Agent Quality Handler is a standalone orchestration service. Detection production and persistence remain external.

Data Flow#

Detection Service ---- writes ----> External storage API
       |
       | MQTT batch-complete event
       v
MQTT broker -----> Agent service FIFO queue
                         |
                         | bounded GET /detections
                         | bounded GET /detections/stats
                         v
            Policy -> Analysis -> Evidence -> Ticketing
                         |
                         v
               In-memory run results
                         |
                         v
             Per-agent JSON output volume

The Compose file starts aqh-agent and a private, unexposed mqtt-broker. A secured external broker can replace the bundled connection through the MQTT_* settings.

Startup and Configuration#

At startup, the service validates runtime values and required assets. Configuration errors terminate startup. Defaults live in defaults; custom config and prompt directories are mounted with USE_CASE_CONFIGS_DIR and USE_CASE_PROMPTS_DIR.

Fallback mode uses configured rules and starts with:

docker compose -f docker/compose.yaml up --build -d

LLM mode sends agent prompts to OVMS and requires both:

LLM_MODE=llm docker compose -f docker/compose.yaml --profile llm up --build -d

The profile adds aqh-ovms and model-download.

Run Lifecycle#

  1. Detection Service publishes a terminal batch event after persistence.

  2. A completed event enters the FIFO queue as queued; an error event becomes a terminal error without reasoning.

  3. One worker changes the next run to running and reads only (start_id, end_id] from STORAGE_SERVICE_URL.

  4. The four agents produce policy, analysis, evidence, and ticket outputs.

  5. The run becomes completed or error, then the MQTT delivery is acknowledged.

POST /agents/run is the manual fallback. It creates its own run ID and uses optional min_id and max_id bounds.

Run state is held in memory and is lost when the agent container restarts. Terminal policy, analysis, evidence, and ticket outputs are additionally written to atomic JSON files in the aqh_agent_output named volume and remain queryable after a container restart. Persisted entries use the same retention limits as the run registry.

Graph failures are explicit: the run status becomes error, while successful partial outputs remain in the result with a structured errors list. Unexpected pipeline exceptions use the same error status and identify the failure as the pipeline agent.

External Integrations#

  • Storage: required; defaults to http://host.docker.internal:5001. Detection Service owns writes and database choice. Agent Quality Handler performs bounded reads only.

  • MQTT: enabled by default; the bundled broker is private. Authentication are supported for an external broker.

  • LLM: optional; fallback mode is the default.

The FIFO queue and run registry are process-local. MQTT acknowledgement waits for terminal state so interrupted event-driven work can be redelivered. Manual queued work is not durable across restarts.

GET /health reports Agent Quality Handler liveness and in-memory run count. It does not probe or guarantee availability of the downstream storage API.