Agent Configuration

This guide covers the complete YAML schema for configuring agents in AxonFlow's Multi-Agent Planning system.

Configuration Format

Agents use a Kubernetes-style YAML format with apiVersion, kind, metadata, and spec fields:

apiVersion: axonflow.io/v1
kind: AgentConfig
metadata:
  name: agent-name
  domain: domain-name
  labels:
    environment: production
spec:
  type: specialist
  description: Agent description
  capabilities:
    - capability1
    - capability2
  # ... additional configuration

Schema Reference

Root Fields

Field	Type	Required	Description
`apiVersion`	string	Yes	API version, currently `axonflow.io/v1`
`kind`	string	Yes	Resource type, must be `AgentConfig`
`metadata`	object	Yes	Agent metadata including name and domain
`spec`	object	Yes	Agent specification

Metadata Fields

Field	Type	Required	Description
`name`	string	Yes	Unique agent identifier (lowercase, alphanumeric, hyphens)
`domain`	string	Yes	Domain grouping (travel, healthcare, finance, generic)
`labels`	map	No	Key-value labels for organization
`annotations`	map	No	Additional metadata

Spec Fields

Field	Type	Required	Description
`type`	string	Yes	Agent type: `specialist` or `coordinator`
`description`	string	Yes	Human-readable description
`capabilities`	[]string	Yes	List of agent capabilities
`llm`	object	No*	LLM configuration (required for llm-call)
`connector`	object	No*	Connector configuration (for connector-call)
`tools`	[]string	No	List of MCP connector IDs agent can use
`delegatesTo`	[]string	No	Agent names this coordinator delegates to
`promptTemplate`	string	No	Prompt template with variable placeholders
`timeout`	string	No	Execution timeout (default: 60s)
`retryPolicy`	object	No	Retry configuration

Agent Types

Specialist Agent

Specialist agents perform specific tasks with domain expertise:

apiVersion: axonflow.io/v1
kind: AgentConfig
metadata:
  name: data-analyst
  domain: analytics
spec:
  type: specialist
  description: Analyze data and generate insights
  capabilities:
    - data_analysis
    - statistical_modeling
    - visualization
  llm:
    provider: openai
    model: gpt-4
    temperature: 0.3
    maxTokens: 2000
  promptTemplate: |
    You are a data analyst. Analyze the following data and provide insights:

    Data: {{input.data}}
    Question: {{input.question}}

    Provide analysis with:
    1. Key findings
    2. Statistical summary
    3. Recommendations

Coordinator Agent

Coordinator agents orchestrate other agents:

apiVersion: axonflow.io/v1
kind: AgentConfig
metadata:
  name: research-coordinator
  domain: research
spec:
  type: coordinator
  description: Coordinate multi-source research tasks
  capabilities:
    - research_coordination
    - synthesis
  delegatesTo:
    - web-researcher
    - document-analyzer
    - fact-checker
  llm:
    provider: anthropic
    model: claude-3-sonnet
  promptTemplate: |
    You are a research coordinator. Synthesize findings from multiple sources:

    Web Research: {{steps.web-researcher.output}}
    Document Analysis: {{steps.document-analyzer.output}}
    Fact Check: {{steps.fact-checker.output}}

    Provide a comprehensive summary.

LLM Configuration

The llm field configures the language model:

spec:
  llm:
    provider: openai          # Provider: openai, anthropic, bedrock, ollama
    model: gpt-4              # Model identifier
    temperature: 0.7          # Sampling temperature (0.0-2.0)
    maxTokens: 2000           # Maximum response tokens
    topP: 0.9                 # Top-p sampling
    frequencyPenalty: 0.0     # Frequency penalty (-2.0 to 2.0)
    presencePenalty: 0.0      # Presence penalty (-2.0 to 2.0)
    stopSequences:            # Stop generation sequences
      - "\n\n"
      - "END"

Provider-Specific Configuration

OpenAI

