Config Reference

All agent configuration lives in a single agent.toml file in the project root. Generate it interactively with ai init, then tune by hand. Sensitive values (API keys) must always use ${ENV_VAR} references — inline secrets are rejected at load time.

Security: Fields agent.model.api_key and any [[agent.model.fallback_chain]] api_key must be ${ENV_VAR} references. Literal secrets are rejected with an error.

[agent]

Top-level agent identity and system prompt.

FieldTypeDefaultDescription
namestring—Required. Human-readable agent name (used in AgentCard and logs)
descriptionstring""Short description of the agent's purpose (exposed via A2A AgentCard)
system_promptstring""Base system prompt. Skill fragments are appended at serve time. Bare $name is never expanded — use ${VAR} only for API keys

[agent.model]

Primary model selection and optional fallback chain.

FieldTypeDefaultDescription
providerstring—"anthropic" (uses anthropic-sdk-go) or "openai-compat" (any OpenAI-compatible endpoint)
modelstring—Model ID, e.g. "claude-sonnet-4-6", "gpt-5-mini", "llama3" (Ollama), "mistral" (vLLM/Fireworks)
api_keystring""Must be ${ENV_VAR}. E.g. ${ANTHROPIC_API_KEY}
base_urlstring""For openai-compat: endpoint URL (e.g. http://localhost:11434/v1)
max_response_tokensint8192Maximum tokens per model response

[[agent.model.fallback_chain]]

Ordered list of fallback models. Tried in sequence if the primary model fails or hits the cost circuit breaker.

FieldTypeDefaultDescription
providerstring—"anthropic" or "openai-compat"
modelstring—Fallback model ID
base_urlstring""For openai-compat fallbacks
api_keystring""Must be ${ENV_VAR} if set
 
[[agent.model.fallback_chain]]
provider = "openai-compat"
model    = "llama3"
base_url = "${OLLAMA_URL}"

[[agent.model.fallback_chain]]
provider = "anthropic"
model    = "claude-haiku-4-5-20251001"
api_key  = "${ANTHROPIC_API_KEY}"

[agent.budget]

Resource limits and context pressure thresholds for each session.

FieldTypeDefaultDescription
max_turnsint10Maximum agent turns per session before aborting
max_tokens_per_sessionint0Max total tokens (input + output) per session. 0 = unlimited
max_usd_per_sessionfloat0.0Cost circuit breaker in USD per session. 0.0 = unlimited
context_warn_ratiofloat0.70Context fill ratio that triggers a warning log (0.0–1.0)
context_compact_ratiofloat0.80Context fill ratio that triggers automatic compaction
context_abort_ratiofloat0.95Context fill ratio that triggers session abort to prevent truncation

[agent.memory]

Session persistence and semantic memory backends.

FieldTypeDefaultDescription
session_storestring"inmemory"Session state backend: "file", "redis", or "inmemory"
semantic_memoryboolfalseEnable semantic memory sidecar (port 8092) for cross-session recall
trace_graphboolfalseWrite execution traces (turn-by-turn) to the graph DB for replay and evaluation

[agent.toolbox]

MCP tool server connection. Start mcp-toolbox with ai sidecar mcp-toolbox --config toolbox.yaml — it supports 48 database sources out of the box including Neo4j, PostgreSQL, MySQL, MongoDB, Redis, BigQuery, Snowflake, Cassandra, Elasticsearch, and more. See ai sidecar and the toolbox.yaml reference below.

FieldTypeDefaultDescription
endpointstring""MCP server SSE URL, e.g. "http://localhost:15001/mcp/sse"
transportstring"sse""sse" for HTTP/SSE (multi-session); "stdio" for subprocess / single-client

toolbox.yaml

Separate config file consumed by mcp-toolbox (not agent.toml). Defines database sources and the Cypher / SQL tools the agent can call.

Supported source kinds (48 total)

CategorySources
Graphneo4j, dgraph
Documentmongodb, firestore, couchbase, elasticsearch
Relationalpostgres, mysql, mariadb, mssql, oracle, sqlite, cockroachdb, tidb, yugabytedb, clickhouse, trino, singlestore, oceanbase, firebird, mindsdb
Key-value / Cacheredis, valkey, cassandra, bigtable
Cloud analyticsbigquery, spanner, snowflake, looker, cloud-gda, dataplex, dataproc
Google Cloud SQLalloydb-pg, cloud-sql-mysql, cloud-sql-pg, cloud-sql-mssql
Othercloud-healthcare, cloud-logging-admin, cloud-monitoring, http

Minimal Neo4j example

sources:
  my_graph:
    kind: neo4j
    uri:      "${NEO4J_URI}"
    username: "${NEO4J_USERNAME}"
    password: "${NEO4J_PASSWORD}"
    database: "${NEO4J_DATABASE}"

tools:
  search_companies:
    source:      my_graph
    description: "Find companies by name (case-insensitive partial match)"
    parameters:
      - name: query
        type: string
        description: "Company name fragment"
    statement: |
      MATCH (c:Company)
      WHERE toLower(c.name) CONTAINS toLower($query)
      RETURN c.name AS name LIMIT 10

toolsets:
  default:
    - search_companies

Minimal PostgreSQL example

sources:
  my_db:
    kind: postgres
    host:     "${PG_HOST}"
    port:     5432
    database: "${PG_DATABASE}"
    user:     "${PG_USER}"
    password: "${PG_PASSWORD}"

tools:
  list_orders:
    source:      my_db
    description: "List recent orders for a customer"
    parameters:
      - name: customer_id
        type: integer
        description: "Customer ID"
    statement: |
      SELECT id, status, total FROM orders
      WHERE customer_id = $customer_id
      ORDER BY created_at DESC LIMIT 20

Start the server: ai sidecar mcp-toolbox --config toolbox.yaml --port 15001

Connect the agent: set [agent.toolbox] endpoint = "http://localhost:15001/mcp/sse"

[[agent.tools]]

Explicit tool entries that supplement toolbox-discovered tools. Repeated table.

FieldTypeDefaultDescription
namestring—Tool name (must match a tool registered in the tool registry)
descriptionstring""Optional override for the tool's description shown to the model

[agent.skills]

List of skills to load at serve time. Each skill contributes system prompt fragments and tool requirements.

FieldTypeDefaultDescription
skills[]string[]Skill names or GitHub refs, e.g. ["graph-search", "memory-recall"]

[agent.a2a]

Inbound Agent-to-Agent (A2A) protocol server configuration.

FieldTypeDefaultDescription
enabledbooltrueEnable the inbound A2A HTTP server
portint8080Port for the A2A server to listen on
endpointstring""Outbound URL for task handoff to another agent (used by StepHandoff)

[agent.mcp_server]

Outward-facing MCP server surface — exposes agent skills as MCP prompts to Claude Desktop, Cursor, and other MCP hosts.

FieldTypeDefaultDescription
enabledboolfalseEnable the outward MCP server
transportstring"http""stdio" (single host, e.g. Claude Desktop) or "http" (multi-client SSE)
portint8081Port for the MCP HTTP server

[agent.security]

Authentication and prompt injection protection.

FieldTypeDefaultDescription
require_authboolfalseRequire Bearer token auth on all A2A endpoints
injection_detectionboolfalseScan incoming messages and tool results for prompt injection patterns

When require_auth = true, all A2A requests must include Authorization: Bearer <token>. Task ownership is enforced — clients can only access tasks they created.

Full Example

A complete annotated agent.toml:

# agent.toml — complete example

[agent]
name         = "companies-researcher"
description  = "Research companies using the knowledge graph"
system_prompt = """
You are a research agent. Use available tools to answer questions about companies.
Prefer targeted lookups over broad queries. Cite your sources.
"""

[agent.model]
provider            = "anthropic"
model               = "claude-sonnet-4-6"
api_key             = "${ANTHROPIC_API_KEY}"
max_response_tokens = 8192

[[agent.model.fallback_chain]]
provider = "openai-compat"
model    = "llama3"
base_url = "${OLLAMA_URL}"

[agent.budget]
max_turns              = 15
max_tokens_per_session = 0        # 0 = unlimited
max_usd_per_session    = 0.50
context_warn_ratio     = 0.70
context_compact_ratio  = 0.80
context_abort_ratio    = 0.95

[agent.memory]
session_store   = "file"     # file | redis | inmemory
semantic_memory = true
trace_graph     = true       # write execution traces to graph DB

[agent.toolbox]
endpoint  = "http://localhost:15000/mcp/sse"
transport = "http"         # stdio | http

[agent.skills]
skills = ["graph-search", "memory-recall"]

[agent.a2a]
enabled = true
port    = 8080

[agent.mcp_server]
enabled    = true
transport  = "http"       # stdio | http
port       = 8081

[agent.security]
require_auth        = true
injection_detection = true