Configuration

Overview

Fast Agent uses YAML configuration files to manage MCP servers, logging, models, and runtime behavior. Configuration is loaded from fastagent.config.yaml and optional fastagent.secrets.yaml files.

Configuration Files

fastagent.config.yaml

Main configuration file for servers, models, and settings

fastagent.secrets.yaml

Sensitive values like API keys and tokens

File Location

Fast Agent searches for configuration files in this order:

Current working directory
Parent directories (recursive)
Custom path via --config or config_path parameter

The .secrets.yaml file should never be committed to version control. Add it to your .gitignore.

Basic Structure

# fastagent.config.yaml
logger:
  type: file
  level: error
  progress_display: true

mcp:
  targets:
    - name: filesystem
      target: "npx -y @modelcontextprotocol/server-filesystem ."
    - name: fetch
      target: "uvx mcp-server-fetch"

default_model: "sonnet"

Logger Configuration

Control logging behavior and output:

logger:
  type: file              # file, console, or json
  level: error            # debug, info, warning, error
  progress_display: true  # Show progress indicators
  show_chat: true         # Display conversation messages
  show_tools: true        # Show tool call details
  truncate_tools: true    # Truncate long tool outputs
  file_path: logs/app.log # Custom log file path

Logger Types

File Logging
Console Logging
JSON Logging

logger:
  type: file
  level: info
  file_path: logs/fast-agent.log

Writes structured logs to a file. Best for production.

logger:
  type: console
  level: debug

Outputs logs to console. Best for development.

logger:
  type: json
  level: info

Structured JSON logs. Best for log aggregation systems.

Display Options

logger:
  progress_display: false  # Disable progress bars
  show_chat: false         # Hide conversation messages
  show_tools: false        # Hide tool execution details
  truncate_tools: true     # Truncate tool outputs > 1000 chars

Use --quiet flag to disable all progress and logging for cleaner output in scripts.

MCP Server Configuration

Target Shorthand

Simplest way to configure servers:

mcp:
  targets:
    - name: filesystem
      target: "npx -y @modelcontextprotocol/server-filesystem /workspace"
    - name: fetch
      target: "uvx mcp-server-fetch"
    - name: time
      target: "uvx mcp-server-time"

Full Server Configuration

Detailed server settings:

mcp:
  servers:
    filesystem:
      command: "npx"
      args:
        - "-y"
        - "@modelcontextprotocol/server-filesystem"
        - "/workspace"
      env:
        NODE_ENV: production
      roots:
        - uri: "file:///workspace"
          name: "Workspace"
    
    github:
      command: "uvx"
      args: ["mcp-server-github"]
      env:
        GITHUB_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"

HTTP/SSE Servers

Connect to remote servers:

mcp:
  servers:
    remote_api:
      transport: http  # or 'sse'
      url: "https://api.example.com/mcp"
      headers:
        X-API-Version: "v1"
      auth:
        oauth: true
        redirect_port: 3030
        redirect_path: /callback
      ping_interval_seconds: 30
      max_missed_pings: 3

Sampling Configuration

Configure LLM sampling for servers:

mcp:
  servers:
    ai_server:
      command: "uvx"
      args: ["my-mcp-server"]
      sampling:
        model: "haiku"  # Model for server sampling requests

Model Configuration

Default Model

default_model: "sonnet"  # Used when agent doesn't specify

Model Aliases

Fast Agent provides built-in model aliases:

haiku → Claude 3.5 Haiku
sonnet → Claude 3.5 Sonnet
opus → Claude 3 Opus
gpt-4 → GPT-4
gpt-4o → GPT-4 Optimized
o3-mini.low → O3 Mini (low reasoning)
o3-mini.medium → O3 Mini (medium reasoning)
o3-mini.high → O3 Mini (high reasoning)

Custom Model Configuration

models:
  custom_model:
    provider: anthropic
    model_id: claude-3-5-sonnet-20241022
    api_key_env: ANTHROPIC_API_KEY
    max_tokens: 8000
    temperature: 0.7

Provider Configuration

Anthropic
OpenAI
Azure OpenAI
Google

providers:
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"
    base_url: "https://api.anthropic.com"

providers:
  openai:
    api_key: "${OPENAI_API_KEY}"
    organization: "${OPENAI_ORG_ID}"

providers:
  azure_openai:
    api_key: "${AZURE_OPENAI_API_KEY}"
    endpoint: "${AZURE_OPENAI_ENDPOINT}"
    deployment: "gpt-4-deployment"
    api_version: "2024-02-15-preview"

providers:
  google:
    api_key: "${GOOGLE_API_KEY}"
    project_id: "${GOOGLE_PROJECT_ID}"

Shell Execution Configuration

Control shell command execution behavior:

shell_execution:
  timeout_seconds: 90          # Command timeout
  warning_interval_seconds: 30 # Warning display interval
  output_byte_limit: 50000     # Max output size
  enable_read_text_file: true  # Enable file reading
  write_text_file_mode: auto   # auto, on, off, apply_patch

Write Modes

auto: Choose based on model capabilities
on: Always use write_text_file
off: Disable file writing
apply_patch: Use patch-based editing (for advanced models)

Shell access grants agents significant system permissions. Use with caution in production environments.

Skills Configuration

Configure agent skills:

skills:
  directories:
    - ~/.fast-agent/skills
    - ./custom-skills
  
  # Per-agent skills in agent definition

In agent code:

@fast.agent(
    name="skilled",
    instruction="Use available skills. {{agentSkills}}",
    skills=SKILLS_DEFAULT  # Load from configured directories
)

Environment Variables

Use environment variable substitution:

mcp:
  servers:
    github:
      env:
        GITHUB_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"
        API_URL: "${GITHUB_API_URL:-https://api.github.com}"

With default values:

value: "${VAR_NAME:-default_value}"

Secrets Management

Store sensitive values separately:

# fastagent.secrets.yaml
api_keys:
  anthropic: "sk-ant-..."
  openai: "sk-..."
  github: "ghp_..."

Reference in main config:

# fastagent.config.yaml
providers:
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"

Secrets file values automatically override environment variables with the same name.

OpenTelemetry Configuration

Enable observability:

otel:
  enabled: true
  endpoint: "http://localhost:4318"
  service_name: "fast-agent"
  traces:
    enabled: true
    sample_rate: 1.0
  metrics:
    enabled: true

Advanced Options

Connection Persistence

mcp:
  connection_persistence: true  # Reuse connections

Request Parameters

default_request_params:
  temperature: 0.7
  max_tokens: 4096
  top_p: 0.9
  presence_penalty: 0.0
  frequency_penalty: 0.0

Custom Environment Directory

environment_dir: ~/.fast-agent

Or via CLI:

fast-agent go --env ~/.custom-fast-agent

Platform-Specific Configuration

Windows

mcp:
  servers:
    filesystem:
      # Use full node path on Windows
      command: "node"
      args:
        - "C:/Program Files/nodejs/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js"
        - "C:/workspace"

macOS/Linux

mcp:
  servers:
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]

Configuration Validation

Validate your configuration:

fast-agent check

Check specific aspects:

fast-agent check --models    # Validate model configuration
fast-agent check --servers   # Validate MCP servers
fast-agent check --keys      # Check API keys

Complete Example

# fastagent.config.yaml
logger:
  type: file
  level: info
  progress_display: true
  show_chat: true
  show_tools: true

mcp:
  targets:
    - name: filesystem
      target: "npx -y @modelcontextprotocol/server-filesystem ."
    - name: fetch
      target: "uvx mcp-server-fetch"
    - name: time
      target: "uvx mcp-server-time"
  
  servers:
    github:
      command: "uvx"
      args: ["mcp-server-github"]
      env:
        GITHUB_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"
    
    remote_api:
      transport: http
      url: "https://api.example.com/mcp"
      auth:
        oauth: true

default_model: "sonnet"

shell_execution:
  timeout_seconds: 90
  enable_read_text_file: true
  write_text_file_mode: auto

skills:
  directories:
    - ~/.fast-agent/skills

otel:
  enabled: true
  endpoint: "http://localhost:4318"
  service_name: "my-fast-agent-app"

Best Practices

Separate Secrets

Always use fastagent.secrets.yaml for sensitive values. Never commit this file to version control.

Environment Variables

Use environment variable substitution (${VAR}) for deployment-specific values.

Default Values

Provide sensible defaults with ${VAR:-default} syntax for optional configuration.

Validate Configuration

Run fast-agent check before deploying to catch configuration errors early.

Server Performance

Only configure servers you actually use. Each server adds initialization overhead.

Logging Levels

Use error or warning in production, debug only for troubleshooting.

CLI Overrides

Override configuration via command line:

# Override model
fast-agent go --model gpt-4o

# Custom config path
fast-agent go --config /path/to/config.yaml

# Quiet mode (disable logging)
fast-agent go --quiet

# Custom environment directory
fast-agent go --env ~/.custom-fast-agent

# Server mode
fast-agent go --transport http --port 8000

Next Steps

Agents

Learn how to configure agents

MCP Integration

Configure MCP servers in detail

Security

Security best practices

Deployment

Production deployment guide

Get Started

Core Concepts

Agent Types

Workflows

Features

CLI Reference

Examples

​Overview

​Configuration Files

fastagent.config.yaml

fastagent.secrets.yaml

​File Location

​Basic Structure

​Logger Configuration

​Logger Types

​Display Options

​MCP Server Configuration

​Target Shorthand

​Full Server Configuration

​HTTP/SSE Servers

​Sampling Configuration

​Model Configuration

​Default Model

​Model Aliases

​Custom Model Configuration

​Provider Configuration

​Shell Execution Configuration

​Write Modes

​Skills Configuration

​Environment Variables

​Secrets Management

​OpenTelemetry Configuration

​Advanced Options

​Connection Persistence

​Request Parameters

​Custom Environment Directory

​Platform-Specific Configuration

​Windows

​macOS/Linux

​Configuration Validation

​Complete Example

​Best Practices

​CLI Overrides

​Next Steps

Agents

MCP Integration

Security

Deployment

Overview

Configuration Files

File Location

Basic Structure

Logger Configuration

Logger Types

Display Options

MCP Server Configuration

Target Shorthand

Full Server Configuration

HTTP/SSE Servers

Sampling Configuration

Model Configuration

Default Model

Model Aliases

Custom Model Configuration

Provider Configuration

Shell Execution Configuration

Write Modes

Skills Configuration

Environment Variables

Secrets Management

OpenTelemetry Configuration

Advanced Options

Connection Persistence

Request Parameters

Custom Environment Directory

Platform-Specific Configuration

Windows

macOS/Linux

Configuration Validation

Complete Example

Best Practices

CLI Overrides

Next Steps