# evalstate/fast-agent architecture

> Architecture diagram of the GitHub repository evalstate/fast-agent, 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/evalstate/fast-agent
- Repository: https://github.com/evalstate/fast-agent

## Overview

Based on our analysis of the provided file tree and README content, this project is a Python framework for building multi-modal agent applications and workflows. It is built on the concepts of “agents” and “workflows” (like chains, parallel execution, evaluators/optimizers, routers, and orchestrators) and integrates with both Anthropic and OpenAI models as well as custom MCP servers. The project is designed as a library—with a strong CLI and interactive components—for rapid prototyping of intelligent agents based on configurable YAML files and code decorators.

##### Main Components
- Agents & Core Framework: Represent the agent definitions (found under src/mcp_agent/agents, src/mcp_agent/core) that use decorators (e.g., @fast.agent, @fast.chain, etc.) to define behavior. Indicate that these components expose methods to generate prompts, interact with human input, and call the agents.
- Workflows: Separate blocks for the different workflow patterns:
- Chain (sequential processing)
- Parallel (fan out/in execution)
- Evaluator-Optimizer (iterative refinement loop)
- Router and Orchestrator workflows (dynamic task delegation and planning)
Under the “Workflows” section (see src/mcp_agent/workflows and its subdirectories).
- MCP Server & Communication: Show the MCP-related modules (located in src/mcp_agent/mcp) that handle external server interaction, resource management (including Filesystem, Sampling servers, etc.), and conversion of Tool Calls between agents.
- CLI and Application Layer: Highlight the CLI tooling (e.g., src/mcp_agent/cli and the __main__.py entry point) that kickstarts the agent applications along with the configuration system (YAML configuration files, secrets, and bootstrap examples located in various directories and examples).
- Logging, Telemetry, and Event Tracking: Include modules from src/mcp_agent/logging and src/mcp_agent/telemetry that manage error handling, tracing, and progress displays.
- Resources & Prompts: Represent the role of external prompt templates, resource files, and configuration files (found throughout examples, schema, and resources directories) which agents use to load instructions and assets.
- Testing & Examples: Note that there is extensive test and example infrastructure (tests folder and examples folder) that serves as both a demonstration of the system’s capabilities and a means of quality assurance.

##### Relationships and Interactions
- Agents interacting with MCP servers and external models. For instance, once an Agent receives a task, it might call a specific MCP Server (depicted as a separate component) that then interacts with OpenAI or Anthropic endpoints.
- For Evaluator-Optimizer, illustrate a loop between the generator agent and evaluator agent.
- Role of the Logging and Telemetry components intercepting events and errors from the various execution paths.

##### Architectural Patterns/Design Principles
- A modular design where each “agent” or “workflow” is defined via decorators—making them pluggable components.
- Separation of concerns by distinguishing between configuration/bootstrapping (YAML files and CLI commands), core logic (agent and workflow execution), and external interactions (MCP server and external API calls).
- Use of dependency injection-like patterns, where configuration files (fastagent.config.yaml, secrets files) are recursively searched and applied to style the behavior of agents.
- Point out how the design supports multimodality (text, images, PDFs) by incorporating resource management components.

##### Incorporate Relevant Technologies, Frameworks, and Tools
- Python and uv package manager for installation and execution.
- GitHub Actions (CI/CD automation as seen in .github/workflows), testing frameworks (unit, integration, end-to-end tests in tests/), and the use of pre-commit configurations.
- YAML-based configuration for both MCP Servers and agent properties.
- External libraries for LLM integrations with Anthropic and OpenAI.
- The decorator pattern heavily used in defining agent behaviors.

