# xpressai/xai-gpt-agent-toolkit architecture

> Architecture diagram of the GitHub repository xpressai/xai-gpt-agent-toolkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xpressai/xai-gpt-agent-toolkit
- Repository: https://github.com/xpressai/xai-gpt-agent-toolkit

## Overview

##### What this project is (type + purpose)

This repo is a **Xircuits component library** (a plugin-style package) that adds **GPT-agent / BabyAGI-like task management components** to the Xircuits visual workflow environment.

- **Xircuits runtime / orchestrator** executing a **workflow graph (.xircuits)**
- This library’s **custom components** (agents + tools) plugged into that runtime
- **External services** the components rely on (notably **OpenAI API**)
- **State / memory** mechanisms (in-memory scratchpad, task list, SQLite tool)
- Developer/CI packaging concerns (pyproject, requirements, GitHub Actions)

##### How the file structure maps to architecture

From the tree:

- `agent_components.py`

- `examples/babyagi.xircuits`
A **concrete workflow graph** showing how components are wired into an iterative loop (create → prioritize → execute → critique → update tasks → repeat). This is crucial for a “runtime dataflow” view.

- `tests/babyagi_test.xircuits`

- `pyproject.toml`, `requirements.txt`, `__init__.py`

- `.github/workflows/run-workflow-tests.yml`

So, architecturally: **Xircuits (host platform) + this library (plugin components) + external APIs + optional storage + user input**.

##### Xircuits IDE / Workflow Designer
- Produces `.xircuits` workflow definitions.
##### Xircuits Runtime / Engine
- Loads installed component libraries
- Executes the workflow graph node-by-node
- Manages execution context and passing values between nodes

##### This repo’s library (the “plugin”)
**“xai_gpt_agent_toolkit (Xircuits Component Library)”**
Internally, subdivide into:

**Agent Components**
- TaskCreatorAgent
- TaskPrioritizerAgent
- TaskExecutorAgent
- TaskCriticAgent

**Tool/Utility Components**
- ToolRunner
- CreateTaskList
- ScratchPadTool
- PromptUserTool
- BrowserTool
- SqliteTool

##### External dependencies/services
- **OpenAI API** (explicit prerequisite)
- **Web/Internet** (for BrowserTool)
- **SQLite DB file** (for SqliteTool; local file or mounted volume depending on how Xircuits is run)
- **Human User** (for PromptUserTool)

##### State / data structures (important in agent systems)
Call these out explicitly as data stores/flows:
- **Objective / Goal**
- **Task List / Queue** (incomplete tasks + prioritized ordering)
- **Memory / Scratchpad** (summaries, intermediate results)
- **Tool Results / Observations**

##### Loop
- **TaskPrioritizerAgent** reads Task List + Objective → writes updated Task List (reordered)
- **TaskExecutorAgent** pulls next task from Task List, reads Memory/Context → produces “Action/Tool request” (or tool selection)
- **ToolRunner** executes the chosen tool(s)
- may call:
- **OpenAI API** (if tool/agent uses LLM)
- **BrowserTool → Web**
- **SqliteTool → SQLite DB**
- **PromptUserTool → User**
- ToolRunner returns **Results/Observations** → stored into **Memory/Scratchpad**
- **TaskCriticAgent** reviews Results vs Objective → produces critique/feedback → stored in Memory (and/or influences new tasks)
- **TaskCreatorAgent** reads Objective + Results + incomplete tasks → appends new tasks into Task List

This gives you the most “accurate” system picture because it shows: **control flow (loop)** + **data flow (task list/memory)** + **side effects (tools/external calls)**.

- Developer/CI publishes code → installed via `xircuits install gpt-agent-toolkit`
- Xircuits Runtime loads component library (Python package) → components become available in IDE palette

This is important for principal-level accuracy: it clarifies the plugin boundary and runtime loading mechanism.

##### CI/testing view (optional but recommended)
- GitHub Actions (`run-workflow-tests.yml`) runs → executes `tests/babyagi_test.xircuits` → validates component integration and workflow execution

- **Plugin / Component Library architecture**: Xircuits host loads third-party components.
- **Graph-based orchestration**: `.xircuits` is the source of truth for execution order and data passing.
- **Agent loop pattern (BabyAGI-like)**: iterative plan → act → observe → reflect → re-plan.
- **Tool abstraction**: ToolRunner as an execution layer decoupling agents from concrete tools.
- **Stateful agent context**: explicit “Task List” + “Memory/Scratchpad” stores.

##### Concrete diagramming guidance (how to make it “best and most accurate”)

Purpose: boundaries and dependencies.

Runtime calling these components.

