# agnt-gg/agnt architecture

> Architecture diagram of the GitHub repository agnt-gg/agnt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agnt-gg/agnt
- Repository: https://github.com/agnt-gg/agnt

## Overview

##### Project Type & Purpose
- AGNT is a modular, graph-based workflow orchestrator that leverages both JavaScript and Python implementations. It is designed to define and execute autonomous agent tasks as workflows, where every tool is encapsulated as a node in a network.
- The system handles workflow definitions (via JSON files), graph orchestration via various components (AGNT, FIRE, PLUG, VIBE, SPRK), and a web interface (in the JS version) for managing and visualizing workflows.

##### File Structure
- Notice the directories “agnt-js” and “agnt-py” – these represent parallel implementations of the same architecture in different languages.
- Within each implementation, you have clearly defined subdirectories:
– “orchestrator”: Contains core modules (AGNT, FIRE, PLUG, SPARK/SPRK, VIBE) responsible for managing execution, tasks, parameter resolution, condition evaluation, and dynamic workflow routing.
– “tools”: Includes individual tool implementations that are executed as part of the workflow.
– “workflows”: Houses JSON files that define complete workflows, representing the graph of nodes (tools) and edges (execution flow).
– “schema-cache” and “schema-patterns”: Hold JSON schema definitions that ensure correct structure for workflows and tools.
– “public” and “server.js” in agnt-js indicate an HTTP front-end interface, providing a UI for interaction with workflows.
- The root-level also includes utilities and configuration files – these underscore the emphasis on modularity and extensibility.

a. • Core Components to Include:
- Workflow Definition Module: Represented by the JSON workflow files (e.g., in “agnt-js/workflows”, “agnt-py/workflows”).
- Orchestrator Core (AGNT): The central engine that validates and instantiates workflows.
- Execution Engines/Modules: FIRE (to execute trigger functions), PLUG (for parameter resolution), VIBE (for condition evaluations), and SPRK (for dynamic tool/workflow generation).
- Tools: Multiple individual tool modules (found in “tools” directories) for specific operations.
- Schema Management: Schema-cache/schema-patterns directories ensuring the workflows and tools adhere to required contracts.
- Web UI / API: For the JavaScript implementation, include a front-facing layer (server.js, public folder) that allows users to view, create, and run workflows.
- Execution Summary: A component that logs, tracks, and saves execution traces (summaries and cache directories).
b. • Relationships and Interactions:
- That each node (tool) communicates its output back to the orchestrator for aggregation, tracking, and passing as input to the next stage.
- In the Python lane, emphasize similar async calls to the orchestrator.
c. • Architectural Patterns & Design Principles:
- Modular and Extensible: Highlight that each component is loosely coupled but interoperates via defined JSON schemas and API calls.
- Graph-based Workflow: Emphasize nodes (tools) and edges (dependencies and data flow) in the workflow graph.
- Asynchronous Processing: Point out that both implementations support asynchronous operations (especially in Python and modern Node.js environments).
d. • Technologies and Frameworks:
- For JavaScript: Node.js environment, ES modules, and a web server with an HTML/CSS-based UI.
- For Python: Python 3.8+ asynchronous programming constructs.
- JSON-based schemas for workflow and tool validation.
- Optional: Tools for automated testing or orchestration visualizations if available.

