Skip to main content

agent.yml – Configuration Reference

Complete reference for all agent.yml configuration options.

Table of Contents​

  1. Minimal Configuration
  2. Complete Example
  3. LLM Configuration
  4. System Prompt Configuration
  5. MCP Servers
  6. Tool Confirmation
  7. Storage Configuration
  8. Session Configuration
  9. Telemetry Configuration
  10. Logger Configuration
  11. Plugins
  12. Internal Tools
  13. Internal Resources
  14. Agent Identity / A2A
  15. Agent ID
  16. Dynamic Changes
  17. Starter Prompts
  18. Greeting
  19. Global Preferences

Minimal Configuration​

systemPrompt: |
  You are a helpful AI assistant.

llm:
  provider: anthropic
  model: claude-sonnet-4-5-20250929
  apiKey: $ANTHROPIC_API_KEY

Complete Example​

# LLM
llm:
  provider: openai
  model: gpt-5
  apiKey: $OPENAI_API_KEY
  maxIterations: 50
  router: vercel

# System Prompt
systemPrompt:
  contributors:
    - id: primary
      type: static
      priority: 0
      content: |
        You are a helpful AI assistant with access to tools.
    - id: dateTime
      type: dynamic
      priority: 10
      source: dateTime
    - id: memories
      type: memory
      priority: 40
      enabled: true
      options:
        includeTags: true
        limit: 10

# MCP Servers
mcpServers:
  filesystem:
    type: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
  playwright:
    type: stdio
    command: npx
    args: ["-y", "@playwright/mcp@latest"]

# Tool Confirmation
toolConfirmation:
  mode: manual
  timeout: 120000
  allowedToolsStorage: storage
  toolPolicies:
    alwaysAllow:
      - internal--ask_user
      - mcp--filesystem--read_file

# Storage
storage:
  cache:
    type: in-memory
  database:
    type: sqlite
  blob:
    type: local
    maxBlobSize: 52428800
    maxTotalSize: 1073741824
    cleanupAfterDays: 30

# Sessions
sessions:
  maxSessions: 100
  sessionTTL: 3600000

# Telemetry
telemetry:
  enabled: true
  serviceName: my-dexto-agent
  tracerName: dexto-tracer
  export:
    type: otlp
    protocol: http
    endpoint: http://localhost:4318/v1/traces

# Logger
logger:
  level: info
  transports:
    - type: console
      colorize: true
    - type: file
      path: ./logs/agent.log
      maxSize: 10485760
      maxFiles: 5

# Plugins
plugins:
  contentPolicy:
    priority: 10
    blocking: true
    enabled: true
  responseSanitizer:
    priority: 900
    blocking: false
    enabled: true

# Internal Tools
internalTools:
  - ask_user
  - read_file
  - write_file
  - edit_file
  - glob_files
  - grep_content
  - bash_exec

# Internal Resources
internalResources:
  resources:
    - type: filesystem
      paths: ["."]
      maxFiles: 50
      maxDepth: 3
      includeExtensions: [".txt", ".md", ".json", ".yaml", ".js", ".ts", ".py"]
    - type: blob

# Agent Identity / A2A
agentCard:
  name: "MyAgent"
  description: "A comprehensive AI assistant"
  url: "https://agent.example.com"
  version: "1.0.0"
  provider:
    organization: "My Organization"
    url: "https://example.com"
  capabilities:
    streaming: true
    pushNotifications: false

# Starter Prompts
starterPrompts:
  - id: quick-start
    title: "📚 Quick Start"
    prompt: "Show me what you can do!"
    category: learning
    priority: 9

# Greeting
greeting: "Hello! I'm ready to help you today."

LLM Configuration​

Guides

For configuration details and examples, see LLM Configuration.

For supported providers and models, see Supported LLM Providers.

Language model provider and settings.

Schema​

llm:
  provider: string              # Required: openai | anthropic | google | groq | openai-compatible
  model: string                 # Required
  apiKey: string                # Required: API key or $ENV_VAR
  maxIterations: number         # Optional, default: 50
  router: string                # Optional: vercel | in-built, default: vercel
  baseURL: string               # Optional
  maxInputTokens: number        # Optional
  maxOutputTokens: number       # Optional
  temperature: number           # Optional: 0.0-1.0

Examples​

# OpenAI
llm:
  provider: openai
  model: gpt-5
  apiKey: $OPENAI_API_KEY

# Anthropic
llm:
  provider: anthropic
  model: claude-sonnet-4-5-20250929
  apiKey: $ANTHROPIC_API_KEY

