Tool Modes - AXON

AXON’s tool system supports three execution modes: stub, real, and hybrid. This flexibility enables safe development without API keys while supporting production deployments with real external services.

Overview

Tool modes control how AXON executes tools declared in your programs:

Mode	Behavior	API Keys Required	Use Case
stub	Returns mock data	No	Development, testing, CI/CD
real	Calls production APIs	Yes	Production execution
hybrid	Prefers real, falls back to stubs	Partial	Mixed environments

Configuration

Command-Line

Set the tool mode using the --tool-mode flag:

axon run program.axon --tool-mode stub
axon run program.axon --tool-mode real
axon run program.axon --tool-mode hybrid

Default: stub (if not specified)

Python API

from axon.runtime.tools import create_default_registry

# Stub mode (default)
registry = create_default_registry(mode="stub")

# Real mode
registry = create_default_registry(mode="real")

# Hybrid mode
registry = create_default_registry(mode="hybrid")

Stub Mode

Description

Stub mode uses fake implementations for all tools. No external API calls are made, and all results are deterministic mock data.

Usage

axon run program.axon --tool-mode stub

Behavior

WebSearch

tool

Returns hardcoded search results with realistic structureExample Output:

{
  "results": [
    {
      "title": "Example Result",
      "url": "https://example.com",
      "snippet": "This is a mock search result..."
    }
  ]
}

FileReader

tool

Returns mock file contentsExample Output:

Mock file contents for: document.txt
This is simulated data.

CodeExecutor

tool

Returns mock execution results without running codeExample Output:

{
  "stdout": "Mock execution result",
  "stderr": "",
  "exit_code": 0
}

PDFExtractor

tool

Returns mock PDF text extraction

ImageAnalyzer

tool

Returns mock image analysis

APICall

tool

Returns mock API responses

Calculator

tool

Always real — Uses Python stdlib for actual calculations

DateTime

tool

Always real — Uses Python stdlib for actual date/time operations

Advantages

No API keys required — Works out of the box
Fast execution — No network latency
Deterministic — Same input = same output
Cost-free — No API charges
Safe for CI/CD — No external dependencies

Use Cases

Local Development

# Rapid iteration without API costs
axon run program.axon --tool-mode stub

Unit Testing

def test_flow():
    registry = create_default_registry(mode="stub")
    executor = Executor(tool_registry=registry)
    result = await executor.execute(compiled_program)
    assert result.success

CI/CD Pipelines

