AI Agents Guide

Ralph Orchestrator supports multiple AI agents, each with unique capabilities and cost structures. This guide helps you choose and configure the right agent for your task.

Supported Agents

Claude (Anthropic)

Claude is Anthropic's advanced AI assistant, known for nuanced understanding and high-quality outputs.

Strengths:

• Excellent code generation and debugging
• Strong reasoning and analysis
• Comprehensive documentation writing
• Ethical and safe responses
• Large context window (200K tokens)

Best For:

• Complex software development
• Technical documentation
• Research and analysis
• Creative writing
• Problem-solving requiring deep reasoning

Installation:

npm install -g @anthropic-ai/claude-cli

Usage:

python ralph_orchestrator.py --agent claude

Cost:

• Input: $3.00 per million tokens
• Output: $15.00 per million tokens

Q Chat

Q Chat is a cost-effective AI assistant suitable for many general tasks, with a solid adapter implementation.

Strengths:

• Good general-purpose capabilities
• Fast response times with streaming support
• Cost-effective for simple tasks
• Reliable for straightforward operations
• Thread-safe concurrent message processing
• Robust error handling and recovery
• Graceful shutdown and resource cleanup

Best For:

• Simple coding tasks
• Basic documentation
• Data processing
• Quick prototypes
• Budget-conscious operations
• High-concurrency workloads
• Long-running batch processes

Installation:

pip install q-cli

Usage:

python ralph_orchestrator.py --agent q

# Short form
python ralph_orchestrator.py -a q

Operational Features:

• Message Queue: Thread-safe async message processing
• Error Recovery: Automatic retry with exponential backoff
• Signal Handling: Graceful shutdown on SIGINT/SIGTERM
• Resource Management: Proper cleanup of processes and threads
• Timeout Handling: Configurable timeouts with partial output preservation
• Non-blocking I/O: Prevents deadlocks in pipe communication
• Concurrent Processing: Handles multiple requests simultaneously

Cost:

• Input: $0.50 per million tokens (estimated)
• Output: $1.50 per million tokens (estimated)

Gemini (Google)

Google's Gemini offers strong capabilities with multimodal understanding.

Strengths:

• Excellent at data analysis
• Strong mathematical capabilities
• Good code understanding
• Multimodal capabilities (Pro version)
• Competitive pricing

Best For:

• Data science tasks
• Mathematical computations
• Code analysis
• Research tasks
• Multi-language support

Installation:

pip install google-generativeai

Usage:

python ralph_orchestrator.py --agent gemini

Cost:

• Input: $0.50 per million tokens
• Output: $1.50 per million tokens

ACP (Agent Client Protocol)

ACP enables integration with any agent that implements the Agent Client Protocol. This provides a standardized way to communicate with AI agents regardless of their underlying implementation.

Strengths:

• Works with any ACP-compliant agent
• Standardized JSON-RPC 2.0 protocol
• Flexible permission handling (4 modes)
• File and terminal operation support
• Session persistence via scratchpad
• Streaming update support

Best For:

• Using multiple agent backends
• Custom agent implementations
• Sandboxed execution environments
• CI/CD pipelines with controlled permissions
• Enterprise deployments with security requirements

Installation:

# Gemini CLI with ACP support
npm install -g @google/gemini-cli

# Any other ACP-compliant agent
# Follow the agent's installation instructions

Usage:

# Basic ACP usage with Gemini
python ralph_orchestrator.py --agent acp --acp-agent gemini

# With specific permission mode
python ralph_orchestrator.py --agent acp --acp-agent gemini --acp-permission-mode auto_approve

# Using allowlist mode
python ralph_orchestrator.py --agent acp --acp-permission-mode allowlist

Permission Modes:

Configuration (ralph.yml):

adapters:
  acp:
    enabled: true
    timeout: 300
    tool_permissions:
      agent_command: gemini
      agent_args: []
      permission_mode: auto_approve
      permission_allowlist:
        - "fs/read_text_file:*.py"
        - "fs/write_text_file:src/*"
        - "terminal/create:pytest*"

Environment Variables:

Supported Operations:

Cost:

• Input: $0.00 (billing handled by underlying agent)
• Output: $0.00 (billing handled by underlying agent)

Note: Claude CLI does not currently support native ACP mode. For Claude, use the native ClaudeAdapter (--agent claude) instead.

Auto-Detection

Ralph Orchestrator can automatically detect and use available agents:

python ralph_orchestrator.py --agent auto

Detection Order:

1. Claude (if installed)
2. Q Chat (if installed)
3. Gemini (if installed)

Agent Comparison

Choosing the Right Agent

Decision Tree

graph TD
    A[Select Agent] --> B{Task Type?}
    B -->|Complex Code| C[Claude]
    B -->|Simple Task| D{Budget?}
    B -->|Data Analysis| E[Gemini]
    B -->|Sandboxed/CI| K{Need Control?}
    D -->|Limited| F[Q Chat]
    D -->|Flexible| G[Claude/Gemini]
    B -->|Documentation| H{Quality Need?}
    H -->|High| I[Claude]
    H -->|Standard| J[Q Chat/Gemini]
    K -->|Yes| L[ACP]
    K -->|No| M[Any Agent]

Task-Agent Mapping

Agent Configuration

Claude Configuration

# Standard Claude usage
python ralph_orchestrator.py --agent claude

# With specific model
python ralph_orchestrator.py \\
  --agent claude \\
  --agent-args "--model claude-3-sonnet-20240229"

# With custom parameters
python ralph_orchestrator.py \\
  --agent claude \\
  --agent-args "--temperature 0.7 --max-tokens 4096"

Q Chat Configuration

# Standard Q usage
python ralph_orchestrator.py --agent q

# With custom parameters
python ralph_orchestrator.py \\
  --agent q \\
  --agent-args "--context-length 50000"

# Production configuration with enhanced settings
python ralph_orchestrator.py \\
  --agent q \\
  --max-iterations 100 \\
  --retry-delay 2 \\
  --checkpoint-interval 10 \\
  --verbose

# High-concurrency configuration
python ralph_orchestrator.py \\
  --agent q \\
  --agent-args "--async --timeout 300" \\
  --max-iterations 200

Environment Variables:

# Set Q chat timeout (default: 120 seconds)

# Enable verbose logging

# Configure retry attempts

Gemini Configuration

# Standard Gemini usage
python ralph_orchestrator.py --agent gemini

# With specific model
python ralph_orchestrator.py \\
  --agent gemini \\
  --agent-args "--model gemini-pro"

ACP Configuration

# Standard ACP usage with Gemini
python ralph_orchestrator.py --agent acp --acp-agent gemini

# With custom permission mode
python ralph_orchestrator.py \\
  --agent acp \\
  --acp-agent gemini \\
  --acp-permission-mode allowlist

# Production configuration
python ralph_orchestrator.py \\
  --agent acp \\
  --acp-agent gemini \\
  --acp-permission-mode auto_approve \\
  --max-iterations 100 \\
  --checkpoint-interval 10 \\
  --verbose

Configuration File (ralph.yml):

adapters:
  acp:
    enabled: true
    timeout: 300
    tool_permissions:
      agent_command: gemini
      agent_args: ["--experimental-acp"]
      permission_mode: auto_approve
      permission_allowlist: []

Environment Variables:

# Override agent command

# Override permission mode

# Override timeout

Agent-Specific Features

Claude Features

• Constitutional AI: Built-in safety and ethics
• Code Understanding: Deep comprehension of complex codebases
• Long Context: Handles up to 200K tokens
• Nuanced Responses: Understands subtle requirements

# Leverage Claude's long context
python ralph_orchestrator.py \\
  --agent claude \\
  --context-window 200000 \\
  --context-threshold 0.9

Q Chat Features

• Speed: Fast response times with streaming support
• Efficiency: Lower resource usage with optimized memory management
• Simplicity: Straightforward for basic tasks
• Concurrency: Thread-safe operations for parallel processing
• Reliability: Automatic error recovery and retry mechanisms
• Operational Reliability: Signal handling, graceful shutdown, resource cleanup

