quickstart Command

Generate example applications demonstrating workflow patterns and agent capabilities

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

directory · path · default: "."

Directory where examples will be created. Most examples create a subdirectory.

fast-agent quickstart workflow ./my-examples

--force · boolean · default: false

Force overwrite existing files without prompting.

fast-agent quickstart workflow --force
fast-agent quickstart researcher -f

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

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

After Creating researcher

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

After Creating data-analysis

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

After Creating tensorzero

1. Navigate to project: cd tensorzero
2. Set up API keys: cp .env.sample .env
3. Start services: docker compose up --build -d
4. 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.

Related Commands

scaffold

Create basic project structure

go

Quickly test examples without files

check

Verify configuration after setup

Workflows Guide

Learn about workflow patterns