How evalstate/fast-agent works
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).