ai-agents 0.1.2 → 0.2.0

data/docs/concepts/agent-tool.md

@@ -0,0 +1,166 @@
+---
+layout: default
+title: AgentTool
+parent: Concepts
+nav_order: 6
+---
+
+# AgentTool
+
+The `AgentTool` class enables **agent-to-agent collaboration** by wrapping agents as callable tools. This pattern allows specialized agents to work behind the scenes to help each other without conversation handoffs.
+
+## Key Concept
+
+Unlike handoffs where control transfers between agents with full conversation context, AgentTool creates **constrained execution environments** where wrapped agents:
+
+- Cannot perform handoffs (empty registry)
+- Have limited turn counts to prevent infinite loops
+- Only receive shared state, not conversation history
+- Always return control to the calling agent
+
+## Architecture
+
+```ruby
+# Specialized agents as tools
+research_agent = Agent.new(
+  name: "Research Agent",
+  instructions: "Research topics and extract key information"
+)
+
+analysis_agent = Agent.new(
+  name: "Analysis Agent",
+  instructions: "Analyze data and provide insights"
+)
+
+# Main orchestrator uses other agents as tools
+orchestrator = Agent.new(
+  name: "Orchestrator",
+  instructions: "Coordinate research and analysis",
+  tools: [
+    research_agent.as_tool(
+      name: "research_topic",
+      description: "Research a specific topic"
+    ),
+    analysis_agent.as_tool(
+      name: "analyze_data",
+      description: "Analyze research findings"
+    )
+  ]
+)
+```
+
+## Implementation Details
+
+### Constraints
+
+AgentTool implements several safety constraints:
+
+1. **No Handoffs**: Wrapped agents receive an empty registry, preventing handoff calls
+2. **Limited Turns**: Maximum 3 turns to prevent infinite loops
+3. **Context Isolation**: Only shared state is passed, not conversation history
+4. **Return Control**: Always returns to the calling agent
+
+### Context Isolation
+
+```ruby
+# Parent context (full conversation state)
+parent_context = {
+  state: { user_id: 123, session: "abc" },
+  conversation_history: [...],
+  current_agent: "MainAgent",
+  turn_count: 5
+}
+
+# Isolated context (only state)
+isolated_context = {
+  state: { user_id: 123, session: "abc" }
+}
+```
+
+### Error Handling
+
+AgentTool provides robust error handling:
+
+- Execution failures return descriptive error messages
+- Runtime exceptions are caught and reported
+- Missing output is handled gracefully
+
+## Usage Patterns
+
+### Customer Support Copilot
+
+```ruby
+# Specialized agents for different domains
+conversation_analyzer = Agent.new(
+  name: "ConversationAnalyzer",
+  instructions: "Extract order IDs and customer intent"
+)
+
+shopify_agent = Agent.new(
+  name: "ShopifyAgent",
+  instructions: "Perform Shopify operations",
+  tools: [shopify_refund_tool, shopify_lookup_tool]
+)
+
+# Main copilot coordinates specialized agents
+copilot = Agent.new(
+  name: "SupportCopilot",
+  instructions: "Help support agents with customer requests",
+  tools: [
+    conversation_analyzer.as_tool(
+      name: "analyze_conversation",
+      description: "Extract key information from conversation"
+    ),
+    shopify_agent.as_tool(
+      name: "shopify_action",
+      description: "Perform Shopify operations"
+    )
+  ]
+)
+```
+
+## Output Transformation
+
+AgentTool supports custom output extractors for transforming results:
+
+```ruby
+# Custom output extraction
+summarizer = Agent.new(
+  name: "Summarizer",
+  instructions: "Summarize long content"
+)
+
+summarizer_tool = summarizer.as_tool(
+  name: "summarize",
+  description: "Create a summary",
+  output_extractor: ->(result) {
+    "SUMMARY: #{result.output&.first(200)}..."
+  }
+)
+```
+
+## Best Practices
+
+1. **Keep it Simple**: Use AgentTool for focused, single-purpose tasks
+2. **Avoid Deep Nesting**: Don't create agents that use agents that use agents
+3. **State Management**: Only share necessary state between agents
+4. **Error Handling**: Always handle potential execution failures
+5. **Performance**: Consider the overhead of multiple agent calls
+
+## Comparison with Handoffs
+
+| Aspect | AgentTool | Handoff |
+|--------|-----------|---------|
+| **Purpose** | Behind-the-scenes collaboration | User-facing conversation transfer |
+| **Context** | Isolated (state only) | Full conversation history |
+| **Control** | Returns to caller | Transfers to target |
+| **Constraints** | Limited turns, no handoffs | Full agent capabilities |
+| **Use Case** | Internal processing | Conversation routing |
+
+## See Also
+
+<!-- - [Agent-as-Tool Pattern Guide](../guides/agent-as-tool-pattern.html)
+- [Multi-Agent Systems](../guides/multi-agent-systems.html) -->
+
+- [Tools Concept](tools.html)
+- [Handoffs Concept](handoffs.html)

