quickstart Command - Fast Agent

Overview

The quickstart command creates ready-to-run example applications that demonstrate various agent patterns, workflows, and integrations. These examples are based on Anthropic’s “Building Effective Agents” paper and showcase practical implementations.

fast-agent quickstart              # Show available examples
fast-agent quickstart workflow     # Create workflow examples
fast-agent quickstart researcher   # Create research agent example

Usage

fast-agent quickstart [EXAMPLE_TYPE] [DIRECTORY] [OPTIONS]

Available Examples

workflow

Demonstrates each pattern from Anthropic’s “Building Effective Agents” paper.

fast-agent quickstart workflow

Creates:

chaining.py - Sequential agent workflow
parallel.py - Parallel agent execution
router.py - Dynamic agent routing
orchestrator.py - Complex task orchestration
evaluator.py - Evaluator-optimizer pattern
human_input.py - Human-in-the-loop workflow
fastagent.config.yaml - Configuration for workflows
short_story.txt - Sample data

Includes:

Chaining workflows for sequential processing
Parallel workflows for concurrent execution
Router pattern for dynamic delegation
Orchestrator pattern for task planning
Evaluator-optimizer for quality iteration
Human input integration

MCP Servers Used:

fetch (for web content)
filesystem (for file operations)

researcher

Research agent with web search and evaluation capabilities.

fast-agent quickstart researcher

Creates:

researcher.py - Basic research agent
researcher-eval.py - Research with quality evaluation
fastagent.config.yaml - Configuration with Brave Search

Features:

Web search integration via Brave API
Evaluator-optimizer workflow
Quality assurance and refinement
Report generation

MCP Servers Used:

brave-search (requires API key)
docker (for code execution)

data-analysis

Data analysis agent demonstrating statistical analysis and visualization.

fast-agent quickstart data-analysis

Creates:

analysis.py - Data analysis agent
fastagent.config.yaml - Configuration with MCP roots
mount-point/ - Sample dataset directory
- WA_Fn-UseC_-HR-Employee-Attrition.csv - HR dataset

Features:

Dataset loading and exploration
Statistical analysis
Visualization generation
MCP roots for file mapping

MCP Servers Used:

filesystem (with mount-point mapping)

state-transfer

Demonstrates state passing between multiple agents.

fast-agent quickstart state-transfer

Creates:

agent_one.py - First agent in sequence
agent_two.py - Second agent receiving state
fastagent.config.yaml - Configuration
fastagent.secrets.yaml.example - Secrets template

Features:

State serialization and transfer
Multi-agent coordination
Context preservation

elicitations

Interactive forms using MCP elicitations feature.

fast-agent quickstart elicitations

Creates:

forms_demo.py - Basic forms example
game_character.py - Character creator with forms
game_character_handler.py - Custom form handler
tool_call.py - Elicitation via tool calls
elicitation_*.py - MCP server implementations
fastagent.config.yaml - Configuration
fastagent.secrets.yaml.example - Secrets template

Features:

Structured data collection
AI-guided form workflows
Custom form handlers
Interactive dialogs

tensorzero

Complete TensorZero integration example with gateway and MCP server.

fast-agent quickstart tensorzero

Creates:

agent.py - Interactive agent
simple_agent.py - Basic TensorZero agent
image_demo.py - Multi-modal functionality
docker-compose.yml - Service orchestration
Makefile - Convenience commands
README.md - Setup instructions
mcp_server/ - Custom MCP server
tensorzero_config/ - TensorZero configuration
demo_images/ - Sample images

Features:

TensorZero gateway integration
Custom MCP server example
Multi-modal support
Docker-based deployment

toad-cards

Example agent and tool cards for Hugging Face Toad integration.

fast-agent quickstart toad-cards

Creates:

.fast-agent/ directory with:
- agent-cards/ - Agent definitions
- tool-cards/ - Tool definitions
- skills/ - Agent skills
- shared/ - Shared context
- hooks/ - Workflow hooks

Features:

ACP expert card
MCP expert card
HF search tool card
Skill examples

Options

Examples

View Available Examples

fast-agent quickstart

Displays a table of all available examples with descriptions.

Create Workflow Examples

fast-agent quickstart workflow
cd workflow
uv run chaining.py

Create Research Agent

fast-agent quickstart researcher
cd researcher

# Set up Brave API key in fastagent.config.yaml
vim fastagent.config.yaml

# Run the researcher
uv run researcher.py

Create Data Analysis Example

fast-agent quickstart data-analysis
cd data-analysis

# Run the analysis
uv run analysis.py

Custom Directory Location

fast-agent quickstart workflow ~/projects/agents
cd ~/projects/agents/workflow
uv run chaining.py

Force Overwrite

fast-agent quickstart workflow --force

Running Examples

After creating examples, run them with uv:

# Run with default model
uv run workflow/chaining.py

# Specify a model
uv run workflow/chaining.py --model=sonnet

# Target specific agent in workflow
uv run workflow/chaining.py --agent post_writer --message "http://example.com"

# Quiet mode for automation
uv run workflow/chaining.py --quiet --message "..."

Workflow Patterns Explained

Chaining

Sequential execution where output of one agent feeds into the next.

@fast.agent("url_fetcher", "Fetch and summarize URL", servers=["fetch"])
@fast.agent("social_media", "Write a 280 character post")
@fast.chain("post_writer", sequence=["url_fetcher", "social_media"])

Parallel

Multiple agents process the same input concurrently, with optional aggregation.