- Clearly labeled blocks for:
- Command Line / Application Entry (CLI, __main__.py)
- Core Agent Framework (agents, core libraries)
- Workflows (chain, parallel, evaluator optimizer, router, orchestrator)
- MCP Server & External Interactions
- Logging and Telemetry
- Configuration and Resource Management (YAML configs, secrets, resources)
- User Input → CLI → Agent Framework → MCP Communication → External APIs → Back to Agent Workflow → Logging/Telemetry.
- Annotations or quick notes on key files or directories (e.g., src/mcp_agent for core logic, examples/ for usage demos, tests/ for quality assurance).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("User Input"):::external

    subgraph "CLI and Application Layer"
        B("CLI"):::cli
        C("Main Entry (__main__.py)"):::cli
    end

    A --> B
    B --> C

    subgraph "Core Agent Framework"
        D("Agents"):::core
        E("Core Libraries"):::core
    end

    C --> D
    D --> E

    subgraph "Workflows"
        F1("Evaluator/Optimizer"):::workflow
        F2("Parallel Execution"):::workflow
        F3("Router"):::workflow
        F4("Orchestrator"):::workflow
        F5("LLM Workflow"):::workflow
        F6("Intent Classifier"):::workflow
        F7("Embedding"):::workflow
        F8("Swarm"):::workflow
    end

    E --> F1
    E --> F2
    E --> F3
    E --> F4
    E --> F5
    E --> F6
    E --> F7
    E --> F8

    subgraph "MCP Server & Communication"
        G("MCP Module"):::mcp
        H("MCP Server"):::mcp
    end

    F1 --> G
    F2 --> G
    F3 --> G
    F4 --> G
    F5 --> G
    F6 --> G
    F7 --> G
    F8 --> G

    G --> H

    H --> I("External APIs (Anthropic/OpenAI)"):::external

    I --> E

    subgraph "Logging & Telemetry"
        J("Logging"):::logging
        K("Telemetry"):::logging
    end

    D --- J
    E --- J
    F1 --- K
    F2 --- K
    G --- K
    H --- K

    subgraph "Configuration & Resource Management"
        L("Resources & Prompts"):::config
        M("YAML/Secrets & Bootstrapping"):::config
    end

    B --> L
    C --> M
    M --> D

    subgraph "Testing & Examples"
        N("Testing"):::test
        O("Examples"):::test
    end

    O --> B

    click D "https://github.com/evalstate/fast-agent/tree/main/src/mcp_agent/agents"
    click E "https://github.com/evalstate/fast-agent/tree/main/src/mcp_agent/core"
    click F1 "https://github.com/evalstate/fast-agent/tree/main/src/mcp_agent/workflows/evaluator_optimizer"
    click F2 "https://github.com/evalstate/fast-agent/tree/main/src/mcp_agent/workflows/parallel"
    click F3 "https://github.com/evalstate/fast-agent/tree/main/src/mcp_agent/workflows/router"
    click F4 "https://github.com/evalstate/fast-agent/tree/main/src/mcp_agent/workflows/orchestrator"
    click F5 "https://github.com/evalstate/fast-agent/tree/main/src/mcp_agent/workflows/llm"
    click F6 "https://github.com/evalstate/fast-agent/tree/main/src/mcp_agent/workflows/intent_classifier"
    click F7 "https://github.com/evalstate/fast-agent/tree/main/src/mcp_agent/workflows/embedding"
    click F8 "https://github.com/evalstate/fast-agent/tree/main/src/mcp_agent/workflows/swarm"
    click G "https://github.com/evalstate/fast-agent/tree/main/src/mcp_agent/mcp"
    click H "https://github.com/evalstate/fast-agent/tree/main/src/mcp_agent/mcp_server"
    click B "https://github.com/evalstate/fast-agent/tree/main/src/mcp_agent/cli"
    click C "https://github.com/evalstate/fast-agent/blob/main/src/mcp_agent/cli/__main__.py"
    click J "https://github.com/evalstate/fast-agent/tree/main/src/mcp_agent/logging"
    click K "https://github.com/evalstate/fast-agent/tree/main/src/mcp_agent/telemetry"
    click L "https://github.com/evalstate/fast-agent/tree/main/src/mcp_agent/resources"
    click N "https://github.com/evalstate/fast-agent/tree/main/tests"
    click O "https://github.com/evalstate/fast-agent/tree/main/examples"

    classDef external fill:#f9f,stroke:#333,stroke-width:2px;
    classDef cli fill:#ccf,stroke:#333,stroke-width:2px;
    classDef core fill:#ff9,stroke:#333,stroke-width:2px;
    classDef workflow fill:#cfc,stroke:#333,stroke-width:2px;
    classDef mcp fill:#fc9,stroke:#333,stroke-width:2px;
    classDef logging fill:#fcc,stroke:#333,stroke-width:2px;
    classDef config fill:#cff,stroke:#333,stroke-width:2px;
    classDef test fill:#9cf,stroke:#333,stroke-width:2px;
```
