Unlock the Power of AI Agents: A Comprehensive Guide to fast-agent

Harness the groundbreaking potential of AI agents and workflows with fast-agent, the first framework boasting complete, end-to-end tested MCP feature support, including sampling. Whether you're using Anthropic (Haiku, Sonnet, Opus) or OpenAI models (gpt-4o/gpt-4.1 family, o1/o3 family), fast-agent empowers you to build sophisticated applications with ease.

Why fast-agent? Build Effective Agents in Minutes

Simple Declarative Syntax: Focus on crafting your prompts and MCP servers, leaving boilerplate behind. Maximize your efficiency and get to the core of building effective agents.
Multi-Modal Mastery: Seamlessly integrate images and PDFs for both Anthropic and OpenAI endpoints. Expand your agent's capabilities beyond text.
Rapid Development & Testing: Passthrough and playback LLMs enable quick iterations on your Python glue-code. Streamline your workflow for faster deployment.
MCP Native: Enjoy native MCP support for enhanced functionality. Keep an eye out for our full documentation site and even more MCP examples coming soon!

Agent Application Development Made Easy

Configuration is Simple: Your agent applications' prompts and configurations are stored in easy-to-manage files, simplifying version control. Spend less time managing files and more time building!
Real-Time Debugging: Interact with individual agents and components during workflow execution to fine-tune and diagnose issues. Achieve optimal performance through precise tuning.
Painless Model Selection: Easily test interactions between models and MCP servers. Experiment with different models to find the perfect fit for your needs.

Quick Start: Your First Steps with fast-agent

Ready to dive in? Let's get you up and running.

Install uv: If you don't have it already, install the uv package manager for Python.
Install fast-agent:
```
uv pip install fast-agent-mcp
```
Set up an example agent:
```
fast-agent setup
```

Run your first agent:

uv run agent.py

Specify a model:
```
uv run agent.py --model=o3-mini.low
```

Explore Workflow Examples:
```
 # Create "building effective agents" examples
fast-agent quickstart workflow
```
Explore our examples, including a Researcher Agent (with Evaluator-Optimizer workflow) and a Data Analysis Agent (similar to ChatGPT), demonstrating MCP Roots support.

Windows Users: Configuration changes may be needed for Filesystem and Docker MCP Servers. Check configuration files for detailed instructions.

Basic Agents: Defining Your AI Powerhouse

Creating an agent is surprisingly straightforward:

@ fast. agent (
    instruction = "Given an object, respond only with an estimate of its size."
)

Interact with your agent:

async with fast. run () as agent:
    moon_size = await agent ( "the moon")
    print ( moon_size)

Or enter interactive chat:

async with fast. run () as agent:
    await agent. interactive ()

Combining Agents and Leveraging MCP Servers

Use the fast-agent quickstart workflow to generate useful examples, like chaining agents. Use uv run workflow/chaining.py to start your example. Fast-agent searches for configuration files in the current directory before traversing up the parent directories.

Create chained workflows with MCP Servers:

@ fast. agent (
    "url_fetcher",
    "Given a URL, provide a complete and comprehensive summary",
    servers = [ "fetch"], # Name of an MCP Server defined in fastagent.config.yaml
)

@ fast. agent (
    "social_media",
    """
    Write a 280 character social media post for any given text.
    Respond only with the post, never use hashtags.
    """,
)

@ fast. chain (
    name = "post_writer",
    sequence = [ "url_fetcher", "social_media"],
)

async def main ():
    async with fast. run () as agent:
        # using chain workflow
        await agent. post_writer ( "http://llmindset.co.uk")

Workflows: Advanced Agent Orchestration

Chain: Sequential Agent Execution

Achieve a more declarative approach by calling agents sequentially.

@ fast. chain (
    "post_writer",
    sequence = [ "url_fetcher", "social_media"]
)

# we can then prompt it directly:
async with fast. run () as agent:
    await agent. post_writer ()

Human Input: Bridging AI and Human Intelligence

Enable agents to request human input for complex tasks or context acquisition.

@ fast. agent (
    instruction = "An AI agent that assists with basic tasks. Request Human Input when needed.",
    human_input = True,
)

await agent ( "print the next number in the sequence")

Parallel: Concurrent Agent Processing

Maximize speed and efficiency by sending messages to multiple agents simultaneously.

@ fast. agent ( "translate_fr", "Translate the text to French")
@ fast. agent ( "translate_de", "Translate the text to German")
@ fast. agent ( "translate_es", "Translate the text to Spanish")

@ fast. parallel (
    name = "translate",
    fan_out = [ "translate_fr", "translate_de", "translate_es"]
)

Evaluator-Optimizer: Iterative Content Refinement

Combine a content generator with an evaluator for continuous improvement of output quality.

@ fast. evaluator_optimizer (
    name = "researcher"
    generator = "web_searcher"
    evaluator = "quality_assurance"
    min_rating = "EXCELLENT"
    max_refinements = 3
)

async with fast. run () as agent:
    await agent. researcher. send ( "produce a report on how to make the perfect espresso")

Router: Intelligent Agent Delegation

Direct messages to the most appropriate agent based on content analysis.

@ fast. router (
    name = "route"
    agents [ "agent1", "agent2", "agent3"]
)

Orchestrator: Complex Task Management

Divide complex tasks among available agents using an LLM to generate a plan.

@ fast. orchestrator (
    name = "orchestrate"
    agents = [ "task1", "task2", "task3"]
)

Agent Features: Fine-Grained Control

Calling Agents

Brevity is Key: Omit name and instruction arguments.
Flexible Access: Use dot notation or dictionary access.

@ fast. agent ( "You are a helpful agent") # Create an agent with a default name.
@ fast. agent ( "greeter", "Respond cheerfully!") # Create an agent with the name "greeter"
moon_size = await agent ( "the moon") # Call the default (first defined agent) with a message

Defining Agents

Control every aspect of your agent's behavior, from its basic instructions to its integration with MCP Servers. See basic definitions for:

Basic Agent
Chain
Parallel
Evaluator-Optimizer
Router
Orchestrator

Multimodal Support: Expanding Your Horizons

Add resources to prompts easily using the inbuilt prompt-server or MCP Types.

summary: str = await agent. with_resource (
    "Summarise this PDF please",
    "mcp_server",
    "resource://fast-agent/sample.pdf",
)

MCP Tool Result Conversion

fast-agent intelligently handles the conversion of ImageResources and EmbeddedResources for MCP Tool Results, enriching your agent's interactions.

MCP Prompts

Utilize apply_prompt(name,arguments) for seamless integration.

Sampling LLMs

Configure your sampling LLMs per Client/Server pair in fastagent.config.yaml.

Secrets File

fast-agent will automatically look for a fastagent.secrets.yaml file in the root folder of your agent definitions.

Dive Deeper

fast-agent builds on the mcp-agent project by Sarmad Qadri.

Contributing

Contributions and PRs are welcome - feel free to raise issues to discuss. Guidelines for contributing and roadmap coming soon. Get in touch!