Skillget

Aware

agent
Security Audit
Warn
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Pass
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Dynamic agent generation for self Adaptive Root Cause Analysis

README.md

AWARE V3 Assess ADK MVP

Python
Google ADK
OpenAI
FastAPI
Pydantic
Typer
SQLite
Pytest

V3-only Assess prototype for AWARE (Parser + Executor), with explicit separation:

  • tools/ for file/data handling
  • templates/ for agent templates to instantiate
  • minimal ADK agents (ParserAgent, ExecutorAgent, dynamic sub-agents)
  • LLM used as the decision engine (Parser and Executor sub-agents)
  • strict analysis filtering on failure_time_range_ts

Setup

python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Create your local .env:

cp .env.example .env
# or use the existing .env and fill in OPENAI_API_KEY

Run

aware parse \
  --query "On 2021-03-04 between 18:30:00 and 19:00:00 checkout timeout" \
  --repo /agentfactory/data/Bank/telemetry/2021_03_04

Run the Executor step from an existing BuildSpec:

aware execute \
  --buildspec-json /path/to/buildspec.json \
  --repo /path/to/repository

Parser + Executor in a single command:

aware assess \
  --query "On 2021-03-04 between 18:30:00 and 19:00:00 checkout timeout" \
  --repo /path/to/repository

Run five incidents directly from an extracted dataset, without writing a query or a problems CSV:

aware batch --dataset nezha --source data/Nezha/Nezha-v0.1 --limit 5
aware batch --dataset openrca_bank --source data/Openrca/Bank-003 --limit 5

The same command accepts openrca_market and openrca_telecom with their
extracted dataset directories. --source may also point to a telemetry folder
inside the selected dataset.

The CLI prints the active provider, model, reasoning and memory settings at
startup. Each batch keeps its catalogue, configuration, results, journals,
reports, graphs, and per-incident SQLite memory under output/batches/<batch-id>/.

Run an existing CSV batch with per-incident PNG causal graphs:

aware batch \
  --problems-csv /path/to/problems.csv \
  --results-csv output/results.csv \
  --graph-dir output/graphs

UI Conversation Live

Start the UI:

aware ui --host 127.0.0.1 --port 8787

Then open:

http://127.0.0.1:8787

In the UI:

  • enter the user query
  • enter the repository path
  • start Run Assess (Parser + Executor)
  • watch the live conversation:
    • parser initialization
    • reasoning / LLM attempt
    • validation
    • correction if invalid
    • Executor run (LogsAgent / TraceAgent / MetricsAgent)
    • final success + full JSON output

Architecture Runtime

1) Agent Templates (Dynamic Instantiation)

Executor sub-agents are defined in:

  • templates/assess_templates.py

Each template defines:

  • agent_name
  • role
  • objective
  • BuildSpec target_field
  • tools to use
  • domain

2) Tools (Data Handling)

Read/window/parse operations are in:

  • tools/telemetry_tools.py

Examples:

  • load_csv_window
  • build_llm_observation_context
  • count_matches
  • sample_matching_lines
  • max_numeric_column

3) Minimal Agents + LLM Decision Engine

ExecutorAgent instantiates sub-agents from the templates.

Each sub-agent:

  • runs tools on its target file
  • builds a compact observation context
  • asks the LLM to decide the findings
  • falls back to a heuristic path if the LLM response is invalid

Implementation:

  • agents/executor_agent.py

Each run is automatically saved in:

  • output/json/<timestamp>_<run_id>.json
  • output/txt/<timestamp>_<run_id>.txt

Knowledge DB (SQLite)

Executor sub-agent information is stored in a SQLite database:

  • table runs
  • table events
  • table task_results
  • table findings

Default DB:

  • sqlite:///output/memory/run-YYYYMMDDTHHMMSSZ-xxxxxxxx.db for standalone runs
  • sqlite:///output/batches/<batch-id>/memory/<run-id>.db for CLI and UI batches

You can override it with:

  • UI: db_url request parameter for API callers
  • CLI: --db-url sqlite:///...

Provider LLM

  • OpenAI-compatible APIs (openai-compatible) and Ollama Cloud (ollama, also accepts ollama-cloud).

Useful .env variables:

  • OPENAI_API_KEY
  • OPENAI_BASE_URL (optional, default: https://api.openai.com/v1)
  • OPENAI_MODEL (optional, default: gpt-5-mini)
  • AWARE_LLM_PROVIDER=ollama to use Ollama Cloud
  • OLLAMA_API_KEY and OLLAMA_MODEL when using Ollama Cloud
  • OLLAMA_BASE_URL (optional, default: https://ollama.com/v1)
  • OLLAMA_TIMEOUT_SECONDS (optional, default: 120)
  • PARSER_MAX_ATTEMPTS
  • AWARE_PARSER_KB_FILE (optional, default: knowledge/parser_buildspec_kb.md)
  • AWARE_EXECUTOR_V3_KB_FILE (optional, default: knowledge/executor_rca_v3_kb.md)
  • EXECUTOR_MAX_AGENTS (default 5: total Executor sub-agents allowed per incident analysis)
  • EXECUTOR_MAX_EXPANSIONS (optional: focused follow-ups after initial domain coverage; default 2, maximum 4)
  • AWARE_ENABLE_REASONING (true|false, default true)
    • false: the LLM is still used, but in fast reasoning mode (more direct prompts)
  • AWARE_ENABLE_MEMORY (true|false, default true)
    • false: disables shared inter-agent memory and SQLite writes for agent results

BuildSpec Note (Multiple Files)

BuildSpec now accepts multiple files per domain:

  • absolute_log_file: list of absolute paths
  • absolute_trace_file: list of absolute paths
  • absolute_metrics_file: list of absolute paths

Knowledge Base (Separate File)

ParserAgent loads its BuildSpec instructions from an external file:

  • knowledge/parser_buildspec_kb.md

This file contains:

  • the task_1..task_7 mapping
  • the BuildSpec contract
  • normalization rules
  • file selection rules (log/trace/metrics)

ExecutorAgent loads its V3 knowledge base:

  • knowledge/executor_rca_v3_kb.md

This file contains:

  • possible components/reasons
  • telemetry file structure (header + timestamp units)
  • analysis rules to avoid false components (for example, file name)

You can point to another file with:

export AWARE_PARSER_KB_FILE=/path/to/my_kb.md

Tests

pytest -q

Citation

If you use this project in your research, please cite:

@inproceedings{sanwouo:hal-05402186,
  TITLE = {{Dynamic Agent Generation for Self-Adaptive Root Cause Analysis}},
  AUTHOR = {Sanwouo, Brell and Temple, Paul and Quinton, Cl{\'e}ment},
  URL = {https://hal.science/hal-05402186},
  BOOKTITLE = {{SEAMS'26 - 21st International Conference on Software Engineering for Adaptive and Self-Managing Systems}},
  ADDRESS = {Rio de Janeiro, Brazil},
  YEAR = {2026},
  MONTH = Apr,
  PDF = {https://hal.science/hal-05402186v1/file/SEAMS26.pdf},
  HAL_ID = {hal-05402186},
  HAL_VERSION = {v1},
}

License

This project is licensed under the MIT License. See LICENSE.

Support

Questions, ideas, or collaborations are welcome. Feel free to reach out: [email protected] | [email protected]

Reviews (0)

No results found