@fast.agent("translate_fr", "Translate to French")
@fast.agent("translate_de", "Translate to German")
@fast.parallel("translate", fan_out=["translate_fr", "translate_de"])

Router

Intelligent routing to the most appropriate agent based on input.

@fast.router(
    name="route",
    agents=["math_solver", "code_helper", "general_assistant"]
)

Orchestrator

Planning and coordinating complex tasks across multiple agents.

@fast.orchestrator(
    name="orchestrate",
    agents=["researcher", "writer", "editor"],
    plan_type="full"
)

Evaluator-Optimizer

Iterative refinement with quality evaluation.

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

Configuration After Creation

API Keys

Many examples require API keys. Add them to the created fastagent.secrets.yaml:

keys:
  anthropic:
    api_key: "sk-ant-..."
  openai:
    api_key: "sk-..."
  brave:
    api_key: "BSA..."  # For researcher example

MCP Servers

The created fastagent.config.yaml includes necessary MCP server configurations:

mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]
    
    filesystem:
      command: "npx"
      args:
        - "-y"
        - "@modelcontextprotocol/server-filesystem"
        - "/tmp"

Windows Considerations

For Windows users, some MCP servers require path adjustments:

mcp:
  servers:
    filesystem:
      command: "npx"
      args:
        - "-y"
        - "@modelcontextprotocol/server-filesystem"
        - "C:\\Temp"  # Windows path

Next Steps by Example

After Creating workflow

Review chaining.py for basic workflow pattern
Explore other examples:
- parallel.py - Run agents concurrently
- router.py - Dynamic agent selection
- evaluator.py - Quality evaluation
Run with: uv run <example>.py
Try different models: --model=<model>

After Creating researcher

Get Brave API key from https://brave.com/search/api/
Add key to fastagent.secrets.yaml
Try basic version: uv run researcher.py
Try eval version: uv run researcher-eval.py

After Creating data-analysis

Run: uv run analysis.py
Dataset location: mount-point/WA_Fn-UseC_-HR-Employee-Attrition.csv
On Windows: Edit fastagent.config.yaml mount-point path

After Creating tensorzero

Navigate to project: cd tensorzero
Set up API keys: cp .env.sample .env
Start services: docker compose up --build -d
Run agent: make agent or uv run agent.py

File Structure

Typical structure after quickstart:

my-project/
├── workflow/                    # Created by quickstart workflow
│   ├── chaining.py
│   ├── parallel.py
│   ├── router.py
│   ├── orchestrator.py
│   ├── evaluator.py
│   ├── human_input.py
│   ├── fastagent.config.yaml
│   └── short_story.txt
├── researcher/                  # Created by quickstart researcher
│   ├── researcher.py
│   ├── researcher-eval.py
│   └── fastagent.config.yaml
└── data-analysis/              # Created by quickstart data-analysis
    ├── analysis.py
    ├── fastagent.config.yaml
    └── mount-point/
        └── WA_Fn-UseC_-HR-Employee-Attrition.csv

Troubleshooting

Missing Dependencies

# Install uv if not available
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install example dependencies
uv pip install -r requirements.txt

MCP Server Issues

# Verify MCP server installation
npx -y @modelcontextprotocol/server-filesystem --help
uvx mcp-server-fetch --help

# Check configuration
fast-agent check

API Key Errors

# Verify keys are set
fast-agent check

# Set via environment as alternative
export ANTHROPIC_API_KEY="sk-ant-..."
export BRAVE_API_KEY="BSA..."

File Exists Warning

Skipping chaining.py (already exists)

Use --force to overwrite or manually remove existing files.

scaffold

Create basic project structure

go

Quickly test examples without files

check

Verify configuration after setup

Workflows Guide

Learn about workflow patterns

Get Started

Core Concepts

Agent Types

Workflows

Features

CLI Reference

Configuration

Examples

​Overview

​Usage

​Available Examples

​workflow

​researcher

​data-analysis

​state-transfer

​elicitations

​tensorzero

​toad-cards

​Options

​Examples

​View Available Examples

​Create Workflow Examples

​Create Research Agent

​Create Data Analysis Example

​Custom Directory Location

​Force Overwrite

​Running Examples

​Workflow Patterns Explained

​Chaining

​Parallel

​Router

​Orchestrator

​Evaluator-Optimizer

​Configuration After Creation

​API Keys

​MCP Servers

​Windows Considerations

​Next Steps by Example

​After Creating workflow

​After Creating researcher

​After Creating data-analysis

​After Creating tensorzero

​File Structure

​Troubleshooting

​Missing Dependencies

​MCP Server Issues

​API Key Errors

​File Exists Warning

​Related Commands

scaffold

go

check

Workflows Guide

Build docs developers (and LLMs) love

Overview

Usage

Available Examples

workflow

researcher

data-analysis

state-transfer

elicitations

tensorzero

toad-cards

Options

Examples

View Available Examples

Create Workflow Examples

Create Research Agent

Create Data Analysis Example

Custom Directory Location

Force Overwrite

Running Examples

Workflow Patterns Explained

Chaining

Parallel

Router

Orchestrator

Evaluator-Optimizer

Configuration After Creation

API Keys

MCP Servers

Windows Considerations

Next Steps by Example

After Creating workflow

After Creating researcher

After Creating data-analysis

After Creating tensorzero

File Structure

Troubleshooting

Missing Dependencies

MCP Server Issues

API Key Errors

File Exists Warning

Related Commands