data/docs/concepts/agents.md

@@ -0,0 +1,43 @@
+---
+layout: default
+title: Agents
+parent: Concepts
+nav_order: 1
+---
+
+# Agents
+
+An **Agent** is the fundamental building block of the library. It represents an AI assistant with a specific set of capabilities, defined by its instructions, tools, and the underlying language model it uses.
+
+Agents are immutable and thread-safe by design. Once created, their configuration cannot be changed, ensuring safe sharing across multiple threads without race conditions. Agents can have dynamic instructions using Proc objects that receive runtime context.
+
+{: .note }
+This project is in early development. While thread safety is a core design goal and the architecture is built around it, complete thread safety is not yet guaranteed. We're actively working toward this goal.
+
+### Key Attributes of an Agent
+
+*   **`name`**: A unique name for the agent, used for identification and in handoffs.
+*   **`instructions`**: The system prompt that guides the agent's behavior. This can be a static string or a `Proc` that dynamically generates instructions based on the current context.
+*   **`model`**: The language model the agent will use (e.g., `"gpt-4.1-mini"`).
+*   **`tools`**: An array of `Agents::Tool` instances that the agent can use to perform actions.
+*   **`handoff_agents`**: An array of other agents that this agent can hand off conversations to.
+
+### Example
+
+```ruby
+# Create a simple agent
+assistant_agent = Agents::Agent.new(
+  name: "Assistant",
+  instructions: "You are a helpful assistant.",
+  model: "gpt-4.1-mini",
+  tools: [CalculatorTool.new]
+)
+
+# Create a specialized agent by cloning the base agent
+specialized_agent = assistant_agent.clone(
+  instructions: "You are a specialized assistant for financial calculations.",
+  tools: assistant_agent.tools + [FinancialDataTool.new]
+)
+```
+
+In this example, we create a base `assistant_agent` and then create a `specialized_agent` by cloning it and adding a new tool. This approach allows for easy composition and reuse of agent configurations.

data/docs/concepts/callbacks.md

@@ -0,0 +1,42 @@
+---
+layout: default
+title: Callbacks
+parent: Concepts
+nav_order: 6
+---
+
+# Real-time Callbacks
+
+The AI Agents SDK provides real-time callbacks that allow you to monitor agent execution as it happens. This is particularly useful for building user interfaces that show live feedback about what agents are doing.
+
+## Available Callbacks
+
+The SDK provides four types of callbacks that give you visibility into different stages of agent execution:
+
+**Agent Thinking** - Triggered when an agent is about to make an LLM call. Useful for showing "thinking" indicators in UIs.
+
+**Tool Start** - Called when an agent begins executing a tool. Shows which tool is being used and with what arguments.
+
+**Tool Complete** - Triggered when a tool finishes execution. Provides the tool name and result for status updates.
+
+**Agent Handoff** - Called when control transfers between agents. Shows the source agent, target agent, and handoff reason.
+
+## Basic Usage
+
+Callbacks are registered on the AgentRunner using chainable methods:
+
+```ruby
+runner = Agents::AgentRunner.with_agents(triage, support)
+  .on_agent_thinking { |agent, input| puts "#{agent} thinking..." }
+  .on_tool_start { |tool, args| puts "Using #{tool}" }
+  .on_tool_complete { |tool, result| puts "#{tool} completed" }
+  .on_agent_handoff { |from, to, reason| puts "#{from} → #{to}" }
+```
+
+## Integration Patterns
+
+Callbacks work well with real-time web frameworks like Rails ActionCable, allowing you to stream agent status updates directly to browser clients. They're also useful for logging, metrics collection, and building debug interfaces.
+
+## Thread Safety
+
+Callbacks execute synchronously in the same thread as agent execution. Exceptions in callbacks are caught and logged as warnings without interrupting agent operation. For heavy operations or external API calls, consider using background jobs triggered by the callbacks.

