Config Reference

[agent]

Top-level agent identity and system prompt.

[agent.model]

Primary model selection and optional fallback chain.

[[agent.model.fallback_chain]]

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

[[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.

[agent.memory]

Session persistence and semantic memory backends.

[agent.graph]

Connection to a graph database backend (Neo4j Aura or local Cypherlite).

[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.

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)

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.

[agent.tool_context]

Layered tool context management. Controls how many tool schemas are injected per turn and which strategies are active.

[agent.skills]

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

[agent.a2a]

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

[agent.a2a.auth]

Authentication mode for inbound A2A requests.

Example — Google ID token auth for a Cloud Run service:

[agent.a2a.auth]
mode     = "google"
audience = "https://my-agent-abc123-uc.a.run.app"

[agent.a2a.card]

AgentCard metadata served at GET /.well-known/agent.json. Conforms to A2A protocol v0.3.

Use ai show --card --validate to check that all required fields are populated before registering with Gemini Enterprise.

[agent.deploy.cloudrun]

Persistent Cloud Run deployment settings. Values here become defaults for ai deploy --target cloudrun; CLI flags always override.

Example:

[agent.deploy.cloudrun]
project              = "my-gcp-project"
region               = "us-central1"
allow_unauthenticated = true
secrets              = [
  "ANTHROPIC_API_KEY=projects/my-gcp-project/secrets/anthropic-key/versions/latest",
]

[agent.mcp_server]

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

[agent.security]

Authentication and prompt injection protection.

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

[agent.sandbox]

Secure code execution sandbox. Registers execute_js, execute_python, and execute_shell MCP tools when enabled.

[agent.tool_trust]

Override automatic trust classification for specific tools. Trust levels range from T4 (schema-meta, highest trust) to T9 (untrusted, lowest trust).

[agent.tool_trust.overrides]
"my_internal_api__" = 6   # T6: allowlisted external API
"scraped_content"   = 8   # T8: web content

[agent.tool_reversibility]

Override automatic reversibility classification for specific tools.

Built-in tool classifications

These tools are always classified as shown, regardless of overrides. Use overrides to change the classification for your deployment.

[agent.tool_reversibility.overrides]
"my_safe_shell" = 0   # treat as safe even though name matches R_DESTROY
"read_api"      = 2   # this read-looking tool has irreversible side effects

[agent.intent_router]

Intent-based routing. Classifies user intent before the first LLM call and restricts tool visibility to the matched route.

[[agent.intent_router.route]]

Ordered list of intent routes. A route with intent = "default" acts as the fallback when no other intent matches.

[agent.intent_router]
classify_model = "claude-haiku-4-5-20251001"

[[agent.intent_router.route]]
intent = "research"
tools  = ["search_companies", "get_company_details"]

[[agent.intent_router.route]]
intent = "billing"
agent  = "http://billing-agent:8080"

[[agent.intent_router.route]]
intent = "default"

[[agent.tool_guard]]

Before/after guards for tool calls. Repeated table — add one section per guard rule.

[[agent.tool_guard]]
tool   = "delete_*"
before = "human_approval"

[[agent.tool_guard]]
tool  = "write_file"
after = "audit_log"

[agent.honesty]

Calibrated uncertainty and identity acknowledgement behaviours injected into the system prompt.