The loop with task list + memory as explicit stores.

This layered approach is typically what principal engineers expect: broad boundary + internal structure + runtime behavior.

- “objective + incomplete tasks”
- “prioritized task list”
- “selected tool + tool input”
- “observations/results”
- “memory write/read”
- “API request/response”

Agent systems become unreadable without labeled flows.

##### Control vs data differently
- Or annotate the loop with a “while tasks remain / until objective satisfied” condition.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Level 0: System Context
%% =========================
subgraph "Level 0 — System Context: Xircuits + GPT Agent Toolkit"
direction TB

User["Human User"]:::user

subgraph "Xircuits Host Platform"
direction TB
IDE["Xircuits IDE / Workflow Designer"]:::host
Runtime["Xircuits Runtime / Engine"]:::host
end

subgraph "Installed Plugin Package"
direction TB
Pkg["xai_gpt_agent_toolkit (Xircuits Component Library)"]:::plugin
end

subgraph "External Services & Resources"
direction TB
OpenAI["OpenAI API"]:::external
Web["Web / Internet"]:::external
SQLite[("SQLite DB File")]:::store
end

IDE -->|"authors .xircuits workflow"| Runtime
Runtime -->|"loads installed components"| Pkg

User -->|"provides input"| Runtime
Pkg -->|"LLM requests/responses"| OpenAI
Pkg -->|"browse/search HTTP"| Web
Pkg -->|"read/write"| SQLite
end

%% =========================
%% Level 1: Component Breakdown
%% =========================
subgraph "Level 1 — Component Breakdown: Agents & Tools (from plugin)"
direction TB

Runtime2["Xircuits Runtime / Engine\n(executes workflow nodes)"]:::host

subgraph "Agent Components"
direction TB
Creator["TaskCreatorAgent"]:::component
Prioritizer["TaskPrioritizerAgent"]:::component
Executor["TaskExecutorAgent"]:::component
Critic["TaskCriticAgent"]:::component
end

subgraph "Tool / Utility Components"
direction TB
TaskListInit["CreateTaskList"]:::component
Runner["ToolRunner\n(tool abstraction layer)"]:::component
Scratch["ScratchPadTool"]:::component
Prompt["PromptUserTool"]:::component
Browser["BrowserTool"]:::component
SqliteTool["SqliteTool"]:::component
end

subgraph "State (workflow context stores)"
direction TB
Objective[("Objective / Goal")]:::store
TaskList[("Task List / Queue")]:::store
Memory[("Memory / Scratchpad")]:::store
Obs[("Tool Results / Observations")]:::store
end

Runtime2 -->|"invokes node execute()"| TaskListInit
Runtime2 -->|"invokes node execute()"| Prioritizer
Runtime2 -->|"invokes node execute()"| Executor
Runtime2 -->|"invokes node execute()"| Runner
Runtime2 -->|"invokes node execute()"| Critic
Runtime2 -->|"invokes node execute()"| Creator

TaskListInit -->|"initialize"| TaskList
Scratch -->|"memory read/write"| Memory

Executor -->|"uses objective"| Objective
Executor -->|"reads tasks"| TaskList
Executor -->|"reads context"| Memory
Executor -->|"selected tool + tool input"| Runner

Runner -->|"observations/results"| Obs
Obs -->|"store"| Memory

Critic -->|"reads objective"| Objective
Critic -->|"reviews results"| Obs
Critic -->|"critique/feedback"| Memory

Creator -->|"reads objective"| Objective
Creator -->|"reads results + incomplete tasks"| Obs
Creator -->|"appends new tasks"| TaskList

Runner -->|"may call"| Browser
Runner -->|"may call"| SqliteTool
Runner -->|"may call"| Prompt
Runner -->|"may call LLM"| OpenAI2["OpenAI API"]:::external

Browser -->|"HTTP requests"| Web2["Web / Internet"]:::external
SqliteTool -->|"read/write"| SQLite2[("SQLite DB File")]:::store
Prompt -->|"ask/answer"| User2["Human User"]:::user
end

%% =========================
%% Level 2: Example Workflow (BabyAGI Loop)
%% =========================
subgraph "Level 2 — BabyAGI Example Workflow Execution (examples/babyagi.xircuits)"
direction TB

WF[".xircuits Workflow Graph\n(BabyAGI loop)"]:::workflow

Start["Start / Inputs\n(Objective)"]:::workflow
Init["CreateTaskList"]:::component
P["TaskPrioritizerAgent"]:::component
E["TaskExecutorAgent"]:::component
TR["ToolRunner"]:::component
C["TaskCriticAgent"]:::component
TC["TaskCreatorAgent"]:::component

