Configuration Reference

fast-agent can be configured through the fast-agent.yaml file. Place it in the active fast-agent home (by default ./.fast-agent) or pass an explicit path with --config-path (-c). For sensitive information, you can use fast-agent.secrets.yaml with the same structure - values from both files will be merged, with secrets taking precedence.

Configuration can also be provided through environment variables, with the naming pattern SECTION__SUBSECTION__PROPERTY (note the double underscores).

Configuration File Location

fast-agent loads configuration from the active fast-agent home first, then from the current working directory if no home config exists. The home is selected by --home, --workspace <path>/.fast-agent, FAST_AGENT_HOME, or the default ./.fast-agent. You can also specify a configuration file path or URI with the --config-path (-c) command-line argument.

General Settings

# Default model for all agents
default_model: "gpt-5-mini?reasoning=low"  # Format: provider.model_name with optional query params

# Optional namespaced model references (configured under model_references and
# used via exact tokens like $system.fast)
model_references:
  system:
    fast: "gpt-5-mini?reasoning=low"
    plan: "claude-sonnet-4-6"

# Number of times to retry transient LLM API errors (falls back to FAST_AGENT_RETRIES env)
llm_retries: 2

# Execution engine (only asyncio is currently supported)
execution_engine: "asyncio"

# Base directory for fast-agent runtime data
home: ".fast-agent"

# Session history storage (on/off)
session_history: true

# Session history rolling window (number of recent sessions to keep)
session_history_window: 20

# Persist git repository provenance in session snapshots and trace exports
git_aware: false

History compaction defaults are generated from fast_agent.config.CompactionSettings:

compaction:
  auto:         true  # automatically compact when the threshold is crossed
  # threshold:    null  # context-window fraction that triggers compaction; unset: model default
  keep_turns:   2     # recent turns kept verbatim after compaction
  strategy:     'auto' # auto: provider-native where supported; client: always summarize
  # prompt:       null  # built-in prompt; set inline text or a relative file path

Relative compaction.prompt file paths are resolved from the loaded config file's directory. If FAST_AGENT_HOME points at a home config, the path is relative to that home config file; it is not resolved from the process current working directory.

llm_retries defaults to 2 and is the preferred way to control retry attempts. If unset in config, the FAST_AGENT_RETRIES environment variable is used as a fallback.

Namespaced Model References

Use model_references to create exact-token model references such as $system.fast and reuse them in default_model, --model, environment overrides, and agent card model fields.

default_model: "$system.fast"

model_references:
  system:
    fast: "gpt-5-mini?reasoning=low"
    plan: "claude-sonnet-4-6"

Notes:

• Model reference tokens must match this form exactly: $<namespace>.<key> (for example $system.fast).
• Model references can point to other model references (recursive expansion is supported with cycle detection).
• If a model reference cannot be resolved, fast-agent logs a warning and falls back to the next lower-precedence configured model source (explicit model → CLI → config → environment). This warning is emitted through the normal logger/event pipeline and may be surfaced in UIs.
• If no model resolves, interactive startup opens the picker. Unattended runs must supply an AgentCard/decorator model, --model, FAST_AGENT_MODEL, or default_model.
• If a selected model is not a model reference token (doesn't start with $), normal validation behavior applies.

Model Overlays

Model overlays are home-local named model entries stored under the active home.

Files are loaded from:

• model-overlays/*.yaml
• model-overlays.secrets.yaml

Use overlays when you want a short local token such as qwen-local to carry:

• a provider
• a wire model name
• a custom base_url
• auth settings
• request defaults
• local metadata for picker/display use

Example overlay manifest:

name: qwen-local
provider: openresponses
model: unsloth/Qwen3.5-9B-GGUF
connection:
  base_url: http://localhost:8080/v1
  auth: none
defaults:
  temperature: 0.8
  top_p: 0.95
  max_tokens: 2048
metadata:
  context_window: 75264
  max_output_tokens: 2048
picker:
  label: Qwen local
  description: Imported from llama.cpp
  current: true

Once present, the overlay name can be used anywhere a model string is accepted:

default_model: "qwen-local"

or:

model_references:
  system:
    fast: "qwen-local"

For a complete guide, see Model Overlays.

Execution Environment Configuration

Use this resource when creating or editing fast-agent.yaml named execution environments. The field reference below is generated from the Pydantic config models so schema changes are reflected here.

Top-Level Shape

default_environment: local

environments:
  local:
    type: local
    cwd: .

  ubuntu:
    type: docker
    image: ubuntu:24.04
    cwd: /workspace
    mounts:
      - source: .
        target: /workspace
        mode: rw

  hf-gpu:
    type: huggingface
    image: python:3.12
    flavor: cpu-basic
    cwd: /workspace
    volume_mounts:
      - hf://buckets/username/my-bucket:/workspace:rw
      - hf://datasets/username/reference-data:/data:ro

Rules

• local is always available implicitly.
• default_environment must name local or a configured environment.
• Environment names starting with _ are reserved.
• Environment specs reject unknown fields.
• Docker specs require exactly one of image or container.
• Docker mount sources are resolved against the workspace root; use mounts, not volume flags in docker_args.
• Hugging Face volume_mounts use hf://[models|datasets|spaces|buckets]/namespace/name[/path]:/mount/path[:ro|:rw]; omitted type defaults to models.
• Hugging Face Sandbox pooling (SandboxPool) is not exposed in fast-agent.yaml; use a custom environment adapter for pooled sandbox lifecycle.
• Put tokens/secrets in fast-agent.secrets.yaml or environment variables.

Field Reference

Local Environment

Docker Environment

Docker Mount

Hugging Face Environment

Hugging Face Volume Mount

Hugging Face Bucket Mount Shorthand

Custom Environment

Runtime Environment Variables

• FAST_AGENT_DISABLE_UV_LOOP=1: Disable uvloop even if installed (non-Windows). By default, uvloop is used when available. session_history controls whether fast-agent persists session metadata and history files in the environment sessions folder (default .fast-agent/sessions). session_history_window limits how many recent sessions are kept; older sessions are pruned when new sessions are created. The same window is used for session resume completions and ordinal selection (e.g. /session resume 1).

git_aware adds best-effort git provenance to persisted sessions and exported traces. When enabled and the session working directory is inside a git repository, fast-agent records the repository root, commit, capture time, branch, dirty state, GitHub owner/repo when available, and a sanitized origin remote URL. The first captured state is kept as started; later saves update current.

home sets the base folder for local fast-agent data such as skills, sessions, and permission history. You can also override this per run with fast-agent --home <path>, or choose a workspace with fast-agent --workspace <path> and let the home default to <workspace>/.fast-agent. Use --no-home for ephemeral runs that intentionally skip home-based side effects.

History Compaction

When a conversation grows large, fast-agent can compact older turns into a single checkpoint summary, freeing context while preserving the work done so far. The summary is produced by the agent's own model and inserted into history as a clearly-marked message (shown as compacted in /history); the most recent turns are kept verbatim.

You can also compact on demand:

• /compact — compact now, showing the before/after context usage.
• /compact <instructions> — steer the summary (for example, /compact focus on the database migration).
• /compact preview — show what would be kept and dropped, without calling the model.
• /compact prompt — print the active summarization prompt.

The pre-compaction history is archived to a compacted_*.json file in the session directory so the original conversation is never lost.

Model Providers

Anthropic

anthropic:
  api_key: "your_anthropic_key"  # Optional; can also use ANTHROPIC_API_KEY or Anthropic SDK credentials
  base_url: "https://api.anthropic.com/v1"  # Optional, only include to override
  reasoning: auto  # Adaptive models: auto/low/medium/high/max. Budget models: integer tokens or off.
  structured_output_mode: auto  # auto (default), json, or tool_use
  web_search:
    enabled: false
    max_uses: 3  # Optional, must be > 0
    allowed_domains: ["example.com"]  # Optional; mutually exclusive with blocked_domains
    # blocked_domains: ["tracking.example"]
    user_location:  # Optional
      type: approximate
      city: "London"
      country: "UK"
      region: "England"
      timezone: "Europe/London"
  web_fetch:
    enabled: false
    citations_enabled: false
    max_uses: 3  # Optional, must be > 0
    max_content_tokens: 4096  # Optional, must be > 0
    allowed_domains: ["example.com"]  # Optional; mutually exclusive with blocked_domains
    # blocked_domains: ["ads.example"]

Anthropic authentication uses this precedence:

1. anthropic.api_key in fast-agent config/secrets.
2. ANTHROPIC_API_KEY.
3. Anthropic SDK credential discovery, including ANTHROPIC_AUTH_TOKEN, Anthropic profiles (ANTHROPIC_PROFILE / ANTHROPIC_CONFIG_DIR / active profile), and workload identity federation environment variables.

This means api_key is no longer required when Anthropic SDK credentials are available.

Anthropic models fall into three groups:

• No reasoning support: reasoning is ignored with a warning.
• Budget-based thinking (older models): defaults to a 1024 token budget. Set reasoning to a budget integer or disable with "0"/off/false. You can also pass low/medium/high/max, which map to preset budgets.
• Adaptive thinking (e.g. claude-opus-4-6, claude-opus-4-8, claude-opus-5): defaults to auto (provider-chosen). Use effort levels (low/medium/high/max, plus xhigh where advertised) to set output_config.effort. Fixed thinking budgets are deprecated for these models; Opus 4.7+ additionally supports task_budget for model-visible agent-loop budgets.

For budget models, the reasoning budget must be lower than max_tokens (fast-agent raises max_tokens if needed).

Structured outputs default to JSON schema for newer models that support the structured-outputs-2025-11-13 feature and are compatible with reasoning. Older models fall back to tool_use structured output, which is not compatible with reasoning (fast-agent disables reasoning for tool-forced structured outputs). Override with structured_output_mode: json or structured_output_mode: tool_use as needed.

Legacy thinking_enabled and thinking_budget_tokens settings are deprecated and ignored.

Anthropic built-in web tools can also be toggled per run in the model string:

• claude-opus-4-6?web_search=on&web_fetch=on
• sonnet?web_search=off

Allowed values: on/off (also accepts true/false, 1/0).

OpenAI

openai:
  api_key: "your_openai_key"  # Can also use OPENAI_API_KEY env var
  base_url: "https://api.openai.com/v1"  # Optional, only include to override
  reasoning: "medium"  # Optional unified reasoning setting where supported

For OpenAI Responses API models, use the responses section below. The Responses-family web_search block is also supported for openresponses, codexresponses, and metaai provider sections.

Responses-family providers can also be toggled per run in the model string:

• responses.gpt-5?web_search=on
• openresponses.openai/gpt-oss-120b:groq?web_search=on
• codexresponses.gpt-5.3-codex?web_search=off
• metaai.muse-spark-1.3?web_search=on

Allowed values: on/off (also accepts true/false, 1/0).

Responses (OpenAI Responses API)

responses:
  api_key: "your_openai_key"  # Can also use OPENAI_API_KEY env var
  base_url: "https://api.openai.com/v1"  # Optional, only include to override
  reasoning: "medium"  # Optional default reasoning setting
  text_verbosity: "medium"  # Optional: low | medium | high
  transport: "sse"  # sse | websocket | auto
  web_search:
    enabled: false
    tool_type: web_search  # web_search | web_search_preview
    search_context_size: medium  # Optional: low | medium | high
    allowed_domains: ["openai.com"]  # Optional, max 100 domains
    external_web_access: false  # Optional, only for tool_type=web_search
    user_location:  # Optional
      type: approximate
      city: "Minneapolis"
      region: "Minnesota"
      country: "US"
      timezone: "America/Chicago"

web_search can be toggled per run in the model string:

• responses.gpt-5-mini?web_search=on
• responses.gpt-5-mini?web_search=off
• responses.gpt-5.3-codex?transport=ws

Websocket transport is available for all models used through the responses provider. When websocket transport is active, follow-up turns may be sent incrementally for efficiency.

Azure OpenAI

# Option 1: Using resource_name and api_key (standard method)
azure:
  api_key: "your_azure_openai_key"  # Required unless using DefaultAzureCredential
  resource_name: "your-resource-name"  # Resource name in Azure
  azure_deployment: "deployment-name"  # Required - deployment name from Azure
  api_version: "2024-10-21"  # Optional API version
  default_headers:
    Ocp-Apim-Subscription-Key: "${AZURE_OPENAI_API_KEY}"
  # Do NOT include base_url if you use resource_name

# Option 2: Using base_url and api_key (custom endpoints or sovereign clouds)
# azure:
#   api_key: "your_azure_openai_key"
#   base_url: "https://your-endpoint.openai.azure.com/"
#   azure_deployment: "deployment-name"
#   api_version: "2024-10-21"
#   default_headers:
#     Ocp-Apim-Subscription-Key: "${AZURE_OPENAI_API_KEY}"
#   # Do NOT include resource_name if you use base_url

# Option 3: Using DefaultAzureCredential (for managed identity, Azure CLI, etc.)
# azure:
#   use_default_azure_credential: true
#   base_url: "https://your-endpoint.openai.azure.com/"
#   azure_deployment: "deployment-name"
#   api_version: "2024-10-21"
#   default_headers:
#     Ocp-Apim-Subscription-Key: "${AZURE_OPENAI_API_KEY}"
#   # Do NOT include api_key or resource_name in this mode

Important configuration notes: - Use either resource_name or base_url, not both. - When using DefaultAzureCredential, do NOT include api_key or resource_name (the azure-identity package must be installed). - When using base_url, do NOT include resource_name. - When using resource_name, do NOT include base_url. - default_headers can be used with any option to pass API management headers. - The model string format is azure.deployment-name

DeepSeek

deepseek:
  api_key: "your_deepseek_key"  # Can also use DEEPSEEK_API_KEY env var
  base_url: "https://api.deepseek.com"  # Optional, only include to override

See the DeepSeek provider guide for model selection, reasoning, web search, structured output, and stateless Responses behavior.

Google

google:
  api_key: "your_google_key"  # Can also use GOOGLE_API_KEY env var
  base_url: "https://generativelanguage.googleapis.com/v1beta/openai"  # Optional

xAI (Grok)

xai:
  api_key: "your_xai_key"  # Can also use XAI_API_KEY env var
  base_url: "https://api.x.ai/v1"  # Optional, defaults to this value
  # image_upload_mode: inline  # Default: public_url
  # image_upload_ttl_seconds: 86400  # 1 hour to 30 days

MetaAI

metaai:
  api_key: "${META_AI_API_KEY}"
  base_url: "https://api.meta.ai/v1"  # Optional, defaults to this value
  default_model: "muse-spark-1.3"
  web_search:
    enabled: false
    search_context_size: medium  # Optional: low | medium | high
    user_location:  # Optional approximate locale bias
      type: approximate
      country: "GB"

MetaAI search grounding can also be toggled per run with metaai.muse-spark-1.3?web_search=on. See the MetaAI provider guide for supported media, interactive toggles, and search-result behavior.

Groq

groq:
  api_key: "your_groq_key"  # Can also use GROQ_API_KEY env var
  base_url: "https://api.groq.com/openai/v1"  # Optional, defaults to this value

Aliyun (Qwen via OpenAI-compatible API)

aliyun:
  api_key: "your_aliyun_key"  # Provide via secrets/env as appropriate
  base_url: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"  # Optional, defaults to this value

Hugging Face (Inference Providers)

hf:
  api_key: "${HF_TOKEN}"  # Can also use HF_TOKEN env var
  base_url: "https://router.huggingface.co/v1"  # Optional
  default_provider: null  # Optional: groq, fireworks-ai, cerebras, etc.

Generic (Ollama, etc.)

generic:
  api_key: "ollama"  # Default for Ollama, change as needed
  base_url: "http://localhost:11434/v1"  # Default for Ollama

OpenRouter

openrouter:
  api_key: "your_openrouter_key"  # Can also use OPENROUTER_API_KEY env var
  base_url: "https://openrouter.ai/api/v1"  # Optional, only include to override

TensorZero

tensorzero:
  base_url: "http://localhost:3000"  # Optional, only include to override

See the TensorZero Quick Start and the TensorZero Gateway Deployment Guide for more information on how to deploy the TensorZero Gateway.

AWS Bedrock

bedrock:
  region: "us-east-1"  # Required - AWS region where Bedrock is available
  profile: "default"   # Optional - AWS profile to use (defaults to "default")

AWS Bedrock uses standard AWS authentication through the boto3 credential provider chain. You can configure credentials using:

• AWS CLI: Run aws configure to set up credentials (AWS SSO recommended for local development)
• Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN (for temporary credentials)
• IAM roles: Use IAM roles when running on EC2 or other AWS services
• AWS profiles: Use named profiles with the profile setting or AWS_PROFILE environment variable

Additional environment variables: - AWS_REGION or AWS_DEFAULT_REGION: Override the region setting - AWS_PROFILE: Override the profile setting

The model string format is bedrock.model-id (e.g., bedrock.amazon.nova-lite-v1:0)

MCP Server Configuration

MCP Servers are defined under the mcp.servers section:

mcp.servers contains preconfigured aliases. AgentCards may additionally declare runtime targets via mcp_connect; those are resolved at startup and do not need to be prelisted here.

The MCP section contains server defaults, client behavior, diagnostics, and named servers:

mcp:
  defaults:
    protocol_mode: auto
    reconnect_on_disconnect: true
    include_instructions: true
  client:
    auto_sampling: true
  diagnostics:
    enabled: true
    timeline:
      steps: 20
      step_seconds: 30
  servers:
    githubcopilot:
      target: "https://api.githubcopilot.com/mcp/"
      load_on_start: false
      auth:
        oauth: true

    filesystem:
      target: "@modelcontextprotocol/server-filesystem /workspace"
      load_on_start: false

The mcp.servers map key is the canonical server name used by agents and workflows. Omit name from the server block; if present, it must match the map key.

Each server may use either target shorthand or expanded source fields:

mcp:
  servers:
    shorthand:
      target: "@modelcontextprotocol/server-filesystem /workspace"
      load_on_start: false
    expanded:
      transport: http
      url: "https://demo.hf.space"

target cannot be combined with the expanded source fields transport, url, command, args, or connector_id. Non-source settings such as headers, auth, protocol_mode, and load_on_start may accompany it.

target must be a pure target string. Do not embed fast-agent CLI flags (--auth, --oauth, --timeout, etc.) inside target; use structured fields like headers and auth instead.

mcp.defaults applies protocol_mode, reconnect_on_disconnect, and include_instructions only when omitted from a server. mcp.client contains client behavior such as auto_sampling. mcp.diagnostics controls diagnostics collection and timeline display.

See Migrate MCP configuration for the legacy path migration command.

Provider-managed remote MCP

Use management: provider when you want the model provider to execute a remote MCP server directly instead of having fast-agent connect to it as a local MCP client.

mcp:
  servers:
    stripe:
      management: provider
      transport: "http"
      url: "https://mcp.stripe.com"
      access_token: "${STRIPE_TOKEN}"
      description: "Stripe official MCP"
      defer_loading: true  # OpenAI Responses hint; ignored by Anthropic

Provider-managed remote MCP is supported only for:

• anthropic
• responses

It is not available for codexresponses, Codex OAuth aliases, openresponses, openai, google, anthropic-vertex, or other providers.

Rules for provider-managed remote MCP servers:

• Must be URL-based remote servers (http or sse)
• url is required unless using an OpenAI Responses connector
• Use access_token for bearer auth when needed
• command, args, env, cwd, headers, auth, and roots are not supported
• defer_loading is only used by the OpenAI responses provider

When a provider-managed server is attached to an agent/card:

• tools.<server_name> must use exact tool names only
• wildcard tool filters are not supported
• prompts.<server_name> and resources.<server_name> filters are not supported

mcp:
  servers:
    stripe:
      management: provider
      transport: "http"
      url: "https://mcp.stripe.com"
      access_token: "${STRIPE_TOKEN}"

agents:
  billing:
    model: "responses.gpt-5-mini"
    servers: ["stripe"]
    tools:
      stripe: ["customers_create", "customers_retrieve"]

OpenAI Responses connectors

The OpenAI responses provider can also manage OpenAI hosted connectors. Use connector_id instead of url:

mcp:
  servers:
    dropbox:
      management: provider
      connector_id: connector_dropbox
      access_token: "${DROPBOX_OAUTH_ACCESS_TOKEN}"
      description: "Dropbox connector"
      defer_loading: true

Connector rules:

• Supported only by the OpenAI responses provider
• Set exactly one of url or connector_id
• connector_id must be one of the connector IDs supported by the installed OpenAI SDK
• access_token is required
• Omit transport, url, command, args, env, cwd, headers, auth, and roots
• defer_loading: true enables server-side lazy tool loading

mcp:
  servers:
    # Example stdio server
    server_name:
      transport: "stdio"  # "stdio", "sse", or "http"
      command: "npx"  # Command to execute
      args: ["@package/server-name"]  # Command arguments as array
      read_timeout_seconds: 60  # Optional timeout in seconds
      # HTTP transport only:
      # http_timeout_seconds: 30        # Overall HTTP timeout (seconds). If unset, uses MCP SDK default (30s).
      # http_read_timeout_seconds: 300  # Per-read timeout for streaming (seconds). If unset, uses MCP SDK default (300s).
      ping_interval_seconds: 30  # Optional ping interval; <=0 disables (default: 30)
      max_missed_pings: 3  # Optional; consecutive missed pings before marking failed (default: 3)
      env:  # Optional environment variables
        ENV_VAR1: "value1"
        ENV_VAR2: "value2"
      sampling:  # Optional sampling settings
        model: "gpt-5-mini"  # Model to use for sampling requests

    # Example Stremable HTTP server
    streamable_http__server:
      transport: "http"
      url: "http://localhost:8000/mcp"
      read_transport_sse_timeout_seconds: 300  # Timeout for HTTP/SSE connections
      http_timeout_seconds: 300  # Overall HTTP timeout (StreamableHTTP)
      http_read_timeout_seconds: 300  # Read timeout (StreamableHTTP)
      headers:  # Optional HTTP headers
        Authorization: "Bearer token"
      auth:  # Optional authentication
        oauth: true
      include_instructions: true  # Whether to include instructions in {{serverInstructions}}

    # Example SSE server
    sse_server:
      transport: "sse"
      url: "http://localhost:8000/sse"
      read_transport_sse_timeout_seconds: 300  # Timeout for SSE connections
      headers:  # Optional HTTP headers
        Authorization: "Bearer token"
      auth:  # Optional authentication
        oauth: true


    # Server with roots
    file_server:
      transport: "stdio"
      command: "command"
      args: ["arguments"]
      roots:  # Root directories accessible to this server
        - uri: "file:///path/to/dir"  # Must start with file://
          name: "Optional Name"  # Optional display name for the root
          server_uri_alias: "file:///server/path"  # Optional, for consistent paths

Ping settings are optional and configured per server. ping_interval_seconds defaults to 30 seconds (<=0 disables), and max_missed_pings defaults to 3.

Skills Configuration

Configure skill directories and marketplace registries:

skills:
  # Override default skill directories
  directories:
    - ".fast-agent/skills"
    - "~/my-custom-skills"

  # Available skill registries (marketplaces)
  marketplace_urls:
    - "https://github.com/fast-agent-ai/skills"
    - "https://github.com/huggingface/skills"
    - "https://github.com/anthropics/skills"

See Agent Skills for more information on using skills.

Command Plugin Configuration

Enable installed command plugins and configure plugin registries:

plugins:
  enabled:
    - agent-finder
    - edit-assistant
  marketplace_urls:
    - "https://github.com/fast-agent-ai/card-packs"
  config:
    agent-finder:
      page_size: 10
      prompt_when_multiple: true

Plugin registries configure direct plugin operations such as fast-agent plugins add and fast-agent plugins update. Required plugins for a card pack are resolved from the marketplace that supplied that pack, not necessarily from these plugin registry settings. If you publish a custom card pack that declares plugins.required, include matching command_plugins entries in the same marketplace file as the pack.

Plugin-specific settings belong under plugins.config.<plugin-name>. The shape inside each plugin's namespace is owned by that plugin.

Global plugins are layered separately from the active fast-agent home. When FAST_AGENT_HOME is set, plugin names enabled in $FAST_AGENT_HOME/fast-agent.yaml are merged with the active project config, including when --home <dir> selects a different active fast-agent home. If FAST_AGENT_HOME is not set, ~/.fast-agent/fast-agent.yaml is used as the global plugin layer when it exists. Only the global file's plugins block is layered in: global plugins load from the global plugins/ directory, and project-enabled plugins load from the active fast-agent home's plugins/ directory. Project plugin commands override global commands with the same name, and inline commands: entries override both. See Command Plugins for install, update, and card-pack usage.

OpenTelemetry Settings

otel:
  enabled: false  # Enable or disable OpenTelemetry
  service_name: "fast-agent"  # Service name for tracing
  otlp_endpoint: "http://localhost:4318/v1/traces"  # OTLP endpoint for tracing
  console_debug: false  # Log spans to console
  sample_rate: 1.0  # Sample rate (0.0-1.0)

Logging Settings

logger:
  type: "file"  # "none", "console", "file", or "http"
  level: "warning"  # "debug", "info", "warning", or "error"
  progress_display: true  # Enable/disable progress display
  path: "fast-agent-log.jsonl"  # Explicit path to log file (for "file" type)
  batch_size: 100  # Events to accumulate before processing
  flush_interval: 2.0  # Flush interval in seconds
  max_queue_size: 2048  # Maximum queue size for events

  # HTTP logger settings
  http_endpoint: "https://logging.example.com"  # Endpoint for HTTP logger
  http_headers:  # Headers for HTTP logger
    Authorization: "Bearer token"
  http_timeout: 5.0  # Timeout for HTTP logger requests

  # Console display options
  show_chat: true  # Show chat messages on console
  show_tools: true  # Show MCP Server tool calls on console
  truncate_tools: true  # Truncate long tool calls in display
  enable_markup: true # Disable if outputs conflict with rich library markup
  enable_prompt_marks: true # Emit OSC 133 prompt marks in supported terminals
  streaming: "markdown"  # "markdown", "plain", or "none"

When logger.path is omitted, file logging writes to <fast-agent-home>/fast-agent-log.jsonl. Under --no-home, it falls back to <current-working-directory>/fast-agent-log.jsonl. Explicit relative paths continue to resolve from the process current working directory.

Responses websocket failures emit an error-level structured event, Responses websocket attempt failed, through this logging path, including failures recovered by the transport's bounded reconnect. File logging persists these events as JSONL even at level: "error"; they do not depend on a completed assistant response or ATIF export. Logging disabled with type: "none" does not persist them.

The fast-agent.responses-websocket-failure/v2 payload includes an allowlisted error_code (null when absent, unknown for unrecognized codes), stream_started, connection ages at request start and failure in seconds (null when unknown), reuse status, and reconnect_eligible. Ages use the connection manager's monotonic clock. Eligibility describes the existing single transport reconnect only, not outer provider retries; websocket_attempt / websocket_max_attempts distinguish that bound from the provider call, attempt, and max_attempts counters. When a stream ends without a completion event, v2 adds how it ended (otherwise null):

• close_kind: one of close_frame_received, no_close_frame (the peer dropped the connection without a WebSocket close frame), close_code, no_close_code or unknown.
• close_code: the numeric close code, if any.
• events_seen: the number of frames received.
• last_event_types: up to the last five frame types. Responses event names are kept, Copilot's untyped header frame is recorded as headers, and anything else becomes other or untyped.
• seconds_since_request and seconds_since_last_frame.

The diagnostic contains no error text, headers, URLs, request/response bodies, prompts, or credentials. It does not change retry or timeout policy.

The raised error's message is more detailed but is not persisted by this event. It lists the recent frames, including header names and *request-id* header values that match a strict identifier pattern, which are useful when contacting the provider. The exception also exposes last_frame, the raw last frame (at most 16 KiB), for programmatic inspection. It is never logged.

MCP Diagnostics Settings

mcp:
  diagnostics:
    enabled: true
    timeline:
      steps: 20
      step_seconds: 30  # seconds per bucket; strings like "30s" and "2m" also work

Skills Settings

skills:
  directory: null  # Override the default skills directory

Shell Execution Settings

shell_execution:
  tool_profile: auto  # Grok uses shell + process; other models use bash + process
  timeout_seconds: 90
  warning_interval_seconds: 30
  interactive_use_pty: true  # Use PTY for interactive prompt shell commands
  output_byte_limit: 16000  # Explicit value; omit for catalog/default selection, null for auto
  retain_truncated_output: true
  retained_output_max_bytes: 2097152  # Per shell process
  durable_output_max_bytes: 2097152  # Per persistent stdout/stderr/combined log
  retained_output_temp_directory: null  # Optional parent directory
  process_poll_max_wait_seconds: 260  # Default keeps prompt caches warm; range: 1–3600
  foreground_auto_await_max_seconds: 30  # Total runtime; range: 0–3600; 0 disables
  managed_process_poll_history_folding: auto  # auto | on | off

tool_profile controls the model-facing contract only. The default auto profile selects the catalog contract for the active model. Grok models expose shell(command, working_directory?, background?, timeout?) plus unified process(...); other models retain bash(...) plus unified process(...). Use process(action="list") to list retained managed processes in creation order; process_id is required for status, wait, and stop.

Set tool_profile explicitly to minimal_process, grok_shell, or native to override automatic selection, including after runtime model switches. native remains a compatibility escape hatch for the legacy execute, poll_process, and terminate_process schemas. All profiles use the same managed-process runtime.

When output_byte_limit is omitted, a model-catalog override is used when available, followed by the global 16,000-byte default. An explicit positive value always wins. Set the field to null to use automatic sizing from model output-token metadata.

When retain_truncated_output is enabled, fast-agent creates a private session-scoped directory and lazily writes a 0600 file only when a shell result exceeds its model-facing preview. The truncation notice includes the temporary path so the model can inspect selected ranges or search the complete output. Each process is limited by retained_output_max_bytes; retained files are removed when the shell runtime closes.

durable_output_max_bytes separately caps each persistent process stdout.log, stderr.log, and combined output.log. Fast-agent continues draining child pipes after a log reaches the cap and reports the excess as dropped output, preventing verbose persistent commands from filling the filesystem or blocking on full pipes.

foreground_auto_await_max_seconds is the maximum total foreground runtime, measured from shell process start, during which a finite command remains in its original shell tool call. Commands retain the initial no-output and total-runtime yield checks (10 and 30 seconds by default); after either check, the runtime waits only for the remaining total budget. If the command finishes before the deadline, its final result is returned without a model turn spent scheduling a process wait. Reaching the deadline returns the live, session-scoped process to the model and does not stop it. Explicit background commands and explicit hard timeouts are unchanged. Set the value to 0 to return live foreground processes at the initial yield boundary.

The 30-second default matches the initial total-runtime yield and keeps longer commands model-interruptible. It still lets shorter commands finish in their original shell call without a model turn spent scheduling a process wait.

process_poll_max_wait_seconds caps a single model-initiated managed-process wait. The 260-second default returns each wait while provider prompt caches are still warm (a hung or long process then costs a cached poll rather than blocking the model for up to an hour); longer work is followed with repeated waits, which fold in history when quiet. Model requests above the ceiling are clamped. Unless the ceiling is set explicitly, a longer model wait period (catalogue, overlay or poll_period) raises it; an explicit ceiling is authoritative and a longer poll_period is rejected instead of being silently reduced.

See Foreground auto-await and outer-budget-aware process waits for the model-interruptibility tradeoff, external-deadline integration gap, proposed budget-aware semantics, telemetry, and acceptance tests.

managed_process_poll_history_folding controls whether repetitive quiet managed-process polling exchanges are collapsed before the next model call:

• auto enables folding only for models whose metadata marks the behavior as validated.
• on forces folding for every model.
• off preserves every poll exchange in model history.

LLM Retries

llm_retries: 2

Example Full Configuration

default_model: "gpt-5-mini?reasoning=low"

# Model provider settings
anthropic:
  api_key: API_KEY

responses:
  api_key: API_KEY
  reasoning: "high"

# MCP servers
mcp:
  servers:
    fetch:
      transport: "stdio"
      command: "uvx"
      args: ["mcp-server-fetch"]

    filesys:
      transport: "stdio"
      command: "uvx"
      args: ["mcp-server-filesystem"]
      roots:
        - uri: "file://./data"
          name: "Data Directory"

# Logging configuration
logger:
  type: "file"
  level: "info"
  path: "logs/fast-agent-log.jsonl"

Environment Variables

All configuration options can be set via environment variables using a nested delimiter:

ANTHROPIC__API_KEY=your_key
OPENAI__API_KEY=your_key
LOGGER__LEVEL=debug

Environment variables take precedence over values in the configuration files. For nested arrays or complex structures, use the YAML configuration file.

The fast-agent.yaml file supports referencing environment variables inline using the ${ENV_VAR} syntax. When the configuration is loaded, any value specified as ${ENV_VAR} will be automatically replaced with the value of the corresponding environment variable. This allows you to securely inject sensitive or environment-specific values into your configuration files without hardcoding them.

For example:

openai:
  api_key: "${OPENAI_API_KEY}"

In this example, the api_key value will be set to the value of the OPENAI_API_KEY environment variable at runtime.