Skip to main content

​
Overview

The scaffold command initializes a new fast-agent project by creating template files including configuration, secrets, and a basic agent script. This is the recommended way to start a new agent project. 
fast-agent scaffold                # Create files in current directory
fast-agent scaffold --config-dir ./my-project  # Create in specific directory

​
Usage

fast-agent scaffold [OPTIONS]

​
Options

​
--config-dir
string
default:"."
Directory where configuration files will be created. Creates the directory if it doesn’t exist.
fast-agent scaffold --config-dir ./my-agent
fast-agent scaffold -c ./projects/agent1
​
--force
boolean
default:false
Force overwrite existing files without prompting.
fast-agent scaffold --force
fast-agent scaffold -f

​
Created Files

The scaffold command creates the following files:

​
1. fastagent.config.yaml

Main configuration file for agents and MCP servers. 
# Model Configuration
model:
  default: "gpt-4o-mini"  # Default model for all agents

# MCP Server Configuration
mcp:
  servers:
    filesystem:
      command: "npx"
      args:
        - "-y"
        - "@modelcontextprotocol/server-filesystem"
        - "/tmp"  # Allowed directory
    
    fetch:
      command: "uvx"
      args:
        - "mcp-server-fetch"

​
2. fastagent.secrets.yaml

Secure storage for API keys and sensitive configuration. 
# API Keys (NEVER commit this file to version control)
keys:
  anthropic:
    api_key: "sk-ant-..."
  
  openai:
    api_key: "sk-..."
  
  google:
    api_key: "AIza..."
The secrets file should never be committed to version control. Add it to .gitignore.

​
3. agent.py

A minimal agent script demonstrating basic usage. 
import asyncio
from fast_agent import FastAgent

# Create the application
fast = FastAgent("My Agent")

@fast.agent(
    instruction="You are a helpful AI assistant."
)
async def main():
    async with fast.run() as agent:
        await agent.interactive()

if __name__ == "__main__":
    asyncio.run(main())

​
4. pyproject.toml

Minimal project configuration for uv package manager. 
[project]
name = "my-fast-agent"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "fast-agent-mcp",
]

​
5. .gitignore (if needed)

Git ignore file to prevent committing secrets. 
# Secrets
fastagent.secrets.yaml

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python

# Virtual environments
venv/
ENV/
.venv/

# IDE
.vscode/
.idea/
The .gitignore file is only created if one doesn’t already exist in the current directory or any parent directory.

​
Interactive Prompts

The scaffold command provides interactive confirmation: 
$ fast-agent scaffold

fast-agent scaffold

This will create the following files:
  - /path/to/fastagent.config.yaml
  - /path/to/fastagent.secrets.yaml
  - /path/to/agent.py
  - /path/to/pyproject.toml
  - /path/to/.gitignore

Continue? [Y/n]:
If files already exist, you’ll be prompted for each: 
Warning: fastagent.config.yaml already exists. Overwrite? [y/N]:
Use --force to skip all prompts and overwrite existing files.

​
Examples

​
Create in Current Directory

fast-agent scaffold
Creates all template files in the current working directory.

​
Create in New Project Directory

fast-agent scaffold --config-dir ./my-agent
cd my-agent
uv run agent.py
Creates a new directory and initializes the project inside it.

​
Force Overwrite Existing Files

fast-agent scaffold --force
Overwrites existing files without prompting.

​
Scaffold and Configure

fast-agent scaffold --config-dir ./my-agent
cd my-agent

# Edit secrets file to add API keys
vim fastagent.secrets.yaml

# Verify configuration
fast-agent check

# Run the agent
uv run agent.py

​
Next Steps After Scaffolding

​
1. Add API Keys

Edit fastagent.secrets.yaml to add your API keys: 
keys:
  anthropic:
    api_key: "sk-ant-your-key-here"
Or use environment variables: 
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

​
2. Verify Configuration

fast-agent check
This command shows:
  • Detected API keys
  • Configured MCP servers
  • Default model settings
  • Any configuration issues

​
3. Run Your Agent

uv run agent.py
Or specify a different model: 
uv run agent.py --model=sonnet

​
4. Customize Configuration

Edit fastagent.config.yaml to:
  • Add MCP servers
  • Configure model settings
  • Set default behaviors

​
5. Explore Examples

fast-agent quickstart workflow
Generate example agents demonstrating advanced patterns.

​
Configuration File Location

fast-agent searches for configuration files recursively: 
project/
├── fastagent.config.yaml   # Found here
├── fastagent.secrets.yaml
└── agents/
    └── my_agent.py          # Will find configs in parent
This means you can organize agents in subdirectories while maintaining a single configuration at the root.

​
Security Best Practices

1

Never Commit Secrets

Ensure fastagent.secrets.yaml is in .gitignore before committing.
git status  # Verify secrets file is ignored
2

Use Environment Variables

Alternatively, store secrets as environment variables:
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
3

Secure File Permissions

Restrict access to secrets file:
chmod 600 fastagent.secrets.yaml
4

Verify Configuration

Use fast-agent check to verify setup without exposing keys:
fast-agent check

​
Git Ignore Detection

The scaffold command intelligently detects existing .gitignore files:
  • Searches current directory and all parent directories
  • Only creates .gitignore if none exists
  • Warns if existing .gitignore might not cover secrets
Note: Found an existing .gitignore in this or a parent directory.
Ensure it ignores 'fastagent.secrets.yaml' to avoid committing secrets.

​
Template Customization

The scaffold templates are packaged with fast-agent. To customize:
  1. Copy the generated files
  2. Modify them to suit your project
  3. Check them into your repository (except secrets!)

​
Troubleshooting

​
Directory Permission Issues

Directory /path/to/dir does not exist. Create it? [Y/n]:
If you don’t have permission to create the directory, either:
  • Choose a different location
  • Create the directory manually first
  • Run with appropriate permissions

​
Template Loading Errors

Setup template missing: 'agent.py'.
Expected packaged resource at: ...
This indicates a packaging issue. Try: 
pip install --force-reinstall fast-agent-mcp

​
Existing Files Warning

Warning: fastagent.config.yaml already exists. Overwrite? [y/N]:
Options:
  • Press n to skip and keep existing file
  • Press y to overwrite (loses custom changes)
  • Use --force flag to overwrite all files
  • Back up existing files before scaffolding

check

Verify your configuration after scaffolding

go

Quickly test your agent without creating files

quickstart

Generate example agents and workflows

Configuration Guide

Learn about configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us