Operational Capabilities:

# Quick iterations with Q
python ralph_orchestrator.py \\
  --agent q \\
  --max-iterations 100 \\
  --retry-delay 1

# Async execution with timeout
python ralph_orchestrator.py \\
  --agent q \\
  --agent-args "--async --timeout 300" \\
  --checkpoint-interval 10

# Stress testing configuration
python ralph_orchestrator.py \\
  --agent q \\
  --max-iterations 500 \\
  --metrics-interval 10 \\
  --verbose

# Long-running batch processing
python ralph_orchestrator.py \\
  --agent q \\
  --checkpoint-interval 5 \\
  --max-cost 50.0 \\
  --retry-delay 5

Monitoring and Logging:

• Thread-safe logging for concurrent operations
• Detailed error messages with stack traces
• Performance metrics collection
• Resource usage tracking
• Message queue status monitoring

Gemini Features

• Data Excellence: Superior at data tasks
• Mathematical Prowess: Strong calculation abilities
• Multi-language: Good support for various programming languages

# Data processing with Gemini
python ralph_orchestrator.py \\
  --agent gemini \\
  --prompt data_analysis.md

ACP Features

• Protocol Standardization: JSON-RPC 2.0 communication
• Permission Control: Four modes for fine-grained access control
• File Operations: Secure read/write with path validation
• Terminal Operations: Full subprocess lifecycle management
• Session Persistence: Scratchpad for cross-iteration context
• Streaming Updates: Real-time agent output and thoughts

Permission Mode Examples:

# Auto-approve all requests (CI/CD)
python ralph_orchestrator.py \\
  --agent acp \\
  --acp-agent gemini \\
  --acp-permission-mode auto_approve

# Deny all requests (testing)
python ralph_orchestrator.py \\
  --agent acp \\
  --acp-agent gemini \\
  --acp-permission-mode deny_all

# Interactive approval (development)
python ralph_orchestrator.py \\
  --agent acp \\
  --acp-agent gemini \\
  --acp-permission-mode interactive

Allowlist Pattern Examples:

# ralph.yml
adapters:
  acp:
    tool_permissions:
      permission_mode: allowlist
      permission_allowlist:
        # Exact match
        - "fs/read_text_file"
        # Glob patterns
        - "fs/*"
        - "terminal/create:pytest*"
        # Regex patterns (surrounded by slashes)
        - "/^fs\\\\/.*$/"

Agent Scratchpad: All agents maintain context across iterations via a scratchpad file (.agent/scratchpad.md by default):

• Persists progress from previous iterations
• Records decisions and context
• Tracks current blockers or issues
• Lists remaining work items

In hat-based configurations, each hat can have its own scratchpad via the scratchpad config option — set a custom path, disable it entirely, or inherit from core.scratchpad. See Per-Hat Scratchpads for details.

# The scratchpad is automatically managed
cat .agent/scratchpad.md

Multi-Agent Strategies

Sequential Processing

Process with different agents for different phases:

# Phase 1: Research with Claude
python ralph_orchestrator.py --agent claude --prompt research.md

# Phase 2: Implementation with Q
python ralph_orchestrator.py --agent q --prompt implement.md

# Phase 3: Documentation with Claude
python ralph_orchestrator.py --agent claude --prompt document.md

Cost Optimization

Start with cheaper agents, escalate if needed:

# Try Q first
python ralph_orchestrator.py --agent q --max-cost 2.0

# If unsuccessful, try Claude
python ralph_orchestrator.py --agent claude --max-cost 20.0

Agent Performance Tuning

Claude Optimization

# Optimized for quality
python ralph_orchestrator.py \\
  --agent claude \\
  --max-iterations 50 \\
  --checkpoint-interval 5 \\
  --context-window 200000

# Optimized for speed
python ralph_orchestrator.py \\
  --agent claude \\
  --max-iterations 20 \\
  --retry-delay 1

Q Chat Optimization

# Maximum efficiency
python ralph_orchestrator.py \\
  --agent q \\
  --max-iterations 200 \\
  --checkpoint-interval 20 \\
  --metrics-interval 50

Ge