ai-agents 0.1.2 → 0.2.0

data/docs/guides/agent-as-tool-pattern.md

@@ -0,0 +1,242 @@
+---
+layout: default
+title: Agent-as-Tool Pattern
+parent: Guides
+nav_order: 4
+---
+
+# Agent-as-Tool Pattern Guide
+
+The Agent-as-Tool pattern enables **multi-agent collaboration** where specialized agents work behind the scenes to help each other, without the user knowing multiple agents are involved.
+
+## When to Use This Pattern
+
+Use Agent-as-Tool when you need:
+
+- **Specialized Processing**: Different agents excel at different tasks
+- **Behind-the-Scenes Coordination**: Agents collaborate invisibly to the user
+- **Multi-step Workflows**: Complex processes requiring different expertise
+- **Modular Architecture**: Clean separation of concerns between agents
+
+## Core Concept
+
+### Handoffs vs Agent-as-Tool
+
+**Handoffs**: "Let me transfer you to billing"
+- User-visible conversation transfer
+- Full context shared
+- Agent takes over conversation
+
+**Agent-as-Tool**: "Let me check that for you" (uses billing agent internally)
+- Invisible to user
+- Limited context (state only)
+- Returns control to caller
+
+## Basic Implementation
+
+### Step 1: Create Specialized Agents
+
+```ruby
+# Research agent - finds customer information
+research_agent = Agents::Agent.new(
+  name: "ResearchAgent",
+  instructions: <<~PROMPT
+    You research customer information and history.
+    Return contact details including email addresses.
+  PROMPT,
+  tools: [customer_lookup_tool, conversation_search_tool]
+)
+
+# Billing agent - handles payment operations
+billing_agent = Agents::Agent.new(
+  name: "BillingAgent",
+  instructions: <<~PROMPT
+    You handle billing operations using Stripe.
+    CRITICAL: You need customer email addresses for billing lookups.
+    Contact IDs will NOT work.
+  PROMPT,
+  tools: [stripe_billing_tool]
+)
+```
+
+### Step 2: Create Orchestrator with Agent Tools
+
+```ruby
+# Main agent coordinates specialists
+orchestrator = Agents::Agent.new(
+  name: "SupportCopilot",
+  instructions: <<~PROMPT
+    You help support agents by coordinating specialist agents.
+
+    **CRITICAL: Multi-Step Workflow Approach**
+
+    For complex queries, break them into steps and use tools sequentially:
+    1. Plan your approach: What information do you need?
+    2. Execute sequentially: Use EXACT results from previous tools
+    3. Build context progressively: Each tool builds on previous findings
+
+    **Tool Requirements:**
+    - research_customer: Returns contact details including emails
+    - check_billing: Requires customer email (not contact ID)
+
+    Always think: "What did I learn and how do I use it next?"
+  PROMPT,
+  tools: [
+    research_agent.as_tool(
+      name: "research_customer",
+      description: "Research customer details. Returns contact info including email."
+    ),
+    billing_agent.as_tool(
+      name: "check_billing",
+      description: "Check billing status. Requires customer email address."
+    )
+  ]
+)
+```
+
+### Step 3: Use with Context Persistence
+
+```ruby
+# Set up runner with context persistence
+runner = Agents::Runner.with_agents(orchestrator)
+context = {}
+
+# Interactive loop maintains context
+loop do
+  user_input = gets.chomp
+  break if user_input == "exit"
+
+  # Pass and update context each turn
+  result = runner.run(user_input, context: context)
+  context = result.context if result.context
+
+  puts result.output
+end
+```
+
+## Advanced Features
+
+### Custom Output Extraction
+
+Extract specific information for other tools:
+
+```ruby
+research_agent.as_tool(
+  name: "get_customer_email",
+  description: "Get customer email address",
+  output_extractor: ->(result) {
+    # Extract just the email instead of full response
+    email_match = result.output.match(/Email:\s*([^\s]+)/i)
+    email_match&.captures&.first || "Email not found"
+  }
+)
+```
+
+## Best Practices
+
+### 1. Clear Tool Descriptions with Requirements
+
+Specify what each tool needs and provides:
+
+```ruby
+# Good: Clear requirements
+billing_agent.as_tool(
+  name: "check_stripe_billing",
+  description: "Check Stripe billing info. Requires customer email (not contact ID)."
+)
+
+research_agent.as_tool(
+  name: "research_customer",
+  description: "Research customer details. Returns email address and contact info."
+)
+
+# Avoid: Vague descriptions
+agent.as_tool(name: "process", description: "Do stuff")
+```
+
+### 2. Multi-Step Workflow Instructions
+
+Guide orchestrators to chain tool calls properly:
+
+```ruby
+orchestrator = Agent.new(
+  instructions: <<~PROMPT
+    **For complex queries requiring multiple pieces of information:**
+
+    1. Plan what information you need to gather
+    2. Use tools sequentially, building on previous results
+    3. Extract specific values from tool outputs for subsequent calls
+    4. Don't pass original parameters - use discovered values
+
+    **Example:** To check billing for CONTACT-123:
+    Step 1: research_customer("Get details for CONTACT-123") → finds email
+    Step 2: check_billing("Check billing for [discovered email]") → not original ID
+  PROMPT
+)
+```
+
+### 3. Explicit Parameter Requirements in Agent Instructions
+
+Make tool parameter needs crystal clear:
+
+```ruby
+billing_agent = Agent.new(
+  instructions: <<~PROMPT
+    **CRITICAL: Billing Requirements**
+    - Stripe billing lookups REQUIRE customer email addresses
+    - Contact IDs, names, phone numbers will NOT work
+    - If you don't have email, clearly state you need it
+  PROMPT
+)
+```
+
+### 4. Handle Errors with Guidance
+
+Provide helpful error messages that guide next steps:
+
+```ruby
+# In orchestrator instructions
+instructions = <<~PROMPT
+  **Error Handling:**
+  - If billing fails due to missing email: Use research_customer first
+  - If contact not found: Ask for more identifying information
+  - Always provide helpful responses even if tools fail
+PROMPT
+```
+
+### 5. Context Persistence for Multi-Turn Conversations
+
+Maintain state across conversation turns:
+
+```ruby
+# Maintain context between interactions
+runner = Agents::Runner.with_agents(orchestrator)
+context = {}
+
+# Each turn builds on previous context
+result = runner.run(user_input, context: context)
+context = result.context if result.context
+```
+
+### 6. Design Focused Agents
+
+Keep agent responsibilities clear and narrow:
+
+```ruby
+# Good: Focused responsibility
+customer_agent = Agent.new(
+  name: "CustomerAgent",
+  instructions: "Handle customer data lookups and history research"
+)
+
+# Avoid: Too broad
+everything_agent = Agent.new(
+  name: "EverythingAgent",
+  instructions: "Handle all customer operations, billing, support, and analysis"
+)
+```
+
+## See Also
+
+- [AgentTool Concept](../concepts/agent-tool.html)
+- [Multi-Agent Systems Guide](multi-agent-systems.html)

