# adamstrojek/rust-agentai architecture

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

- Interactive diagram: https://gitdiagram.com/adamstrojek/rust-agentai
- Repository: https://github.com/adamstrojek/rust-agentai

## Overview

##### Project type and purpose
- This is a Rust workspace hosting an open-source library (crate) called **AgentAI**, plus a companion **agentai-macros** crate.

##### File structure
- Top-level files and dirs:
- `.github` – CI/CD workflows (crate publishing, tests).
- `Cargo.toml` – workspace definition pointing at two crates under `crates/`.
- `crates/agentai/` – primary library.
- `crates/agentai-macros/` – procedural macro crate for deriving tooling boilerplate.
- `scripts/` – helper scripts to run examples.
- Inside `crates/agentai/`:
- `src/lib.rs` – public API entry.
- `src/agent.rs` – core `Agent` struct and workflow.
- `src/tool/` – built-in implementations: `buildin.rs`, `web.rs`, `mcp.rs` + `ToolBox` trait.
- `src/structured_output.rs` – parsing and enforcing structured responses.
- `examples/` – demonstration code for various use cases.
- `agentai-macros` provides the `#[toolbox]` macro to auto-generate code to wire tools into agents.

##### README for additional insights
- Confirms that AgentAI uses the GenAI crate under the hood to connect to many LLM providers.
- Highlights feature flags (MCP, macros, built-in tools, web tools).
- Shows sample usage: instantiate `Agent`, call `.run(...)` with model id, prompt, optional toolset.

a. Main components to represent:
- **AgentAI Library**
- Agent Core (the `Agent` struct & workflow manager)
- Structured Output module
- ToolBox Trait (extension point)
- **Tools** (plug-in modules)
- Built-in Tools (e.g., web scraping, string utilities)
- Web Tools (HTTP client wrappers)
- MCP Client (Model-Context-Protocol server connector)
- Custom Tools (user-defined via `#[toolbox]` macro)
- **agentai-macros** crate (codegen for `ToolBox` implementations)
- **GenAI** dependency (abstract LLM provider interface)
- **External LLM Providers** (OpenAI, Anthropic, Gemini, Ollama, etc.)
- **Examples & CI** (demonstrate usage, test workflows)

b. Relationships and interactions:
- **Agent Core** invokes **GenAI** to send prompts to an LLM provider.
- **GenAI** routes to an **External LLM API** (e.g., OpenAI).
- **Agent Core** consults its configured **ToolBox** implementations when a step requires a tool.
- **Tool modules** implement the **ToolBox** trait; autogenerated code from **agentai-macros** wires them in.
- **Structured Output** module validates or deserializes LLM responses into typed Rust structures.
- **Examples** import the `agentai` crate, assemble an `Agent` with tools, and demonstrate end-to-end runs.

c. Architectural patterns and principles:
- **Modular plugin pattern**: Tools implement a `ToolBox` trait, decoupling agent logic from concrete tool implementations.
- **Separation of concerns**:
- Agent management vs. tooling vs. output parsing vs. codegen.
- **Workspace structure** in Cargo: multi-crate design for core vs. macros, keeping procedural macro code separate.
- **Feature flags** drive conditional compilation of tool modules.

d. Technologies, frameworks, libraries:
- Rust/Cargo workspace
- GenAI crate for LLM abstraction
- Tokio (async runtime, implied by usage)
- Serde (for structured output parsing)
- Procedural macros (`agentai-macros`)

##### Detailed capturing of essential elements
- Break out:
- Agent workflow manager
- Structured output parser
- ToolBox trait (interface)
- Each tool module category
- Macros crate (codegen)
- GenAI + external provider cluster
- Feature-flag toggles as optional modules.

