ai-agents 0.1.1 → 0.1.3

data/docs/concepts/handoffs.md

@@ -0,0 +1,81 @@
+---
+layout: default
+title: Handoffs
+parent: Concepts
+nav_order: 4
+---
+
+# Handoffs
+
+**Handoffs** are a powerful feature of the Ruby Agents library that allow you to build sophisticated multi-agent systems. A handoff is the process of transferring a conversation from one agent to another, more specialized agent.
+
+This is particularly useful when you have a general-purpose agent that can handle a wide range of queries, but you also have specialized agents that are better equipped to handle specific tasks. For example, you might have a triage agent that routes users to a billing agent or a technical support agent.
+
+## How Handoffs Work
+
+Handoffs are implemented as a special type of tool called a `HandoffTool`. When you configure an agent with `handoff_agents`, the library automatically creates a `HandoffTool` for each of the specified agents.
+
+Here's how the handoff process works:
+
+1.  **The user sends a message:** The user sends a message that indicates they need help with a specific task (e.g., "I have a problem with my bill").
+2.  **The LLM decides to hand off:** The current agent's language model determines that the query is best handled by another agent and decides to call the corresponding `HandoffTool`.
+3.  **The `HandoffTool` signals the handoff:** The `HandoffTool` sets a `pending_handoff` flag in the `RunContext`, indicating which agent to hand off to.
+4.  **The Runner switches agents:** The `Runner` detects the `pending_handoff` flag and switches the `current_agent` to the new agent.
+5.  **The conversation continues:** The conversation continues with the new agent, which now has access to the full conversation history.
+
+### Loop Prevention
+
+To prevent infinite handoff loops, the library automatically processes only the first handoff tool call in any LLM response. If multiple handoff tools are called in a single response, only the first one is executed and subsequent calls are ignored. This prevents conflicting handoff states and ensures clean agent transitions.
+
+## Why Use Tools for Handoffs?
+
+Using tools for handoffs has several advantages over simply instructing the LLM to hand off the conversation:
+
+*   **Reliability:** LLMs are very good at using tools when they are available. By representing handoffs as tools, we can be more confident that the LLM will use them when appropriate.
+*   **Clarity:** The tool's schema clearly defines when each handoff is suitable, making it easier for the LLM to make the right decision.
+*   **Simplicity:** We don't need to parse free-text responses from the LLM to determine if a handoff is needed.
+*   **Consistency:** This approach works consistently across different LLM providers.
+
+## Example
+
+```ruby
+# Create the specialized agents
+billing_agent = Agents::Agent.new(name: "Billing", instructions: "Handle billing and payment issues.")
+support_agent = Agents::Agent.new(name: "Support", instructions: "Provide technical support.")
+
+# Create the triage agent with handoff agents
+triage_agent = Agents::Agent.new(
+  name: "Triage",
+  instructions: "You are a triage agent. Your job is to route users to the correct department.",
+  handoff_agents: [billing_agent, support_agent]
+)
+
+# Run the triage agent
+result = Agents::Runner.run(triage_agent, "I have a problem with my bill.")
+
+# The runner will automatically hand off to the billing agent
+```
+
+In this example, the `triage_agent` will automatically hand off the conversation to the `billing_agent` when the user asks a question about their bill. This allows you to create a seamless user experience where the user is always talking to the most qualified agent for their needs.
+
+## Troubleshooting Handoffs
+
+### Infinite Handoff Loops
+
+**Problem:** Agents keep handing off to each other in an endless loop.
+
+**Common Causes:**
+- Agent instructions that conflict with each other
+- Agents configured to hand off for overlapping scenarios
+- Poor instruction clarity about when to hand off vs. when to handle directly
+
+**Solutions:**
+1. **Review agent instructions:** Ensure each agent has a clear, distinct responsibility
+2. **Use hub-and-spoke pattern:** Have specialized agents only hand off back to a central triage agent
+3. **Add specific scenarios:** Include examples in instructions of when to handle vs. hand off
+4. **Enable debug logging:** Use `ENV["RUBYLLM_DEBUG"] = "true"` to see handoff decisions
+
+
+### Multiple Handoffs in One Response
+
+The library automatically handles cases where an LLM tries to call multiple handoff tools in a single response. Only the first handoff will be processed, and subsequent calls will be ignored. This is normal behavior and prevents conflicting handoff states.

data/docs/concepts/runner.md