# OpenAI-Compatible
llm:
  provider: openai-compatible
  model: custom-model-name
  apiKey: $CUSTOM_API_KEY
  baseURL: https://api.custom-provider.com/v1

System Prompt Configuration​

Guides

See System Prompt Guide and Memory Configuration for detailed explanations.

Agent behavior and personality.

Schema​

# Simple string
systemPrompt: |
  Your instructions

# Structured contributors
systemPrompt:
  contributors:
    - id: string                  # Required, unique
      type: static | dynamic | file | memory
      priority: number            # Lower runs first
      enabled: boolean            # Optional, default: true

Contributor Types​

# Static
- id: core
  type: static
  priority: 0
  content: |
    Your instructions

# Dynamic
- id: timestamp
  type: dynamic
  priority: 10
  source: dateTime | resources

# File
- id: docs
  type: file
  priority: 20
  files: ["path/to/file.md"]
  options:
    includeFilenames: boolean
    separator: string
    errorHandling: skip | error
    maxFileSize: number

# Memory
- id: context
  type: memory
  priority: 30
  options:
    pinnedOnly: boolean
    limit: number
    includeTimestamps: boolean
    includeTags: boolean

MCP Servers​

Guide

For detailed configuration and examples, see MCP Configuration.

External tools and services via Model Context Protocol.

Schema​

mcpServers:
  server-name:
    type: stdio | sse | http
    timeout: number               # Optional, default: 30000
    connectionMode: lenient | strict  # Optional, default: lenient
    # Type-specific fields below

Server Types​

# stdio - Local process
filesystem:
  type: stdio
  command: npx
  args: ["-y", "@modelcontextprotocol/server-filesystem", "."]

# sse - Server-Sent Events (deprecated)
remote-sse:
  type: sse
  url: https://api.example.com/mcp/events
  headers:
    Authorization: Bearer $API_TOKEN

# http - HTTP (recommended for remote)
api-service:
  type: http
  url: https://api.example.com/mcp
  headers:
    Authorization: Bearer $API_TOKEN

Connection Modes​

  • lenient (default) - Log errors, continue without server
  • strict - Require successful connection or fail startup

Tool Confirmation​

Guide

For detailed policy configuration, see Tool Confirmation Guide.

Tool approval and confirmation behavior.

Schema​

toolConfirmation:
  mode: manual | auto-approve | auto-deny  # Default: manual
  timeout: number               # Default: 120000ms
  allowedToolsStorage: memory | storage  # Default: storage
  toolPolicies:                 # Optional
    alwaysAllow: [string]       # Never require approval
    alwaysDeny: [string]        # Always denied (takes precedence)

Tool Name Format​

  • Internal: internal--tool_name
  • MCP: mcp--server_name--tool_name

Example​

toolConfirmation:
  mode: manual
  toolPolicies:
    alwaysAllow:
      - internal--ask_user
      - mcp--filesystem--read_file
    alwaysDeny:
      - mcp--filesystem--delete_file

Storage Configuration​

Guide

For detailed storage options and examples, see Storage Configuration Guide.

Storage backends for cache, database, and blob storage.

Schema​

storage:
  cache:
    type: in-memory | redis
  database:
    type: in-memory | sqlite | postgres
  blob:
    type: in-memory | local

Cache Types​

# In-Memory
cache:
  type: in-memory
  maxConnections: number        # Optional
  idleTimeoutMillis: number     # Optional
  connectionTimeoutMillis: number  # Optional

# Redis
cache:
  type: redis
  url: $REDIS_URL               # Option 1
  # OR
  host: string                  # Option 2
  port: number
  password: string
  database: number
  maxConnections: number
  idleTimeoutMillis: number

Database Types​

# In-Memory
database:
  type: in-memory

# SQLite
database:
  type: sqlite
  path: string                  # Required: full path to database file
  maxConnections: number        # Optional

# PostgreSQL
database:
  type: postgres
  url: $POSTGRES_URL            # Option 1
  # OR
  connectionString: string      # Option 2
  # OR
  host: string                  # Option 3
  port: number
  database: string
  password: string
  maxConnections: number

Blob Storage Types​

# In-Memory
blob:
  type: in-memory
  maxBlobSize: number           # Default: 10485760 (10MB)
  maxTotalSize: number          # Default: 104857600 (100MB)

# Local Filesystem
blob:
  type: local
  storePath: string             # Optional, auto-detected
  maxBlobSize: number           # Default: 52428800 (50MB)
  maxTotalSize: number          # Default: 1073741824 (1GB)
  cleanupAfterDays: number      # Default: 30