##### Final Recommendations
- Use a high-level view combined with a more detailed inset that zooms in on the graph-based workflow execution process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% JavaScript Implementation Layer
    subgraph "JavaScript Implementation"
        WJ1["Workflow Definitions (JS)"]:::input
        SC1["Schema Management (JS)"]:::schema
        AGNT1["AGNT Core (JS)"]:::orchestration
        FIRE1["FIRE (JS)"]:::orchestration
        PLUG1["PLUG (JS)"]:::orchestration
        VIBE1["VIBE (JS)"]:::orchestration
        SPRK1["SPRK (JS)"]:::orchestration
        TOOLS1["Tool Modules (JS)"]:::tool
        UI1["Web UI/API"]:::ui
        SUM1["Execution Summary"]:::summary
    end

    %% Python Implementation Layer
    subgraph "Python Implementation"
        WP1["Workflow Definitions (PY)"]:::input
        SC2["Schema Management (PY)"]:::schema
        AGNT2["AGNT Core (PY)"]:::orchestration
        FIRE2["FIRE (PY)"]:::orchestration
        PLUG2["PLUG (PY)"]:::orchestration
        VIBE2["VIBE (PY)"]:::orchestration
        SPRK2["SPRK (PY)"]:::orchestration
        TOOLS2["Tool Modules (PY)"]:::tool
    end

    %% JavaScript Data Flow
    WJ1 -->|"triggers"| AGNT1
    AGNT1 -->|"validates"| SC1
    AGNT1 -->|"executes"| FIRE1
    AGNT1 -->|"executes"| PLUG1
    AGNT1 -->|"executes"| VIBE1
    AGNT1 -->|"executes"| SPRK1
    FIRE1 -->|"returns"| AGNT1
    PLUG1 -->|"returns"| AGNT1
    VIBE1 -->|"returns"| AGNT1
    SPRK1 -->|"returns"| AGNT1
    AGNT1 -->|"delegates"| TOOLS1
    TOOLS1 -->|"feedback"| AGNT1
    UI1 -->|"requests"| AGNT1
    AGNT1 -->|"logs"| SUM1

    %% Python Data Flow
    WP1 -->|"triggers"| AGNT2
    AGNT2 -->|"validates"| SC2
    AGNT2 -->|"executes"| FIRE2
    AGNT2 -->|"executes"| PLUG2
    AGNT2 -->|"executes"| VIBE2
    AGNT2 -->|"executes"| SPRK2
    FIRE2 -->|"returns"| AGNT2
    PLUG2 -->|"returns"| AGNT2
    VIBE2 -->|"returns"| AGNT2
    SPRK2 -->|"returns"| AGNT2
    AGNT2 -->|"delegates"| TOOLS2
    TOOLS2 -->|"feedback"| AGNT2

    %% Click Events for JavaScript
    click WJ1 "https://github.com/agnt-gg/agnt/tree/main/agnt-js/workflows"
    click AGNT1 "https://github.com/agnt-gg/agnt/blob/main/agnt-js/orchestrator/AGNT.js"
    click FIRE1 "https://github.com/agnt-gg/agnt/blob/main/agnt-js/orchestrator/FIRE.js"
    click PLUG1 "https://github.com/agnt-gg/agnt/blob/main/agnt-js/orchestrator/PLUG.js"
    click VIBE1 "https://github.com/agnt-gg/agnt/blob/main/agnt-js/orchestrator/VIBE.js"
    click SPRK1 "https://github.com/agnt-gg/agnt/blob/main/agnt-js/orchestrator/SPRK.js"
    click TOOLS1 "https://github.com/agnt-gg/agnt/tree/main/agnt-js/tools"
    click SC1 "https://github.com/agnt-gg/agnt/tree/main/agnt-js/schema-cache"
    click UI1 "https://github.com/agnt-gg/agnt/blob/main/agnt-js/server.js"
    click SUM1 "https://github.com/agnt-gg/agnt/tree/main/agnt-js/summaries"

    %% Click Events for Python
    click WP1 "https://github.com/agnt-gg/agnt/tree/main/agnt-py/workflows"
    click AGNT2 "https://github.com/agnt-gg/agnt/blob/main/agnt-py/orchestrator/AGNT.py"
    click FIRE2 "https://github.com/agnt-gg/agnt/blob/main/agnt-py/orchestrator/FIRE.py"
    click PLUG2 "https://github.com/agnt-gg/agnt/blob/main/agnt-py/orchestrator/PLUG.py"
    click VIBE2 "https://github.com/agnt-gg/agnt/blob/main/agnt-py/orchestrator/VIBE.py"
    click SPRK2 "https://github.com/agnt-gg/agnt/blob/main/agnt-py/orchestrator/SPRK.py"
    click TOOLS2 "https://github.com/agnt-gg/agnt/tree/main/agnt-py/tools"
    click SC2 "https://github.com/agnt-gg/agnt/tree/main/agnt-py/schema-patterns"

    %% Styles
    classDef input fill:#D5F5E3,stroke:#000,stroke-width:2px;
    classDef orchestration fill:#AED6F1,stroke:#000,stroke-width:2px;
    classDef tool fill:#E8DAEF,stroke:#000,stroke-width:2px;
    classDef schema fill:#F5CBA7,stroke:#000,stroke-width:2px;
    classDef ui fill:#F9E79F,stroke:#000,stroke-width:2px;
    classDef summary fill:#FADBD8,stroke:#000,stroke-width:2px;
```