data/docs/concepts/context.md

@@ -0,0 +1,110 @@
+---
+layout: default
+title: Context
+parent: Concepts
+nav_order: 3
+---
+
+# Context
+
+**Context** is the serializable state management system that preserves information across agent interactions, tool executions, and handoffs. Context enables conversation continuity and cross-session persistence through a simple hash-based structure.
+
+## Context Architecture
+
+Context flows through multiple abstraction layers:
+
+### User Context (Serializable)
+The main context hash that persists across sessions:
+```ruby
+context = {
+  user_id: 123,
+  conversation_history: [...],
+  current_agent_name: "Billing",
+  state: { customer_tier: "premium" }  # Tools use this nested hash for persistent data
+}
+```
+
+### RunContext (Execution Wrapper)
+Wraps user context with execution-specific features:
+- **Context Hash**: Shared data accessible to all tools and agents
+- **Thread Safety**: Deep copying ensures execution isolation
+
+### ToolContext (Tool-Specific View)
+Provides tools with controlled access to execution state:
+- **Context Access**: Read/write access to shared context hash
+- **State Management**: Dedicated space for persistent tool state
+
+## The `ToolContext`
+
+The `ToolContext` is a wrapper around the `RunContext` that is passed to each tool when it is executed. It provides the tool with controlled access to the execution state, including the shared context hash.
+
+By passing the context through the `ToolContext`, we ensure that tools can remain stateless and thread-safe, as they do not need to store any execution-specific state in their instance variables.
+
+## Context Serialization
+
+Context is fully serializable for persistence across process boundaries:
+
+```ruby
+# Run conversation
+result = runner.run("Hello, I'm John")
+
+# Serialize for storage
+context_json = result.context.to_json
+# Store in database, file, session, etc.
+
+# Later: restore and continue
+restored_context = JSON.parse(context_json, symbolize_names: true)
+next_result = runner.run("What's my name?", context: restored_context)
+# => "Your name is John"
+```
+
+## Conversation Continuity
+
+The AgentRunner automatically manages conversation continuity through context:
+
+```ruby
+# Create runner
+runner = Agents::Runner.with_agents(triage_agent, billing_agent)
+
+# First interaction
+result1 = runner.run("I need billing help")
+# Triage agent hands off to billing agent
+# Context includes: current_agent_name: "Billing"
+
+# Continue conversation
+result2 = runner.run("What payment methods do you accept?", context: result1.context)
+# AgentRunner detects billing agent should continue based on context
+```
+
+## State Management
+
+Tools can use the context for persistent state:
+
+```ruby
+class CustomerLookupTool < Agents::Tool
+  def perform(tool_context, customer_id:)
+    customer = Customer.find(customer_id)
+    
+    # Store in shared state for other tools
+    tool_context.state[:customer_id] = customer_id
+    tool_context.state[:customer_name] = customer.name
+    tool_context.state[:account_type] = customer.account_type
+    
+    "Found customer: #{customer.name}"
+  end
+end
+
+class BillingTool < Agents::Tool
+  def perform(tool_context)
+    # Access state from previous tool
+    customer_id = tool_context.state[:customer_id]
+    account_type = tool_context.state[:account_type]
+    
+    return "No customer found" unless customer_id
+    
+    # Use customer info for billing operations
+    billing_info = get_billing_info(customer_id, account_type)
+    billing_info.to_s
+  end
+end
+```

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,22 @@
+---
+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
+- **[Callbacks](concepts/callbacks.html)** - Real-time notifications for agent thinking, tool execution, and handoffs
+- **[AgentTool](concepts/agent-tool.html)** - Agent-to-agent collaboration without conversation handoffs