Agent Configuration Overview

Complete guide to defining and configuring AI agents in Archia.

Configuration Options

Archia supports two methods for configuring agents:

1. Individual TOML Files: Store each agent as a separate .toml file in ~/.archia/agents/
2. Server Configuration File: Define agents inline in the server’s config.toml (legacy method)

The recommended approach is using individual TOML files, which allows for easier management, version control, and dynamic updates.

File-Based Agent Configuration

Location

Agent configuration files are stored in the agents directory:

• Production: ~/.archia/agents/
• Development: ~/.archia_dev/agents/

Each agent is defined in its own TOML file named {agent-name}.toml.

Basic Agent Definition

Every agent requires at minimum a name and model:

# ~/.archia/agents/assistant.toml
name = "assistant"
model_name = "claude-haiku-4-5-20251001"
enabled = true

This creates a basic agent accessible at /v1/agent/assistant/chat.

Complete Agent Structure

Here’s a fully-configured agent with all available options:

# ~/.archia/agents/expert.toml

# Required fields
name = "expert"                           # Unique identifier (alphanumeric, hyphens, underscores)
model_name = "claude-sonnet-4-5-20250929"   # LLM model to use
enabled = true                            # Whether the agent is active

# Optional description
description = "Expert technical assistant with database access"

# System prompt (choose one method)
system_prompt = "You are an expert assistant"     # Inline text
# OR
system_prompt_file = "expert.md"                  # Reference to file in ~/.archia/prompts/

# MCP tool access (new format - recommended)
[mcp_tools]
database = ["query", "list_tables"]       # Specific tools from 'database' MCP
filesystem = []                           # All tools from 'filesystem' MCP (empty array = all)
search = null                             # All tools (null = all)

# Legacy MCP access (deprecated, use mcp_tools instead)
# mcp_names = ["database", "filesystem"]

# Agent management capabilities
can_manage_agents = false                 # If true, agent can spawn/manage other agents

# Extended thinking (for supported models)
enable_extended_thinking = false          # Enable extended thinking for complex tasks

Configuration Fields Reference

System Prompts

System prompts define your agent’s personality, knowledge, and behavior. You can specify them in three ways:

1. Inline Prompts

For shorter prompts, include them directly in the configuration:

name = "comedian"
model_name = "claude-sonnet-4-5-20250929"
enabled = true
system_prompt = """
You are a professional comedian who explains technical concepts through humor.
Use puns, jokes, and funny analogies to make complex topics accessible.
Always stay respectful and appropriate.
"""

2. File-based Prompts

For complex prompts, reference external files stored in ~/.archia/prompts/:

name = "analyst"
model_name = "claude-sonnet-4-5-20250929"
enabled = true
system_prompt_file = "data_analyst.md"

Create the prompt file at ~/.archia/prompts/data_analyst.md:

# Data Analyst Assistant

You are an expert data analyst with 20 years of experience in:

- Statistical analysis and hypothesis testing
- Data visualization and storytelling
- SQL and database optimization
- Python (pandas, numpy, scikit-learn)
- Business intelligence and KPI development

## Communication Style

- Be precise with statistical terminology
- Provide confidence intervals when appropriate
- Suggest visualizations for insights
- Always consider data quality and biases

Prompt Resolution Priority

When both system_prompt and system_prompt_file are specified:

1. system_prompt (inline) takes precedence
2. system_prompt_file is used as fallback

Extended Thinking

The enable_extended_thinking option enables reasoning capabilities for supported models, allowing them to “think through” complex problems before responding.

Basic Usage

name = "analyst"
model_name = "claude-sonnet-4-5-20250929"
enabled = true
enable_extended_thinking = true

system_prompt = "You are an expert data analyst."

Behavior by Model

When enable_extended_thinking = true:

When enable_extended_thinking = false (default):

Provider-Specific Implementation

Different providers implement extended thinking differently:

When to Use Extended Thinking

Enable for:

• Complex analytical tasks
• Multi-step reasoning problems
• Code review and debugging
• Mathematical or logical problems
• Research synthesis

Keep disabled for:

• Simple Q&A
• Quick lookups
• Conversational chat
• Tasks where latency matters

Example: Research Agent with Extended Thinking

name = "research-analyst"
model_name = "claude-sonnet-4-5-20250929"
enabled = true
enable_extended_thinking = true
description = "Deep research analyst for complex analysis tasks"

system_prompt = """
You are a senior research analyst. Take your time to think through problems 
thoroughly before providing your analysis. Consider multiple perspectives 
and potential edge cases.
"""

[mcp_tools]
web_search = null
document_store = ["search", "retrieve"]

Overriding via API

When using the Responses API, you can override the agent’s enable_extended_thinking setting by explicitly providing the reasoning parameter:

{
  "model": "agent:research-analyst",
  "input": "Analyze this data",
  "reasoning": {
    "effort": "low"
  }
}

This explicit reasoning parameter takes precedence over the agent’s configuration.

MCP Tool Integration

New Format (Recommended)

The mcp_tools map provides fine-grained control over which tools from each MCP server the agent can access:

[mcp_tools]
# Grant access to specific tools only
database = ["query", "list_tables", "describe_table"]

# Grant access to all tools from an MCP (two equivalent ways)
filesystem = []      # Empty array = all tools
search = null        # null = all tools

# Another MCP with specific tools
github = ["list_repos", "create_issue"]

Legacy Format (Deprecated)

The mcp_names array grants access to all tools from listed MCPs:

mcp_names = ["database", "filesystem", "search"]

Note: If both formats are used, they are merged. The new mcp_tools format takes precedence for any MCP listed in both.

Managing Agents

Via CLI

# List all agents
archiad agent list

# Show agent configuration
archiad agent show assistant

# Set/update an agent from a file
archiad agent set --name assistant --file ./my-agent.toml

# Remove an agent
archiad agent unset --name assistant

Via REST API

# List all agent configurations
curl http://localhost:8080/v1/agent/config

# Get specific agent
curl http://localhost:8080/v1/agent/config/assistant

# Create new agent
curl -X POST http://localhost:8080/v1/agent/config \
  -H "Content-Type: application/json" \
  -d '{
    "name": "helper",
    "model_name": "claude-haiku-4-5-20251001",
    "enabled": true,
    "description": "A helpful assistant",
    "system_prompt": "You are a helpful assistant."
  }'

# Update agent
curl -X PUT http://localhost:8080/v1/agent/config/helper \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

# Delete agent
curl -X DELETE http://localhost:8080/v1/agent/config/helper

Example Configurations

Customer Support Agent

# ~/.archia/agents/support.toml
name = "support"
model_name = "claude-sonnet-4-5-20250929"
enabled = true
description = "Customer support agent with knowledge base access"

system_prompt = """
You are a friendly and professional customer support agent.
- Always greet customers warmly
- Be patient and understanding
- Escalate complex issues when appropriate
- Never share internal policies or workarounds
"""

[mcp_tools]
knowledge_base = ["search", "get_article"]
ticketing = ["create_ticket", "update_ticket"]

Code Review Agent

# ~/.archia/agents/code-reviewer.toml
name = "code-reviewer"
model_name = "claude-sonnet-4-5-20250929"
enabled = true
description = "Automated code review assistant"
system_prompt_file = "code-review-prompt.md"

[mcp_tools]
github = ["get_pull_request", "list_files", "add_comment"]
filesystem = ["read_file"]

Research Agent with Sub-agent Management

# ~/.archia/agents/researcher.toml
name = "researcher"
model_name = "claude-sonnet-4-5-20250929"
enabled = true
description = "Research coordinator that can delegate to specialized agents"
can_manage_agents = true

system_prompt = """
You are a research coordinator. You can:
1. Search the web for information
2. Delegate specialized tasks to other agents
3. Synthesize findings into comprehensive reports
"""

[mcp_tools]
web_search = null
document_store = ["save", "retrieve"]

Best Practices

1. Use Descriptive Names

# Good
name = "customer-support-tier1"
name = "code-review-python"
name = "data-analyst-financial"

# Avoid
name = "agent1"
name = "helper"
name = "bot"

2. Organize Prompt Files

~/.archia/
├── agents/
│   ├── support.toml
│   ├── analyst.toml
│   └── developer.toml
└── prompts/
    ├── support-prompt.md
    ├── analyst-prompt.md
    └── developer-prompt.md

3. Use Minimal Tool Access

Grant agents only the tools they need:

# Good - specific tools
[mcp_tools]
database = ["query"]  # Read-only

# Avoid - unnecessary access
[mcp_tools]
database = null  # All tools including write operations

4. Version Control Your Configurations

Store agent configurations in version control for:

• Change tracking
• Environment consistency
• Easy rollbacks
• Team collaboration

Migration from Legacy Config

If you’re migrating from the server config.toml format:

Old format (in config.toml):

[[agents]]
name = "assistant"
model = "claude-haiku-4-5-20251001"
system = "You are a helpful assistant"
mcps = ["database", "filesystem"]

New format (separate file):

# ~/.archia/agents/assistant.toml
name = "assistant"
model_name = "claude-haiku-4-5-20251001"
enabled = true
system_prompt = "You are a helpful assistant"

[mcp_tools]
database = null
filesystem = null

Next Steps

• Tool Configuration → - Configure MCP tools
• Server Deployment → - Production deployment
• REST API Reference → - Complete API documentation