Configuration File

Understanding the fastagent.config.yaml configuration file structure and options

Overview

The fastagent.config.yaml file is the main configuration file for Fast Agent. It controls model selection, logging, MCP server connections, and various runtime behaviors.

Fast Agent searches for configuration files recursively from your current working directory upward, allowing you to maintain project-specific or global configurations.

File Discovery

Fast Agent looks for configuration files in the following order:

1. Project-level config: fastagent.config.yaml in the current directory or any parent directory
2. Environment overlay: <ENVIRONMENT_DIR>/fastagent.config.yaml (defaults to .fast-agent/fastagent.config.yaml)

When both exist, settings from the environment overlay take precedence, with deep-merge semantics for nested configurations.

Use ENVIRONMENT_DIR environment variable to customize the location of your environment directory. This is useful for managing multiple environments or deployment scenarios.

Basic Configuration

Here’s a minimal configuration file:

default_model: gpt-5-mini.low

logger:
  type: file
  level: error

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

Model Configuration

Default Model

default_model · string · default: "gpt-5-mini.low"

The default model for all agents. Can be overridden via --model CLI flag or in agent definitions.

Format: <provider>.<model_name>.<reasoning_effort> or <provider>.<model_name>?reasoning=<value>

Examples:

• openai.o3-mini.low
• anthropic.claude-3-5-sonnet-20241022
• gpt-5-mini.high
• sonnet (using model alias)

Model Aliases

model_aliases · object

Define namespaced model aliases for easier model management across your agent applications.

model_aliases:
  system:
    default: "responses.gpt-5-mini.low"
    plan: "codexplan"
    fast: "claude-haiku-4-5"

Reference aliases using $namespace.alias syntax:

default_model: "$system.default"

Execution Settings

execution_engine · string · default: "asyncio"

Execution engine for the fast-agent application. Currently only asyncio is supported.

environment_dir · string · default: ".fast-agent"

Base directory for fast-agent runtime data including session history, logs, and environment-specific configuration overlays.

session_history · boolean · default: "true"

Persist session history in the environment sessions folder.

session_history_window · integer · default: "20"

Maximum number of sessions to keep in the rolling window.

auto_sampling · boolean · default: "true"

Enable automatic sampling model selection if not explicitly configured for MCP servers.

llm_retries · integer · default: "1"

Number of times to retry transient LLM API errors. Falls back to FAST_AGENT_RETRIES env var.

Logger Configuration

logger.type · string · default: "file"

Logger output type. Options: none, console, file, http

logger.level · string · default: "warning"

Minimum logging level. Options: debug, info, warning, error

logger.progress_display · boolean · default: "true"

Enable or disable the progress display during agent execution.

logger.show_chat · boolean · default: "true"

Show chat User/Assistant messages on the console.

logger.show_tools · boolean · default: "true"

Show MCP server tool calls on the console.

logger.truncate_tools · boolean · default: "true"

Truncate display of long tool calls for better readability.

logger.streaming · string · default: "markdown"

Streaming renderer for assistant responses. Options: markdown, plain, none

logger.message_style · string · default: "a3"

Chat message layout style for console output. Options: classic, a3

logger.path · string · default: "fastagent.jsonl"

Path to log file when logger type is file.

HTTP Logger Transport

For remote logging:

logger.http_endpoint · string

HTTP endpoint for event transport.

logger.http_headers · object

HTTP headers for event transport.

logger.http_timeout · number · default: "5.0"

HTTP timeout in seconds for event transport.

Shell Execution Settings

shell.timeout_seconds · integer · default: "90"

Maximum seconds to wait for command output before terminating. Supports duration strings like 90s, 2m, 1h.

shell.warning_interval_seconds · integer · default: "30"

Show timeout warnings every N seconds during long-running commands.

shell.interactive_use_pty · boolean · default: "true"

Use a PTY (pseudo-terminal) for interactive prompt shell commands, enabling colors and full-screen tools.

