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-4o", "llama3"
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 (genai-toolbox and/or CypherMCP subprocess).

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

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