Session Configuration​

Guide

For detailed session behavior, see Session Configuration Guide.

Session management limits and timeouts.

Schema​

sessions:
  maxSessions: number           # Default: 100
  sessionTTL: number            # Default: 3600000ms (1 hour)

Telemetry Configuration​

Guide

For detailed telemetry setup, see Telemetry Configuration Guide.

OpenTelemetry distributed tracing.

Schema​

telemetry:
  enabled: boolean              # Default: false
  serviceName: string           # Default: agent name
  tracerName: string            # Default: 'dexto-tracer'
  export:
    type: otlp | console
    protocol: http | grpc       # Default: http
    endpoint: string            # OTLP collector URL
    headers:                    # Optional
      [key: string]: string

Examples​

# Local Jaeger
telemetry:
  enabled: true
  export:
    type: otlp
    protocol: http
    endpoint: http://localhost:4318/v1/traces

# Grafana Cloud
telemetry:
  enabled: true
  export:
    type: otlp
    endpoint: https://otlp-gateway-prod.grafana.net/otlp
    headers:
      authorization: "Basic ${GRAFANA_CLOUD_TOKEN}"

# Console (debugging)
telemetry:
  enabled: true
  export:
    type: console

Logger Configuration​

Multi-transport logging system with file, console, and remote transport support.

CLI Auto-Configuration

The CLI automatically adds a per-agent file transport at ~/.dexto/logs/<agent-id>.log. You only need to configure this section if you want to customize logging behavior or add additional transports.

Schema​

logger:
  level: error | warn | info | debug | silly  # Default: info
  transports:
    - type: console | file
      # Type-specific fields below

Log Levels​

Following Winston convention (lower = more severe):

  • error - Only critical errors
  • warn - Warnings and errors
  • info - General information (default)
  • debug - Detailed debugging information
  • silly - Very detailed trace information

Transport Types​

# Console Transport
- type: console
  colorize: boolean        # Default: true

# File Transport
- type: file
  path: string            # Required: full path to log file
  maxSize: number         # Default: 10485760 (10MB)
  maxFiles: number        # Default: 5 (rotation count)

Examples​

# Console only (development)
logger:
  level: debug
  transports:
    - type: console
      colorize: true

# File only (production)
logger:
  level: info
  transports:
    - type: file
      path: ./logs/agent.log
      maxSize: 10485760
      maxFiles: 5

# Both console and file
logger:
  level: debug
  transports:
    - type: console
      colorize: true
    - type: file
      path: ./logs/agent.log
      maxSize: 10485760
      maxFiles: 5

Per-Agent Log Files​

The CLI automatically creates per-agent log files at:

  • ~/.dexto/logs/<agent-id>.log

Where <agent-id> is derived from:

  1. agentCard.name (sanitized for filesystem)
  2. Config filename (e.g., my-agent.yml → my-agent)
  3. Fallback: default-agent

Plugins​

Guide

For plugin development and configuration, see Plugins Guide.

Built-in and custom plugins for input/output processing.

Schema​

plugins:
  # Built-in
  contentPolicy:
    priority: number
    blocking: boolean
    enabled: boolean
    # Plugin-specific fields

  responseSanitizer:
    priority: number
    blocking: boolean
    enabled: boolean
    # Plugin-specific fields

  # Custom
  custom:
    - name: string
      module: string
      enabled: boolean
      blocking: boolean
      priority: number
      config: {}

Built-in Plugins​

# Content Policy
contentPolicy:
  priority: 10
  blocking: true
  enabled: true
  maxInputChars: 50000
  redactEmails: boolean
  redactApiKeys: boolean

# Response Sanitizer
responseSanitizer:
  priority: 900
  blocking: false
  enabled: true
  redactEmails: boolean
  redactApiKeys: boolean
  maxResponseLength: 100000

Custom Plugins​

custom:
  - name: tenant-auth
    module: "${{dexto.agent_dir}}/plugins/tenant-auth.ts"
    enabled: true
    blocking: true
    priority: 100
    config:
      enforceQuota: true
      maxRequestsPerHour: 1000

Internal Tools​

Guide

For tool descriptions and usage patterns, see Internal Tools Guide.

Built-in tools for file operations, code search, and command execution.

Schema​

internalTools:
  - ask_user
  - read_file
  - write_file
  - edit_file
  - glob_files
  - grep_content
  - bash_exec
  - bash_output
  - kill_process