llm:
  provider: openai
  model: gpt-4                # gpt-4, gpt-4-turbo, gpt-3.5-turbo
  temperature: 0.7

Anthropic

llm:
  provider: anthropic
  model: claude-3-sonnet      # claude-3-opus, claude-3-sonnet, claude-3-haiku
  temperature: 0.7

AWS Bedrock

llm:
  provider: bedrock
  model: anthropic.claude-3-sonnet-20240229-v1:0
  region: us-east-1           # AWS region

Ollama (Local)

llm:
  provider: ollama
  model: llama2               # Local model name
  endpoint: http://localhost:11434

Connector Configuration

For agents that query data sources:

spec:
  connector:
    name: postgresql          # Connector ID
    operation: query          # Operation type
    parameters:
      database: analytics
      timeout: 30s

Capabilities

Capabilities define what an agent can do. The planning engine uses capabilities to select agents:

spec:
  capabilities:
    - flight_search           # Search for flights
    - hotel_booking          # Book hotels
    - itinerary_planning     # Create travel plans
    - policy_compliance      # Check travel policies

Common Capabilities by Domain

Domain	Capabilities
travel	flight_search, hotel_search, car_rental, itinerary_planning
healthcare	patient_lookup, appointment_scheduling, medical_records
finance	account_lookup, transaction_analysis, fraud_detection
support	ticket_creation, knowledge_search, escalation
generic	research, summarization, analysis, writing

Prompt Templates

Prompt templates support variable substitution using {{variable}} syntax:

Input Variables

Access input data:

promptTemplate: |
  Process the following request:
  Query: {{input.query}}
  User: {{input.userId}}
  Context: {{input.context}}

Step Output Variables

Access outputs from previous steps:

promptTemplate: |
  Combine these results:
  Research: {{steps.research-step.output}}
  Analysis: {{steps.analysis-step.output.summary}}

Context Variables

Access execution context:

promptTemplate: |
  Current time: {{context.timestamp}}
  Request ID: {{context.requestId}}
  Organization: {{context.organizationId}}

Conditional Templates