Obj2[("Objective / Goal")]:::store
TL2[("Task List / Queue")]:::store
Mem2[("Memory / Scratchpad")]:::store
Obs2[("Observations / Results")]:::store

Cond{"While tasks remain\n(or until objective satisfied)"}:::control

WF --> Start
Start -->|"objective"| Obj2
Start --> Init
Init -->|"initial tasks"| TL2

TL2 -->|"task list"| P
Obj2 -->|"objective"| P
P -->|"prioritized tasks"| TL2

TL2 -->|"next task"| E
Mem2 -->|"context"| E
Obj2 -->|"objective"| E
E -->|"tool selection + input"| TR

TR -->|"results"| Obs2
Obs2 -->|"write"| Mem2

Mem2 -->|"context + results"| C
Obs2 -->|"results"| C
Obj2 -->|"objective"| C
C -->|"critique/feedback"| Mem2

Obj2 -->|"objective"| TC
Obs2 -->|"results"| TC
TL2 -->|"incomplete tasks"| TC
TC -->|"append tasks"| TL2

TL2 --> Cond
Cond -.->|"next iteration"| P
Cond -.->|"done"| End["End"]:::workflow

subgraph "Tooling invoked by ToolRunner"
direction TB
TR -->|"LLM call"| OpenAI3["OpenAI API"]:::external
TR -->|"browse"| Browser2["BrowserTool"]:::component
Browser2 -->|"web"| Web3["Web / Internet"]:::external
TR -->|"sqlite"| Sqlite2["SqliteTool"]:::component
Sqlite2 -->|"db file"| SQLite3[("SQLite DB File")]:::store
TR -->|"prompt"| Prompt2["PromptUserTool"]:::component
Prompt2 -->|"human input"| User3["Human User"]:::user
end

end

%% =========================
%% CI / Testing Architecture
%% =========================
subgraph "CI / Testing (optional): Workflow-based validation"
direction TB
GH["GitHub Actions"]:::ci
WfCI["run-workflow-tests.yml"]:::ci
TestWF["tests/babyagi_test.xircuits"]:::test
PkgBuild["Packaging / Build"]:::pkg
PyProj["pyproject.toml"]:::pkg
Reqs["requirements.txt"]:::pkg
Docs["README.md"]:::docs

GH --> WfCI -->|"executes workflow tests"| TestWF
TestWF -->|"loads components"| Pkg
PkgBuild --> PyProj
PkgBuild --> Reqs
Docs -->|"usage + architecture guidance"| Pkg
end

%% =========================
%% Click events (component mappings)
%% =========================
click Pkg "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/__init__.py"
click Creator "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click Prioritizer "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click Executor "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click Critic "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click Runner "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click TaskListInit "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click Scratch "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click Prompt "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click Browser "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click SqliteTool "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"

click Init "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click P "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click E "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click TR "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click C "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click TC "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click Browser2 "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click Sqlite2 "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"
click Prompt2 "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/agent_components.py"

click WF "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/examples/babyagi.xircuits"
click TestWF "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/tests/babyagi_test.xircuits"
click WfCI "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/.github/workflows/run-workflow-tests.yml"
click PyProj "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/pyproject.toml"
click Reqs "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/requirements.txt"
click Docs "https://github.com/xpressai/xai-gpt-agent-toolkit/blob/main/README.md"

%% =========================
%% Styles
%% =========================
classDef host fill:#2563EB,stroke:#0B2A6F,color:#FFFFFF,stroke-width:1px
classDef plugin fill:#16A34A,stroke:#0B4A22,color:#FFFFFF,stroke-width:1px
classDef component fill:#22C55E,stroke:#0B4A22,color:#052e12,stroke-width:1px
classDef workflow fill:#60A5FA,stroke:#1D4ED8,color:#0B1B3A,stroke-width:1px
classDef external fill:#9CA3AF,stroke:#374151,color:#111827,stroke-width:1px
classDef store fill:#F59E0B,stroke:#92400E,color:#111827,stroke-width:1px
classDef user fill:#A78BFA,stroke:#5B21B6,color:#111827,stroke-width:1px
classDef control fill:#F97316,stroke:#9A3412,color:#111827,stroke-width:1px
classDef ci fill:#111827,stroke:#6B7280,color:#FFFFFF,stroke-width:1px
classDef test fill:#06B6D4,stroke:#155E75,color:#042f2e,stroke-width:1px
classDef pkg fill:#F43F5E,stroke:#9F1239,color:#FFFFFF,stroke-width:1px
classDef docs fill:#E5E7EB,stroke:#6B7280,color:#111827,stroke-width:1px
```