shell.output_display_lines · integer · default: "5"

Maximum shell output lines to display (head/tail with ellipsis when truncated). Set to null for no limit.

shell.show_bash · boolean · default: "true"

Show shell command output on the console.

shell.missing_cwd_policy · string · default: "warn"

Policy when an agent shell working directory is missing or invalid. Options: ask, create, warn, error

shell.enable_read_text_file · boolean · default: "true"

Expose a local read_text_file tool (ACP-compatible signature) when shell runtime is enabled.

shell.write_text_file_mode · string · default: "auto"

Control which local file edit tool is exposed. Options:

• auto: Uses apply_patch for GPT-5/Codex models and write_text_file otherwise
• on: Always expose write_text_file
• apply_patch: Always expose apply_patch
• off: Disable local file edit tools

MCP Timeline Display

mcp_timeline.steps · integer · default: "20"

Number of timeline buckets to render in MCP activity visualization.

mcp_timeline.step_seconds · integer · default: "30"

Duration of each timeline bucket in seconds. Supports duration strings like 30s, 2m, 1h.

MCP-UI Support

mcp_ui_output_dir · string · default: ".fast-agent/ui"

Where to write MCP-UI HTML files (relative to CWD if not absolute).

mcp_ui_mode · string · default: "disabled"

MCP-UI output mode. Options: disabled, enabled, auto (auto opens browser)

Skills Configuration

skills.directories · array

List of local directories to search for agent skills.

skills.marketplace_url · string

Single marketplace URL for skill discovery.

skills.marketplace_urls · array

Multiple marketplace URLs for skill discovery.

skills:
  marketplace_urls:
    - "https://github.com/fast-agent-ai/skills"
    - "https://github.com/huggingface/skills"
    - "https://github.com/anthropics/skills"

OpenTelemetry Settings

otel.enabled · boolean · default: "false"

Enable OpenTelemetry tracing for debugging and observability.

otel.service_name · string · default: "fast-agent"

OTEL service name for tracing.

otel.otlp_endpoint · string · default: "http://localhost:4318/v1/traces"

OTLP endpoint for tracing data.

otel.console_debug · boolean · default: "false"

Log spans to console for debugging.

otel.sample_rate · number · default: "1.0"

Sample rate for tracing (1.0 = sample everything).

Environment Variable Substitution

You can reference environment variables in your configuration using ${VAR_NAME} syntax:

mcp:
  targets:
    - name: myserver
      target: "node /path/to/server.js"
      env:
        API_KEY: "${MY_API_KEY}"

Provide default values with ${VAR_NAME:default_value}:

logger:
  level: "${LOG_LEVEL:warning}"

Complete Example

# Default model configuration
default_model: gpt-5-mini.low

# Model aliases for easier management
model_aliases:
  system:
    default: "responses.gpt-5-mini.low"
    fast: "claude-haiku-4-5"
    reasoning: "openai.o3-mini.high"

# Environment directory
environment_dir: ".fast-agent"

# Session history
session_history: true
session_history_window: 20

# Logging configuration
logger:
  type: console
  level: error
  progress_display: true
  show_chat: true
  show_tools: true
  truncate_tools: true
  streaming: markdown

# Shell execution settings
shell:
  timeout_seconds: 90
  warning_interval_seconds: 30
  interactive_use_pty: true
  output_display_lines: 5
  show_bash: true

# MCP Timeline configuration
mcp_timeline:
  steps: 20
  step_seconds: 30

# OpenTelemetry (optional)
otel:
  enabled: false
  service_name: "fast-agent"

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

# Skills configuration
skills:
  marketplace_urls:
    - "https://github.com/fast-agent-ai/skills"

See Also

• MCP Servers - Configure MCP server connections
• Models - Provider-specific model configuration
• Secrets - Secure credential management
• OAuth - OAuth authentication for MCP servers