Available Tools​

  • ask_user - Ask questions and collect user input
  • read_file - Read file contents
  • write_file - Write content to files
  • edit_file - Edit files by replacing text
  • glob_files - Find files using glob patterns
  • grep_content - Search file contents with regex
  • bash_exec - Execute shell commands
  • bash_output - Get output from background processes
  • kill_process - Terminate background processes

Internal Resources​

Guide

For detailed configuration and examples, see Internal Resources Guide.

Access to files and blob storage.

Schema​

internalResources:
  enabled: boolean              # Optional, auto-enabled if resources non-empty
  resources:
    - type: filesystem
      paths: [string]           # Required
      maxDepth: number          # Optional, default: 3, max: 10
      maxFiles: number          # Optional, default: 1000, max: 10000
      includeHidden: boolean    # Optional, default: false
      includeExtensions: [string]  # Optional

    - type: blob                # Settings in storage.blob

Resource Types​

# Filesystem
- type: filesystem
  paths: [".", "./docs"]
  maxFiles: 50
  maxDepth: 3
  includeHidden: false
  includeExtensions: [".txt", ".md", ".json", ".js", ".ts", ".py"]

# Blob
- type: blob

Default File Extensions​

.txt, .md, .js, .ts, .json, .html, .css, .py, .yaml, .yml, .xml, .jsx, .tsx, .vue, .php, .rb, .go, .rs, .java, .kt, .swift, .sql, .sh, .bash, .zsh

Agent Identity / A2A​

Guide

For agent card configuration, see Agent Identity Guide.

Agent identity and capabilities for Agent-to-Agent (A2A) communication.

Schema​

agentCard:
  name: string                    # Required
  description: string
  url: string                     # Required
  provider:
    organization: string
    url: string
  version: string                 # Required
  documentationUrl: string
  capabilities:
    streaming: boolean            # Default: true
    pushNotifications: boolean
    stateTransitionHistory: boolean  # Default: false
  authentication:
    schemes: [string]             # Default: []
    credentials: string
  defaultInputModes: [string]     # Default: ['application/json', 'text/plain']
  defaultOutputModes: [string]    # Default: ['application/json', 'text/event-stream', 'text/plain']
  skills:
    - id: string
      name: string
      description: string
      tags: [string]
      examples: [string]
      inputModes: [string]
      outputModes: [string]

Example​

agentCard:
  name: "MyCustomAgent"
  description: "A specialized agent for data analysis"
  url: "https://myagent.example.com"
  version: "1.0.0"
  capabilities:
    streaming: true
    pushNotifications: false
  skills:
    - id: data_analysis
      name: "Data Analysis"
      description: "Analyze datasets and generate insights"
      tags: ["analysis", "data", "statistics"]

Dynamic Changes​

Guide

For runtime configuration and overrides, see Dynamic Changes Guide.

Runtime configuration changes and environment overrides.

Agent ID​

Unique identifier for this agent instance, used for per-agent isolation of logs, database, and blob storage.

CLI Auto-Derives

The CLI automatically derives the agent ID from your agentCard.name or config filename. You rarely need to set this manually.

Schema​

agentId: string           # Default: derived from agentCard.name or filename

Derivation Rules​

The CLI derives agentId in this priority order:

  1. agentCard.name (sanitized for filesystem):

    agentCard:
      name: "My Custom Agent"  # → agentId: "my-custom-agent"

  2. Config filename (without extension):

    my-agent.yml            # → agentId: "my-agent"
    database-agent.yml      # → agentId: "database-agent"

  3. Fallback: default-agent

Manual Override​

agentId: custom-id-123

Use this when you need explicit control over storage isolation or have multiple instances of the same agent.

Starter Prompts​

Clickable prompt buttons for WebUI.

Schema​

starterPrompts:
  - id: string                  # Required, kebab-case, max 64 chars
    title: string               # Optional, defaults to formatted id
    description: string         # Optional
    prompt: string              # Required
    category: string            # Optional, default: "general"
    priority: number            # Optional, default: 0, higher appears first

Example​

starterPrompts:
  - id: quick-start
    title: "📚 Quick Start Guide"
    prompt: "Show me what you can do and how to work with you"
    category: learning
    priority: 9

  - id: tool-demo
    title: "⚡ Tool Demonstration"
    prompt: "Pick an interesting tool and demonstrate it with a practical example"
    category: tools
    priority: 5

Greeting​

Greeting message shown when chat session starts.

Schema​

greeting: string                # Max 500 characters

Example​

greeting: "Hi! I'm Dexto — how can I help today?"

Global Preferences​

tip

For system-wide CLI preferences (default LLM provider, model, default agent), see the Global Preferences Guide.