# .github/workflows/test.yml
- name: Test AXON Programs
  run: |
    axon run tests/*.axon --tool-mode stub

Learning AXON

# No setup required for beginners
axon run example.axon --tool-mode stub

Real Mode

Description

Real mode uses production backends for all tools. Requires API keys for external services.

Usage

# Set required API keys
export SERPER_API_KEY="..."

# Run with real tools
axon run program.axon --tool-mode real

Behavior

WebSearch

tool

Calls Serper.dev API for Google Search resultsRequires: SERPER_API_KEYBackend: axon.runtime.tools.backends.web_search_serper.WebSearchSerper

FileReader

tool

Reads actual files from the filesystemRequires: File system accessBackend: axon.runtime.tools.backends.file_reader_local.FileReaderLocal

CodeExecutor

tool

Executes code using subprocess (Python, JavaScript, etc.)Requires: Installed interpreters (python3, node, etc.)Backend: axon.runtime.tools.backends.code_executor_subprocess.CodeExecutorSubprocess

Calculator

tool

Always real — Python stdlib

DateTime

tool

Always real — Python stdlib

PDFExtractor

tool

Not yet implemented — Falls back to stub

ImageAnalyzer

tool

Not yet implemented — Falls back to stub

APICall

tool

Not yet implemented — Falls back to stub

Advantages

Production-ready — Real data, real results
Accurate — Actual external service responses
Complete functionality — Access to full tool capabilities

Use Cases

Production Execution

export ANTHROPIC_API_KEY="..."
export SERPER_API_KEY="..."
axon run main.axon --backend anthropic --tool-mode real

Integration Testing

# Test with real external services
axon run integration_test.axon --tool-mode real

Data Collection

# Actually scrape/search/process real data
axon run data_pipeline.axon --tool-mode real --trace

Limitations

Requires API keys — Must configure credentials
Costs money — External APIs charge per request
Network dependent — Requires internet connectivity
Rate limits — Subject to provider quotas

Hybrid Mode (Recommended)

Description

Hybrid mode attempts to use real tool backends where API keys are available, falling back to stubs automatically when credentials are missing.

Usage

# Set only the API keys you have
export SERPER_API_KEY="..."  # Have this
# Don't set BRAVE_API_KEY      # Don't have this

# Hybrid mode adapts automatically
axon run program.axon --tool-mode hybrid

Behavior

Initialization:
- Loads all stub implementations first
- Attempts to register real backends
- Real backends override stubs where successful
Execution:
- Uses real backend if API key available
- Falls back to stub if credentials missing
- Logs warnings for missing dependencies

Example Scenario:

# With SERPER_API_KEY set
WebSearch → Uses Serper.dev (real)
FileReader → Uses local filesystem (real)
CodeExecutor → Uses subprocess (real)
PDFExtractor → Falls back to stub (not implemented)
Calculator → Always real
DateTime → Always real

Advantages

Flexible — Works with partial credentials
Graceful degradation — No hard failures
Development-friendly — Add API keys incrementally
Best of both worlds — Real tools where it matters, stubs where it doesn’t

Use Cases

Incremental Development

# Start with stubs
axon run program.axon --tool-mode hybrid

# Add API keys as needed
export SERPER_API_KEY="..."
axon run program.axon --tool-mode hybrid  # Now WebSearch is real

Team Environments

# Each developer has different API keys
# Alice has SERPER_API_KEY
# Bob has ANTHROPIC_API_KEY
# Both can run the same command
axon run program.axon --tool-mode hybrid

Cost Optimization

# Use real tools only for critical operations
# Let others fall back to stubs
export SERPER_API_KEY="..."  # Only search needs to be real
axon run program.axon --tool-mode hybrid

Gradual Rollout

# Enable real tools one at a time
# Week 1: export SERPER_API_KEY="..."
# Week 2: export BRAVE_API_KEY="..."
# Always use: --tool-mode hybrid

Available Tools

Tool Status Matrix

Tool	Stub	Real Backend	Always Real	Requires
WebSearch	✓	✓ Serper.dev	No	`SERPER_API_KEY`
FileReader	✓	✓ Local FS	No	File system access
CodeExecutor	✓	✓ subprocess	No	Interpreters (python3, node)
Calculator	—	✓ stdlib	Yes	—
DateTime	—	✓ stdlib	Yes	—
PDFExtractor	✓	✗ Planned	No	—
ImageAnalyzer	✓	✗ Planned	No	—
APICall	✓	✗ Planned	No	—

Tool Registration

Tools are registered via the RuntimeToolRegistry:

from axon.runtime.tools import RuntimeToolRegistry
from axon.runtime.tools.stubs import WebSearchStub
from axon.runtime.tools.backends import WebSearchSerper

# Manual registration
registry = RuntimeToolRegistry()

# Stub mode
registry.register(WebSearchStub)

# Real mode
registry.register(WebSearchSerper)

# Check what's registered
print(registry.list_tools())
# {'WebSearch': False}  # False = not a stub (real backend)

Mode Selection Guide

Choose Stub Mode When:

✓ Developing locally without API keys
✓ Running unit tests
✓ Setting up CI/CD pipelines
✓ Learning AXON
✓ Avoiding API costs
✓ Need deterministic results

Choose Real Mode When:

✓ Running in production
✓ Need actual external data
✓ Integration testing
✓ Data collection/processing
✓ All required API keys available

Choose Hybrid Mode When:

✓ Developing with some API keys
✓ Team has mixed credentials
✓ Want graceful degradation
✓ Incrementally enabling real tools
✓ Optimizing costs (selective real tools)
✓ Recommended default for development

Examples

Development Workflow

# Day 1: Start with stubs
axon run program.axon --tool-mode stub

# Day 2: Add search capability
export SERPER_API_KEY="..."
axon run program.axon --tool-mode hybrid  # Search is now real

# Day 3: Ready for production
export ANTHROPIC_API_KEY="..."
axon run program.axon --backend anthropic --tool-mode real

Testing Strategy

# Fast unit tests with stubs
axon run test_*.axon --tool-mode stub

# Integration tests with real tools
export SERPER_API_KEY="..."
axon run integration_*.axon --tool-mode real

# Staging environment with hybrid
axon run staging_*.axon --tool-mode hybrid

Cost-Conscious Execution

# Only enable expensive tools when necessary
if [ "$ENVIRONMENT" = "production" ]; then
  export SERPER_API_KEY="..."
  TOOL_MODE="real"
else
  TOOL_MODE="stub"
fi

axon run program.axon --tool-mode $TOOL_MODE

Troubleshooting

Tool Backend Not Loading

# Check registered tools
python3 << EOF
from axon.runtime.tools import create_default_registry
registry = create_default_registry(mode="hybrid")
print(registry.list_tools())
EOF

Output shows {tool_name: is_stub} for all registered tools.

Missing API Key in Real Mode

✗ Tool 'WebSearch' failed: SERPER_API_KEY not set

Solution: Either set the key or use hybrid mode:

# Option 1: Set the key
export SERPER_API_KEY="..."
axon run program.axon --tool-mode real

# Option 2: Use hybrid (falls back to stub)
axon run program.axon --tool-mode hybrid

Unexpected Stub Data

Symptom: Getting mock data when expecting real results. Solution: Check tool mode and API keys:

echo "Tool mode: $TOOL_MODE"
echo "SERPER_API_KEY: ${SERPER_API_KEY:+SET}"
axon run program.axon --tool-mode real  # Force real mode

API Keys

Configure authentication

run Command

Execute with tool modes

Commands

Configuration

​Overview

​Configuration

​Command-Line

​Python API

​Stub Mode

​Description

​Usage

​Behavior

​Advantages

​Use Cases

​Real Mode

​Description

​Usage

​Behavior

​Advantages

​Use Cases

​Limitations

​Hybrid Mode (Recommended)

​Description

​Usage

​Behavior

​Advantages

​Use Cases

​Available Tools

​Tool Status Matrix

​Tool Registration

​Mode Selection Guide

​Choose Stub Mode When:

​Choose Real Mode When:

​Choose Hybrid Mode When:

​Examples

​Development Workflow

​Testing Strategy

​Cost-Conscious Execution

​Troubleshooting

​Tool Backend Not Loading

​Missing API Key in Real Mode

​Unexpected Stub Data

​Related Documentation

API Keys

run Command

Build docs developers (and LLMs) love

Overview

Configuration

Command-Line

Python API

Stub Mode

Description

Usage

Behavior

Advantages

Use Cases

Real Mode

Description

Usage

Behavior

Advantages

Use Cases

Limitations

Hybrid Mode (Recommended)

Description

Usage

Behavior

Advantages

Use Cases

Available Tools

Tool Status Matrix

Tool Registration

Mode Selection Guide

Choose Stub Mode When:

Choose Real Mode When:

Choose Hybrid Mode When:

Examples

Development Workflow

Testing Strategy

Cost-Conscious Execution

Troubleshooting

Tool Backend Not Loading

Missing API Key in Real Mode

Unexpected Stub Data

Related Documentation