data/docs/guides/multi-agent-systems.md

@@ -0,0 +1,261 @@
+---
+layout: default
+title: Building Multi-Agent Systems
+parent: Guides
+nav_order: 1
+---
+
+# Building Multi-Agent Systems
+
+Multi-agent systems allow you to decompose complex problems into specialized agents that collaborate to provide comprehensive solutions. This guide covers patterns and best practices for designing effective multi-agent workflows.
+
+## Core Patterns
+
+### Hub-and-Spoke Architecture
+
+The most common and stable pattern is hub-and-spoke, where a central triage agent routes conversations to specialized agents:
+
+```ruby
+# Specialized agents
+billing_agent = Agents::Agent.new(
+  name: "Billing",
+  instructions: "Handle billing inquiries, payment processing, and account issues."
+)
+
+support_agent = Agents::Agent.new(
+  name: "Support", 
+  instructions: "Provide technical troubleshooting and product support."
+)
+
+# Central hub agent
+triage_agent = Agents::Agent.new(
+  name: "Triage",
+  instructions: "Route users to the appropriate specialist. Only hand off, don't solve problems yourself."
+)
+
+# Register handoffs (one-way: triage -> specialists)
+triage_agent.register_handoffs(billing_agent, support_agent)
+
+# Create runner with triage as entry point
+runner = Agents::AgentRunner.with_agents(triage_agent, billing_agent, support_agent)
+```
+
+### Dynamic Instructions
+
+Use Proc-based instructions to create context-aware agents:
+
+```ruby
+support_agent = Agents::Agent.new(
+  name: "Support",
+  instructions: ->(context) {
+    customer_tier = context[:customer_tier] || "standard"
+    <<~INSTRUCTIONS
+      You are a technical support specialist for #{customer_tier} tier customers.
+      #{customer_tier == "premium" ? "Provide priority white-glove service." : ""}
+      
+      Available tools: diagnostics, escalation
+    INSTRUCTIONS
+  }
+)
+```
+
+## Agent Design Principles
+
+### Clear Boundaries
+
+Each agent should have a distinct, non-overlapping responsibility:
+
+```ruby
+# GOOD: Clear specialization
+sales_agent = Agents::Agent.new(
+  name: "Sales",
+  instructions: "Handle product inquiries, pricing, and purchase decisions. Transfer technical questions to support."
+)
+
+support_agent = Agents::Agent.new(
+  name: "Support", 
+  instructions: "Handle technical issues and product troubleshooting. Transfer sales questions to sales team."
+)
+```
+
+### Avoiding Handoff Loops
+
+Design instructions to prevent infinite handoffs:
+
+```ruby
+# BAD: Conflicting handoff criteria
+agent_a = Agents::Agent.new(
+  instructions: "Handle X. If you need Y info, hand off to Agent B."
+)
+agent_b = Agents::Agent.new(
+  instructions: "Handle Y. If you need X context, hand off to Agent A."
+)
+
+# GOOD: Clear escalation hierarchy
+specialist = Agents::Agent.new(
+  instructions: "Handle specialized requests. Ask users for needed info directly."
+)
+triage = Agents::Agent.new(
+  instructions: "Route users to specialists. Don't solve problems yourself."
+)
+```
+
+## Conversation Flow Management
+
+### Entry Points
+
+The first agent in `AgentRunner.with_agents()` becomes the default entry point:
+
+```ruby
+# Triage agent handles all initial conversations
+runner = Agents::AgentRunner.with_agents(triage_agent, billing_agent, support_agent)
+
+# Start conversation
+result = runner.run("I need help with my account")
+# -> Automatically starts with triage_agent
+```
+
+### Context Preservation
+
+The AgentRunner automatically maintains conversation history across handoffs:
+
+```ruby
+# First interaction
+result1 = runner.run("My name is John and I have a billing question")
+# -> Triage agent hands off to billing agent
+
+# Continue conversation
+result2 = runner.run("What payment methods do you accept?", context: result1.context)
+# -> Billing agent remembers John's name and previous context
+```
+
+### Handoff Detection
+
+The system automatically determines the current agent from conversation history:
+
+```ruby
+# No need to manually specify which agent to use
+result = runner.run("Follow up question", context: previous_result.context)
+# -> AgentRunner automatically selects correct agent based on conversation state
+```
+
+## Advanced Patterns
+
+### Tool-Specific Agents
+
+Create agents specialized for particular tool categories:
+
+```ruby
+data_agent = Agents::Agent.new(
+  name: "DataAnalyst",
+  instructions: "Analyze data and generate reports using available analytics tools.",
+  tools: [DatabaseTool.new, ChartGeneratorTool.new, ReportTool.new]
+)
+
+communication_agent = Agents::Agent.new(
+  name: "Communications",
+  instructions: "Handle notifications and external communications.",
+  tools: [EmailTool.new, SlackTool.new, SMSTool.new]
+)
+```
+
+### Conditional Handoffs
+
+Use dynamic instructions to control handoff behavior:
+
+```ruby
+triage_agent = Agents::Agent.new(
+  name: "Triage",
+  instructions: ->(context) {
+    business_hours = context[:business_hours] || false
+    
+    base_instructions = "Route users to appropriate departments."
+    
+    if business_hours
+      base_instructions + " All departments are available."
+    else
+      base_instructions + " Only hand off urgent technical issues to support. Others should wait for business hours."
+    end
+  }
+)
+```
+
+## Testing Multi-Agent Systems
+
+### Unit Testing Individual Agents
+
+Test each agent in isolation:
+
+```ruby
+RSpec.describe "BillingAgent" do
+  let(:agent) { create_billing_agent }
+  let(:runner) { Agents::AgentRunner.with_agents(agent) }
+  
+  it "handles payment inquiries" do
+    result = runner.run("What payment methods do you accept?")
+    expect(result.output).to include("credit card", "bank transfer")
+  end
+end
+```
+
+### Integration Testing Handoffs
+
+Test complete workflows:
+
+```ruby
+RSpec.describe "Customer Support Workflow" do
+  let(:runner) { create_support_runner } # Creates triage + specialists
+  
+  it "routes billing questions correctly" do
+    result = runner.run("I have a billing question")
+    
+    # Verify handoff occurred
+    expect(result.context.current_agent_name).to eq("Billing")
+    
+    # Test continued conversation
+    followup = runner.run("What are your payment terms?", context: result.context)
+    expect(followup.output).to include("payment terms")
+  end
+end
+```
+
+## Common Pitfalls
+
+### Over-Specialization
+Don't create too many narrow agents - it increases handoff complexity and latency.
+
+### Under-Specified Instructions
+Vague instructions lead to inappropriate handoffs. Be explicit about what each agent should and shouldn't handle.
+
+### Circular Dependencies
+Avoid mutual handoffs between agents. Use hub-and-spoke or clear hierarchical patterns instead.
+
+### Context Leakage
+Don't rely on shared mutable state. Use the context hash for inter-agent communication.
+
+## Performance Considerations
+
+### Handoff Overhead
+Each handoff adds latency. Design agents to minimize unnecessary transfers.
+
+### Context Size
+Large contexts increase token usage. Clean up irrelevant data periodically:
+
+```ruby
+# Remove old conversation history
+cleaned_context = result.context.dup
+cleaned_context[:conversation_history] = cleaned_context[:conversation_history].last(10)
+```
+
+### Concurrent Execution
+AgentRunner is thread-safe, allowing multiple conversations simultaneously:
+
+```ruby
+# Safe to use same runner across threads
+threads = users.map do |user|
+  Thread.new do
+    user_result = runner.run(user.message, context: user.context)
+    # Handle result...
+  end
+end
+```