SuperAgentic

Single-orchestrator architecture for simulation systems with data analytics and knowledge graph capabilities.

Philosophy

Single agent. Dynamic reasoning. Tools execute, you decide.

• One orchestrator decides workflow based on query type
• Agent writes all SQL, Python, and Cypher queries
• Tools only execute - no LLM inside tools
• Session persistence with paths passed between tools
• Discovery-first: agent learns domain from tool results

---

Architecture

+------------------------------------------------------------------+
|                          SUPERAGENTIC                             |
|                                                                   |
|  +-------------------------+    +------------------------------+  |
|  |     AGENT SERVER        |    |    DIGITAL TWIN SERVER       |  |
|  |                         |    |                              |  |
|  |  +-------------------+  |    |  +------------------------+  |  |
|  |  |   LangGraph       |  |    |  |   MCP SERVER           |  |  |
|  |  |   Workflow        |  |    |  |   (19 tools)           |  |  |
|  |  +-------------------+  |    |  |                        |  |  |
|  |          |              |    |  |  Discovery (5)         |  |  |
|  |  +-------------------+  |    |  |  Data (5)              |  |  |
|  |  |   Orchestrator    |--+--->|  |  Configuration (5)     |  |  |
|  |  |   (ReAct Agent)   |  |    |  |  Simulation (2)        |  |  |
|  |  +-------------------+  |    |  |  Core (2)              |  |  |
|  |                         |    |  +------------------------+  |  |
|  |  core/                  |    |  digitaltwin/                |  |
|  +-------------------------+    +------------------------------+  |
+------------------------------------------------------------------+

---

Tools

Core (2)

Tool	Purpose
task_completed(summary)	Signal completion (required at end)
ask_user(question)	Request clarification (use sparingly)

Discovery (5)

Tool	Purpose
list_options()	Available controllers, scenarios, faults, profiles
get_sql_schema(file?)	List data files or get specific schema
get_kg_schema()	Knowledge Graph structure
list_session_artifacts()	What's saved in session
get_data_preview(path)	Column names and sample data

Data (5)

Tool	Purpose
get_sql_data(file, sql)	Query data, returns saved_path
execute_analytics(code, input_path?)	Run Python calculations, returns output_path
execute_visualization(code, input_path?)	Create plots, returns plot_path
get_kg_insights(cypher)	Read from Knowledge Graph
store_kg_insights(cypher)	Write to Knowledge Graph

Configuration (5)

Tool	Purpose
configure(config_json)	Unified JSON configuration
configure_controller(type, ...)	Set controller with params
configure_scenario(type, ...)	Set workload scenario
configure_faults(...)	Inject actuator faults
configure_plant(...)	Set plant physics

Simulation (2)

Tool	Purpose
run_simulation(steps?)	Execute simulation
compute_metrics(profile?)	Compute performance metrics

---

Data Flow

get_sql_data ──────> saved_path
                        │
                        v
execute_analytics ──> output_path
                        │
                        v
get_data_preview ──> column names
                        │
                        v
execute_visualization ──> plot_path

Always pass paths between tools. Don't reload data unnecessarily.

---

Workflow Patterns

Data Analysis

get_sql_schema() → get_sql_data(file, sql) → saved_path
execute_analytics(code, input_path) → output_path
get_data_preview(output_path) → column names
execute_visualization(code, input_path) → plot_path
task_completed(findings)

Simulation

list_options()
configure_controller/scenario/faults
run_simulation()
compute_metrics()
task_completed(results)

Follow-Up Query

list_session_artifacts() → find existing paths
get_data_preview(path) → learn columns
execute_visualization(code, input_path) → create plot
task_completed(summary)

---

Session Artifacts

All artifacts saved to digitaltwin/sessions/<session_id>/:

sessions/session_YYYYMMDD_HHMMSS/
├── session.json           # Metadata & event log
├── data_snapshots/        # SQL query results (JSON)
├── analysis_code/         # Generated Python code
├── analysis_data/         # Analytics outputs (JSON)
├── visualization_code/    # Generated plot code
└── visualizations/        # Saved plots (PNG/HTML)

---

Quick Start

# Install dependencies
pip install -r requirements.txt
pip install -r digitaltwin/requirements.txt

# Set API key
export GROQ_API_KEY=your_key

# Run interactive mode
python agent.py

# Single query
python agent.py -q "Analyze temperature patterns"

---

Environment Variables

# Required
GROQ_API_KEY=your_key

# Optional
GROQ_MODEL=model_name
LLM_PROVIDER=groq  # or "openai"
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password

---

Directory Structure

superAgentic/
├── agent.py                # Entry point
├── core/                   # Agent intelligence
│   ├── workflow.py         # LangGraph workflow
│   ├── nodes.py            # ReAct agent node
│   ├── state.py            # State definition
│   ├── context.py          # Event history
│   ├── prompts.py          # System prompt
│   ├── mcp_manager.py      # Tool discovery
│   └── agent_cards.py      # Agent configuration
│
└── digitaltwin/            # Domain implementation
    ├── config/
    │   ├── __init__.py     # Config loader
    │   └── domain_config.yaml
    ├── tools/mcp_server.py # MCP tools
    ├── sessions/           # Session persistence
    ├── data/               # Data files
    ├── simulation/         # Physics engine
    ├── controllers/        # Control algorithms
    ├── runtime/            # Unified runtime
    └── kg/                 # Knowledge Graph

---

Design Principles

Principle	Rationale
Single Orchestrator	Sequential workflows are optimal for single agent
Agent Writes, Tools Execute	All reasoning in orchestrator, tools just run code
Discovery First	Fetch schema/options before writing queries
Preview Before Viz	Get exact column names to avoid empty plots
Session Persistence	Pass paths between tools, avoid context overflow
Follow-Up Awareness	Check artifacts before redoing work