ai-agents 0.1.1 → 0.1.3

data/docs/architecture.md

@@ -0,0 +1,353 @@
+---
+layout: default
+title: Architecture
+nav_order: 4
+published: false
+---
+
+# Architecture
+
+The AI Agents library is designed around key principles of immutability, thread safety, and separation of concerns. This architecture enables scalable multi-agent systems that can handle concurrent conversations while maintaining state consistency.
+
+## Core Architecture Principles
+
+### Immutability by Design
+- **Agents are immutable** once created, preventing configuration drift
+- **Context is deep-copied** for each execution to prevent cross-contamination
+- **Registry is frozen** after initialization to prevent runtime modifications
+
+### Thread Safety
+- **No shared mutable state** between concurrent executions
+- **Context isolation** through deep copying and closure capture
+- **Stateless tool design** with context injection via parameters
+
+### Separation of Concerns
+- **Agent definition** (configuration) vs **Agent execution** (runtime)
+- **Tool functionality** vs **Tool context** (execution state)
+- **Conversation orchestration** vs **LLM communication**
+
+## Component Architecture
+
+### Two-Tier Execution Model
+
+The library uses a two-tier architecture separating long-lived configuration from short-lived execution:
+
+```
+┌─────────────────┐    ┌─────────────────┐
+│   AgentRunner   │    │     Runner      │
+│   (Long-lived)  │────▶│  (Per-request)  │
+│                 │    │                 │
+│ • Agent Registry│    │ • Execution     │
+│ • Entry Point   │    │ • Context Mgmt  │
+│ • Thread Safety │    │ • Handoff Logic │
+└─────────────────┘    └─────────────────┘
+```
+
+**AgentRunner** (Thread-Safe Manager):
+- Created once, reused for multiple conversations
+- Maintains immutable agent registry
+- Determines conversation continuity
+- Thread-safe for concurrent use
+
+**Runner** (Execution Engine):
+- Created per conversation turn
+- Handles LLM communication and tool execution
+- Manages context state during execution
+- Stateless and garbage-collected after use
+
+### Context Management Architecture
+
+Context flows through multiple abstraction layers:
+
+```
+┌─────────────────┐
+│   User Context  │ (Serializable across sessions)
+│                 │
+├─────────────────┤
+│   RunContext    │ (Execution isolation)
+│                 │
+├─────────────────┤
+│   ToolContext   │ (Tool-specific state)
+│                 │
+└─────────────────┘
+```
+
+**User Context**: Serializable hash for persistence
+**RunContext**: Execution wrapper with usage tracking
+**ToolContext**: Tool-specific view with retry metadata
+
+## Handoff Architecture
+
+### Tool-Based Handoff System
+
+Handoffs are implemented as specialized tools rather than instruction-parsing:
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Triage Agent  │    │  HandoffTool    │    │  Billing Agent  │
+│                 │    │                 │    │                 │
+│ • Instructions  │────▶│ • Target Agent  │────▶│ • Instructions  │
+│ • Handoff List  │    │ • Schema        │    │ • Specialized   │
+│ • General Role  │    │ • Execution     │    │ • Tools         │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+**Benefits of Tool-Based Handoffs**:
+- **Reliable invocation**: LLMs consistently use tools when available
+- **Clear semantics**: Tool schema explicitly defines handoff criteria
+- **No text parsing**: Eliminates need to parse free-form responses
+- **Provider agnostic**: Works consistently across OpenAI, Anthropic, etc.
+
+### First-Call-Wins Handoff Resolution
+
+To prevent infinite handoff loops, the system implements first-call-wins semantics:
+
+```
+LLM Response with Multiple Handoffs:
+┌─────────────────────────────────────┐
+│ Call 1: handoff_to_support()       │ ✓ Processed
+│ Call 2: handoff_to_billing()       │ ✗ Ignored
+│ Call 3: handoff_to_support()       │ ✗ Ignored
+└─────────────────────────────────────┘
+Result: Transfer to Support Agent only
+```
+
+This mirrors OpenAI's SDK behavior and prevents conflicting handoff states.
+
+## Thread Safety Implementation
+
+### Context Isolation Pattern
+
+Each execution receives an isolated context copy:
+
+```ruby
+# Thread-safe execution flow
+def run(input, context: {})
+  # 1. Deep copy context for isolation
+  context_copy = deep_copy_context(context)
+
+  # 2. Create execution wrapper
+  run_context = RunContext.new(context_copy)
+
+  # 3. Execute with isolated state
+  result = execute_with_context(run_context)
+
+  # 4. Return serializable result
+  return result
+end
+```
+
+### Tool Wrapper Pattern
+
+Tools remain stateless through the wrapper pattern:
+
+```ruby
+# Tool Definition (Stateless)
+class WeatherTool < Agents::Tool
+  def perform(tool_context, city:)
+    api_key = tool_context.context[:weather_api_key]
+    WeatherAPI.get(city, api_key)
+  end
+end
+
+# Runtime Wrapping (Context Injection)
+wrapped_tool = ToolWrapper.new(weather_tool, context_wrapper)
+```
+
+The wrapper captures context in its closure, injecting it during execution without modifying the tool instance.
+
+## Chat Architecture
+
+### Extended Chat System
+
+The library extends RubyLLM::Chat with handoff detection:
+
+```
+┌─────────────────┐    ┌─────────────────┐
+│   Agents::Chat  │    │  RubyLLM::Chat  │
+│   (Extended)    │────▶│   (Base)        │
+│                 │    │                 │
+│ • Handoff Detect│    │ • LLM Comm      │
+│ • Tool Classify │    │ • Tool Execution│
+│ • First-Call-Wins│   │ • Message Mgmt  │
+└─────────────────┘    └─────────────────┘
+```
+
+**Handoff Detection Flow**:
+1. Classify tool calls into handoff vs regular tools
+2. Execute first handoff only (first-call-wins)
+3. Return HandoffResponse to signal agent switch
+4. Execute regular tools normally with continuation
+
+### Conversation Continuity
+
+The system maintains conversation state through message attribution:
+
+```ruby
+# Messages include agent attribution
+{
+  role: :assistant,
+  content: "I can help with billing",
+  agent_name: "Billing"  # Enables conversation continuity
+}
+```
+
+AgentRunner uses this attribution to determine conversation ownership when resuming.
+
+## Provider Abstraction
+
+### RubyLLM Integration
+
+The library builds on RubyLLM for provider abstraction:
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   AI Agents     │    │    RubyLLM      │    │   Providers     │
+│                 │    │                 │    │                 │
+│ • Multi-Agent   │────▶│ • Unified API   │────▶│ • OpenAI        │
+│ • Handoffs      │    │ • Tool Calling  │    │ • Anthropic     │
+│ • Context Mgmt  │    │ • Streaming     │    │ • Gemini        │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+This abstraction allows switching between providers without changing agent logic.
+
+## State Management
+
+### Context Serialization
+
+The entire conversation state is serializable:
+
+```ruby
+# Serialize context for persistence
+context_json = result.context.to_json
+
+# Restore and continue conversation
+restored_context = JSON.parse(context_json, symbolize_names: true)
+next_result = runner.run("Continue conversation", context: restored_context)
+```
+
+**Serialization includes**:
+- Conversation history with agent attribution
+- Current agent state
+- Tool-specific state
+- User-defined context data
+
+### State Persistence Patterns
+
+The library supports multiple persistence patterns:
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   In-Memory     │    │   File-Based    │    │   Database      │
+│                 │    │                 │    │                 │
+│ • Development   │    │ • Simple Deploy │    │ • Production    │
+│ • Testing       │    │ • Single Server │    │ • Multi-Server  │
+│ • Rapid Iteration│   │ • File Storage  │    │ • ActiveRecord  │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+All patterns use the same serialization format for consistency.
+
+## Performance Characteristics
+
+### Memory Management
+
+- **Immutable objects** are shared safely across threads
+- **Context copies** are garbage-collected after execution
+- **Tool instances** are reused without state accumulation
+
+### Execution Efficiency
+
+- **Minimal object creation** during execution
+- **Direct LLM communication** without additional abstractions
+- **Efficient handoff detection** through tool classification
+
+### Scalability
+
+- **Thread-safe design** enables horizontal scaling
+- **Stateless execution** supports load balancing
+- **Serializable state** enables process migration
+
+## Error Handling Architecture
+
+### Graceful Degradation
+
+The system handles errors at multiple levels:
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Agent Level   │    │   Tool Level    │    │   LLM Level     │
+│                 │    │                 │    │                 │
+│ • Handoff Fails │    │ • Tool Errors   │    │ • API Errors    │
+│ • Max Turns     │    │ • Retry Logic   │    │ • Rate Limits   │
+│ • State Errors  │    │ • Fallback      │    │ • Timeouts      │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+### Error Recovery
+
+- **Context preservation** even during errors
+- **Partial execution results** for debugging
+- **Conversation continuity** after error resolution
+
+## Extension Points
+
+### Custom Tools
+
+The tool system is fully extensible:
+
+```ruby
+class CustomTool < Agents::Tool
+  name "custom_action"
+  description "Perform custom business logic"
+  param :input, type: "string"
+
+  def perform(tool_context, input:)
+    # Access context for state
+    user_id = tool_context.context[:user_id]
+
+    # Perform custom logic
+    result = BusinessLogic.process(input, user_id)
+
+    # Update shared state
+    tool_context.state[:last_action] = result
+
+    result
+  end
+end
+```
+
+### Custom Providers
+
+While built on RubyLLM, the architecture supports custom providers:
+
+```ruby
+# Custom provider integration
+class CustomProvider < RubyLLM::Provider
+  def complete(messages, **options)
+    # Custom LLM integration
+  end
+end
+
+# Use with agents
+agent = Agents::Agent.new(
+  name: "Assistant",
+  model: CustomProvider.new.model("custom-model")
+)
+```
+
+### Debug Hooks
+
+The system provides hooks for debugging and tracing:
+
+```ruby
+# Enable debug logging
+ENV["RUBYLLM_DEBUG"] = "true"
+
+# Custom callbacks
+chat.on(:new_message) { puts "Sending to LLM..." }
+chat.on(:end_message) { |response| puts "Received: #{response.content}" }
+```
+
+This architecture provides a robust foundation for building production-ready multi-agent systems while maintaining simplicity and developer productivity.

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/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
+```