promptTemplate: |
  {{#if input.detailed}}
  Provide a detailed analysis with examples.
  {{else}}
  Provide a brief summary.
  {{/if}}

  Topic: {{input.topic}}

Retry Policy

Configure automatic retries for transient failures:

spec:
  retryPolicy:
    maxRetries: 3             # Maximum retry attempts
    initialDelay: 1s          # Initial backoff delay
    maxDelay: 30s             # Maximum backoff delay
    backoffMultiplier: 2.0    # Exponential backoff multiplier
    retryableErrors:          # Errors that trigger retry
      - timeout
      - rate_limit
      - transient

Multiple Agents File

Define multiple agents in a single file using YAML document separators:

# config/agents/travel-agents.yaml
apiVersion: axonflow.io/v1
kind: AgentConfig
metadata:
  name: flight-search
  domain: travel
spec:
  type: specialist
  description: Search for flight options
  capabilities:
    - flight_search
  llm:
    provider: openai
    model: gpt-4
  promptTemplate: |
    Search for flights from {{input.origin}} to {{input.destination}}
    on {{input.date}}.
---
apiVersion: axonflow.io/v1
kind: AgentConfig
metadata:
  name: hotel-search
  domain: travel
spec:
  type: specialist
  description: Search for hotels
  capabilities:
    - hotel_search
  llm:
    provider: openai
    model: gpt-4
  promptTemplate: |
    Find hotels in {{input.destination}} for {{input.checkIn}} to {{input.checkOut}}.
---
apiVersion: axonflow.io/v1
kind: AgentConfig
metadata:
  name: trip-coordinator
  domain: travel
spec:
  type: coordinator
  description: Coordinate travel planning
  capabilities:
    - trip_planning
  delegatesTo:
    - flight-search
    - hotel-search
  llm:
    provider: openai
    model: gpt-4
  promptTemplate: |
    Create an itinerary combining:
    Flights: {{steps.flight-search.output}}
    Hotels: {{steps.hotel-search.output}}

Domain Templates

AxonFlow includes built-in domain templates that provide default configurations:

Travel Domain

metadata:
  domain: travel

Default capabilities: flight_search, hotel_search, car_rental, itinerary_planning

Healthcare Domain

metadata:
  domain: healthcare

Default capabilities: patient_lookup, appointment_scheduling, medical_records

Finance Domain

metadata:
  domain: finance

Default capabilities: account_lookup, transaction_analysis, risk_assessment

Generic Domain

metadata:
  domain: generic

Default capabilities: research, summarization, analysis

Configuration Loading

File-Based Loading

Place agent files in the config directory:

config/
└── agents/
    ├── travel-agents.yaml
    ├── support-agents.yaml
    └── analytics-agents.yaml

Configure the orchestrator to load agents:

# orchestrator.yaml
agents:
  registry:
    mode: file              # file, database, or hybrid (Enterprise)
    path: /etc/axonflow/agents
    watchForChanges: true   # Reload on file changes

Environment Variables

Override configuration via environment variables:

AXONFLOW_AGENTS_REGISTRY_MODE=file
AXONFLOW_AGENTS_REGISTRY_PATH=/etc/axonflow/agents

Validation

Validate agent configurations before deployment:

# Using the CLI
axonflow validate agents config/agents/

# Using the API
curl -X POST http://localhost:8081/api/v1/agents/validate \
  -H "Content-Type: application/json" \
  -d @config/agents/my-agent.yaml

Common Validation Errors

Error	Cause	Solution
`missing required field: metadata.name`	Agent name not specified	Add `name` to metadata
`invalid domain`	Unknown domain value	Use: travel, healthcare, finance, generic
`llm config required for llm-call`	LLM not configured	Add `llm` section to spec
`circular delegation detected`	Coordinator delegates to itself	Remove circular reference

Best Practices

1. Use Descriptive Names

# Good
metadata:
  name: flight-availability-checker

# Avoid
metadata:
  name: agent1

2. Define Clear Capabilities

# Good - specific capabilities
capabilities:
  - flight_search
  - fare_comparison
  - booking_validation

# Avoid - vague capabilities
capabilities:
  - travel
  - stuff

3. Keep Prompts Focused

# Good - clear, focused prompt
promptTemplate: |
  Search for flights matching these criteria:
  - From: {{input.origin}}
  - To: {{input.destination}}
  - Date: {{input.date}}

  Return the top 3 options with prices.

# Avoid - overly complex prompts
promptTemplate: |
  You are an AI assistant that can do many things including
  searching for flights, hotels, cars, and more...

4. Set Appropriate Timeouts

spec:
  timeout: 30s    # Short tasks
  # timeout: 120s # Complex analysis

5. Use Labels for Organization

metadata:
  name: production-support-agent
  domain: support
  labels:
    environment: production
    team: customer-success
    version: "2.1"

Next Steps

Step Types - Learn about all execution step types
Planning Patterns - Orchestration patterns
API Reference - Complete API documentation

Configuration Format​

Schema Reference​

Root Fields​

Metadata Fields​

Spec Fields​

Agent Types​

Specialist Agent​

Coordinator Agent​

LLM Configuration​

Provider-Specific Configuration​

OpenAI​

Anthropic​

AWS Bedrock​

Ollama (Local)​

Connector Configuration​

Capabilities​

Common Capabilities by Domain​

Prompt Templates​

Input Variables​

Step Output Variables​

Context Variables​

Conditional Templates​

Retry Policy​

Multiple Agents File​

Domain Templates​

Travel Domain​

Healthcare Domain​

Finance Domain​

Generic Domain​

Configuration Loading​

File-Based Loading​

Environment Variables​

Validation​

Common Validation Errors​

Best Practices​

1. Use Descriptive Names​

2. Define Clear Capabilities​

3. Keep Prompts Focused​

4. Set Appropriate Timeouts​

5. Use Labels for Organization​

Next Steps​