@@ -0,0 +1,87 @@
+---
+layout: default
+title: Runner
+parent: Concepts
+nav_order: 5
+---
+
+# AgentRunner
+
+The **AgentRunner** is the thread-safe execution manager that provides the main API for multi-agent conversations. It separates agent registry management from execution, enabling safe concurrent use across multiple threads while maintaining conversation continuity.
+
+## Two-Tier Architecture
+
+The library uses a two-tier design separating long-lived configuration from short-lived execution:
+
+### AgentRunner (Thread-Safe Manager)
+- Created once at application startup
+- Maintains immutable agent registry
+- Determines conversation continuity from history
+- Thread-safe for concurrent conversations
+
+### Runner (Internal Execution Engine)
+- Created per conversation turn
+- Handles LLM communication and tool execution
+- Manages context state during execution
+- Stateless and garbage-collected after use
+
+## Conversation Flow
+
+Each conversation follows this flow:
+
+1. **Agent Selection**: AgentRunner determines current agent from conversation history
+2. **Context Isolation**: Creates deep copy of context for thread safety
+3. **LLM Communication**: Sends message with context to language model
+4. **Tool Execution**: Executes any requested tools through RubyLLM
+5. **Handoff Detection**: Checks for agent handoffs and switches if needed
+6. **State Persistence**: Updates context with conversation state
+
+## Thread Safety
+
+The AgentRunner ensures thread safety through several key mechanisms:
+
+*   **Immutable Registry**: Agent registry is frozen after initialization, preventing runtime modifications
+*   **Context Isolation**: Each execution receives a deep copy of context to prevent cross-contamination
+*   **Stateless Execution**: Internal Runner instances store no execution-specific state
+*   **Tool Wrapping**: ToolWrapper injects context through parameters, keeping tools stateless
+
+## Usage Pattern
+
+Create an AgentRunner once and reuse it for multiple conversations:
+
+```ruby
+# Create agents
+triage_agent = Agents::Agent.new(
+  name: "Triage",
+  instructions: "Route users to appropriate specialists"
+)
+billing_agent = Agents::Agent.new(
+  name: "Billing", 
+  instructions: "Handle billing inquiries"
+)
+
+# Register handoffs
+triage_agent.register_handoffs(billing_agent)
+
+# Create runner once (thread-safe)
+runner = Agents::Runner.with_agents(triage_agent, billing_agent)
+
+# Use from multiple threads safely
+result1 = runner.run("I have a billing question")
+result2 = runner.run("Follow up", context: result1.context)
+```
+
+## Conversation Continuity
+
+The AgentRunner automatically maintains conversation continuity by analyzing message history to determine which agent should handle each turn:
+
+```ruby
+# First message -> Uses triage agent (default entry point)
+result1 = runner.run("I need help with my bill")
+
+# Triage hands off to billing agent
+# Next message -> AgentRunner detects billing agent should continue
+result2 = runner.run("What payment methods do you accept?", context: result1.context)
+```
+
+The `run` method returns a `RunResult` with output, conversation history, usage metrics, and updated context.

data/docs/concepts/tools.md

@@ -0,0 +1,62 @@
+---
+layout: default
+title: Tools
+parent: Concepts
+nav_order: 2
+---
+
+# Tools
+
+**Tools** are the components that allow agents to interact with the outside world. They are the primary way to extend an agent's capabilities beyond what the language model can do on its own. A tool can be anything from a simple calculator to a complex integration with an external API.
+
+In Ruby Agents, tools are designed to be thread-safe and stateless. This is a critical design principle that ensures the stability and reliability of your agent system, especially in concurrent environments.
+
+## Thread-Safe Design
+
+The key to the thread-safe design of tools is that they do not store any execution-specific state in their instance variables. All the data a tool needs to perform its action is passed to it through the `perform` method, which receives a `ToolContext` object.
+
+### The `ToolContext`
+
+The `ToolContext` provides access to the current execution context, including:
+
+*   **Shared context data:** A hash of data that is shared across all tools and agents in a given run.
+*   **Usage tracking:** An object that tracks token usage for the current run.
+*   **Retry count:** The number of times the current tool execution has been retried.
+
+By passing all the necessary data through the `ToolContext`, we ensure that tool instances can be safely shared across multiple threads without the risk of data corruption.
+
+## Creating a Tool
+
+You can create a tool in two ways:
+
+1.  **Creating a Tool Class:** For more complex tools, you can create a class that inherits from `Agents::Tool` and implements the `perform` method.
+
+    ```ruby
+    class WeatherTool < Agents::Tool
+      name "get_weather"
+      description "Get the current weather for a location."
+      param :location, type: "string", desc: "The city and state, e.g., San Francisco, CA"
+
+      def perform(tool_context, location:)
+        # Access the API key from the shared context
+        api_key = tool_context.context[:weather_api_key]
+
+        # Call the weather API and return the result
+        WeatherApi.get(location, api_key)
+      end
+    end
+    ```
+
+2.  **Using the Functional Tool Definition:** For simpler tools, you can use the `Agents::Tool.tool` helper to define a tool with a block.
+
+    ```ruby
+    calculator_tool = Agents::Tool.tool(
+      "calculate",
+      description: "Perform a mathematical calculation."
+    ) do |tool_context, expression:|
+      # Perform the calculation and return the result
+      eval(expression).to_s
+    end
+    ```
+
+In both cases, the `perform` method receives the `tool_context` and the tool's parameters as arguments. This design ensures that your tools are always thread-safe and easy to test.

data/docs/concepts.md

@@ -0,0 +1,21 @@
+---
+layout: default
+title: Concepts
+nav_order: 2
+has_children: true
+---
+
+# Concepts
+
+This section covers the core concepts of the AI Agents library. Understanding these concepts is essential for building robust and scalable AI agent systems.
+
+## Overview
+
+The AI Agents library is built around several key concepts that work together to provide a powerful framework for multi-agent AI workflows:
+
+- **[Agents](concepts/agents.html)** - Immutable, thread-safe AI assistants with specific roles and capabilities
+- **[AgentRunner](concepts/runner.html)** - Thread-safe execution manager for multi-agent conversations
+- **[Context](concepts/context.html)** - Serializable state management that persists across agent interactions
+- **[Handoffs](concepts/handoffs.html)** - Tool-based mechanism for seamless agent transitions
+- **[Tools](concepts/tools.html)** - Stateless extensions for external system integration
+- **[AgentTool](concepts/agent-tool.html)** - Agent-to-agent collaboration without conversation handoffs

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)