- Blue for core crates
- Green for compile-time macros
- Orange for external services
- Gray for examples/CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library Layer
    subgraph "Core Library (AgentAI)"
        style CoreLib fill:#cce5ff,stroke:#444,stroke-width:1px
        PublicAPI["Public API entry\n(lib.rs)"]:::core
        AgentCore["Agent Core\n(agent.rs)"]:::core
        StructuredOutput["Structured Output\n(structured_output.rs)"]:::core
        ToolBox["ToolBox Trait\n(tool/mod.rs)"]:::core
        subgraph "Tool Modules"
            style ToolModules fill:#e6f2ff,stroke:#444,stroke-width:1px
            Buildin["Built-in Tools\n(buildin.rs)"]:::core
            WebTools["Web Tools\n(web.rs)"]:::core
            MCPClient["MCP Client\n(mcp.rs)"]:::core
            CustomTools["Custom Tools\n(#[toolbox] macro)"]:::core
        end
    end

    %% Macros Crate
    subgraph "Compile-time Codegen"
        style MacrosLib fill:#d5f5e3,stroke:#444,stroke-width:1px
        Macros["agentai-macros\n(lib.rs)"]:::macros
    end

    %% Runtime Dependencies
    subgraph "Runtime Dependencies"
        style RuntimeDeps fill:#fdf2e9,stroke:#444,stroke-width:1px
        GenAI["GenAI Crate"]:::external
        ExternalLLM["External LLM Providers\n(OpenAI, Anthropic, etc.)"]:::external
    end

    %% Examples and CI
    subgraph "Examples & CI"
        style ExamplesCI fill:#eeeeee,stroke:#444,stroke-width:1px
        Examples["Examples\n(crates/agentai/examples/)"]:::examples
        CI["CI/CD Workflows\n(.github/workflows/)"]:::examples
        Scripts["Helper Scripts\n(scripts/run-examples.sh)"]:::examples
        Workspace["Workspace Definition\n(Cargo.toml)"]:::examples
    end

    %% Runtime Flows
    PublicAPI -->|"uses"| AgentCore
    AgentCore -->|"parses responses"| StructuredOutput
    AgentCore -->|"calls tools via"| ToolBox
    ToolBox -->|"implements"| Buildin
    ToolBox -->|"implements"| WebTools
    ToolBox -->|"implements"| MCPClient
    ToolBox -->|"implements"| CustomTools
    AgentCore -->|"invokes"| GenAI
    GenAI -->|"routes to"| ExternalLLM
    Examples -->|"imports"| PublicAPI
    Examples -->|"demonstrates"| AgentCore
    CI -->|"tests & publishes"| Workspace
    Scripts -->|"runs"| Examples

    %% Compile-time Flow
    Macros -.->|"generates code for"| CustomTools
    Macros -.->|"wires into"| AgentCore

    %% Click Events
    click PublicAPI "https://github.com/adamstrojek/rust-agentai/blob/master/crates/agentai/src/lib.rs"
    click AgentCore "https://github.com/adamstrojek/rust-agentai/blob/master/crates/agentai/src/agent.rs"
    click StructuredOutput "https://github.com/adamstrojek/rust-agentai/blob/master/crates/agentai/src/structured_output.rs"
    click ToolBox "https://github.com/adamstrojek/rust-agentai/blob/master/crates/agentai/src/tool/mod.rs"
    click Buildin "https://github.com/adamstrojek/rust-agentai/blob/master/crates/agentai/src/tool/buildin.rs"
    click WebTools "https://github.com/adamstrojek/rust-agentai/blob/master/crates/agentai/src/tool/web.rs"
    click MCPClient "https://github.com/adamstrojek/rust-agentai/blob/master/crates/agentai/src/tool/mcp.rs"
    click Macros "https://github.com/adamstrojek/rust-agentai/blob/master/crates/agentai-macros/src/lib.rs"
    click Examples "https://github.com/adamstrojek/rust-agentai/tree/master/crates/agentai/examples/"
    click CI "https://github.com/adamstrojek/rust-agentai/blob/master/.github/workflows/ci.yml"
    click Workspace "https://github.com/adamstrojek/rust-agentai/blob/master/Cargo.toml"
    click Scripts "https://github.com/adamstrojek/rust-agentai/blob/master/scripts/run-examples.sh"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef macros fill:#d5f5e3,stroke:#145A32,color:#145A32;
    classDef external fill:#fdf2e9,stroke:#7F5F14,color:#7F5F14;
    classDef examples fill:#eeeeee,stroke:#6c757d,color:#6c757d;
```
