ai-agents 0.1.1 → 0.1.3

data/examples/collaborative-copilot/tools/search_knowledge_base_tool.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Copilot
+  # Tool for searching knowledge base articles and documentation
+  class SearchKnowledgeBaseTool < Agents::Tool
+    description "Search help documentation and knowledge base for solutions"
+    param :query, type: "string", desc: "Search terms or keywords to find relevant articles"
+    param :category, type: "string",
+                     desc: "Optional: filter by category (troubleshooting, account, development, billing)", required: false
+
+    def perform(_tool_context, query:, category: nil)
+      data_file = File.join(__dir__, "../data/knowledge_base.json")
+      return "Knowledge base unavailable" unless File.exist?(data_file)
+
+      begin
+        kb_data = JSON.parse(File.read(data_file))
+        articles = kb_data["articles"]
+        query_text = query.downcase
+        matches = []
+
+        articles.each do |article_id, article|
+          # Skip if category filter is specified and doesn't match
+          next if category && article["category"] != category.downcase
+
+          # Simple keyword matching
+          text_to_search = [
+            article["title"],
+            article["tags"].join(" "),
+            article["content"]
+          ].join(" ").downcase
+
+          next unless text_to_search.include?(query_text)
+
+          matches << {
+            article_id: article_id,
+            title: article["title"],
+            category: article["category"],
+            tags: article["tags"],
+            content_preview: "#{article["content"][0...200]}..."
+          }
+        end
+
+        if matches.empty?
+          "No knowledge base articles found for: #{query}"
+        else
+          JSON.pretty_generate({ query: query, articles: matches })
+        end
+      rescue StandardError => e
+        "Error searching knowledge base: #{e.message}"
+      end
+    end
+  end
+end

data/examples/collaborative-copilot/tools/search_linear_issues_tool.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Copilot
+  # Tool for searching Linear issues for development context and bug reports
+  class SearchLinearIssuesTool < Agents::Tool
+    description "Search Linear issues for bug reports, feature requests, and development context"
+    param :query, type: "string", desc: "Search terms (keywords, error messages, or feature descriptions)"
+    param :status, type: "string", desc: "Optional: filter by status (backlog, in_progress, completed, resolved)",
+                   required: false
+    param :priority, type: "string", desc: "Optional: filter by priority (low, medium, high)", required: false
+
+    def perform(_tool_context, query:, status: nil, priority: nil)
+      data_file = File.join(__dir__, "../data/linear_issues.json")
+      return "Linear issues database unavailable" unless File.exist__(data_file)
+
+      begin
+        linear_data = JSON.parse(File.read(data_file))
+        issues = linear_data["issues"]
+        query_text = query.downcase
+        matches = []
+
+        issues.each do |issue_id, issue|
+          # Apply filters
+          next if status && issue["status"] != status.downcase
+          next if priority && issue["priority"] != priority.downcase
+
+          # Simple keyword matching
+          text_to_search = [
+            issue["title"],
+            issue["description"],
+            issue["labels"].join(" "),
+            issue["resolution"]
+          ].compact.join(" ").downcase
+
+          next unless text_to_search.include?(query_text)
+
+          matches << {
+            issue_id: issue_id,
+            title: issue["title"],
+            status: issue["status"],
+            priority: issue["priority"],
+            labels: issue["labels"],
+            description: "#{issue["description"][0...200]}...",
+            resolution: issue["resolution"]
+          }
+        end
+
+        if matches.empty?
+          "No Linear issues found for: #{query}"
+        else
+          JSON.pretty_generate({ query: query, issues: matches })
+        end
+      rescue StandardError => e
+        "Error searching Linear issues: #{e.message}"
+      end
+    end
+  end
+end

data/examples/isp-support/agents_factory.rb

@@ -51,7 +51,7 @@ module ISPSupport
     def create_sales_agent
       Agents::Agent.new(
         name: "Sales Agent",
-        instructions: sales_instructions,
+        instructions: sales_instructions_with_state,
         model: "gpt-4.1-mini",
         tools: [ISPSupport::CreateLeadTool.new, ISPSupport::CreateCheckoutTool.new]
       )
@@ -113,6 +113,62 @@ module ISPSupport
       INSTRUCTIONS
     end
 
+    def sales_instructions_with_state
+      lambda { |context|
+        state = context.context[:state] || {}
+
+        base_instructions = <<~INSTRUCTIONS
+          You are the Sales Agent for an ISP. You handle new customer acquisition, service upgrades,
+          and plan changes.
+
+          **Your tools:**
+          - `create_lead`: Create sales leads with customer information
+          - `create_checkout`: Generate secure checkout links for purchases
+          - Handoff tools: Route back to triage when needed
+
+          **When to hand off:**
+          - Pure technical support questions → Triage Agent for re-routing
+          - Customer needs to speak with human agent → Triage Agent for re-routing
+        INSTRUCTIONS
+
+        # Add customer context if available from previous agent interactions
+        if state[:customer_name] && state[:customer_id]
+          base_instructions += <<~CONTEXT
+
+            **Customer Context Available:**
+            - Customer Name: #{state[:customer_name]}
+            - Customer ID: #{state[:customer_id]}
+            - Email: #{state[:customer_email]}
+            - Phone: #{state[:customer_phone]}
+            - Address: #{state[:customer_address]}
+            #{state[:current_plan] ? "- Current Plan: #{state[:current_plan]}" : ""}
+            #{state[:account_status] ? "- Account Status: #{state[:account_status]}" : ""}
+            #{state[:monthly_usage] ? "- Monthly Usage: #{state[:monthly_usage]}GB" : ""}
+
+            **IMPORTANT:**#{" "}
+            - Use this existing customer information when creating leads or providing service
+            - Do NOT ask for name, email, phone, or address - you already have these details
+            - For new connections, use the existing customer details and only ask for the desired plan
+            - Provide personalized recommendations based on their current information
+          CONTEXT
+        end
+
+        base_instructions += <<~FINAL_INSTRUCTIONS
+
+          **Instructions:**
+          - Be enthusiastic but not pushy
+          - Gather required info: name, email, desired plan for leads
+          - For account verification, ask customer for their account details directly
+          - For existing customers wanting upgrades, collect account info and proceed
+          - Create checkout links for confirmed purchases
+          - Always explain next steps after creating leads or checkout links
+          - Handle billing questions yourself - don't hand off for account verification
+        FINAL_INSTRUCTIONS
+
+        base_instructions
+      }
+    end
+
     def support_instructions
       <<~INSTRUCTIONS
         You are the Support Agent for an ISP. You handle technical support, troubleshooting,

data/examples/isp-support/tools/create_lead_tool.rb

@@ -8,8 +8,22 @@ module ISPSupport
     param :email, type: "string", desc: "Customer's email address"
     param :desired_plan, type: "string", desc: "Plan the customer is interested in"
 
-    def perform(_tool_context, name:, email:, desired_plan:)
-      "Lead created for #{name} (#{email}) interested in #{desired_plan} plan. Sales team will contact within 24 hours."
+    def perform(tool_context, name:, email:, desired_plan:)
+      # Store lead information in state for follow-up
+      tool_context.state[:lead_name] = name
+      tool_context.state[:lead_email] = email
+      tool_context.state[:desired_plan] = desired_plan
+      tool_context.state[:lead_created_at] = Time.now.iso8601
+
+      # Check if we have existing customer info from CRM lookup
+      if tool_context.state[:customer_id]
+        existing_customer = tool_context.state[:customer_name]
+        "Lead created for existing customer #{existing_customer} (#{email}) " \
+        "interested in upgrading to #{desired_plan} plan. Sales team will contact within 24 hours."
+      else
+        "Lead created for #{name} (#{email}) interested in #{desired_plan} plan. " \
+        "Sales team will contact within 24 hours."
+      end
     end
   end
 end

data/examples/isp-support/tools/crm_lookup_tool.rb

@@ -8,7 +8,7 @@ module ISPSupport
     description "Look up customer account information by account ID"
     param :account_id, type: "string", desc: "Customer account ID (e.g., CUST001)"
 
-    def perform(_tool_context, account_id:)
+    def perform(tool_context, account_id:)
       data_file = File.join(__dir__, "../data/customers.json")
       return "Customer database unavailable" unless File.exist?(data_file)
 
@@ -18,6 +18,18 @@ module ISPSupport
 
         return "Customer not found" unless customer
 
+        # Store customer information in shared state for other tools/agents
+        tool_context.state[:customer_id] = account_id.upcase
+        tool_context.state[:customer_name] = customer["name"]
+        tool_context.state[:customer_email] = customer["email"]
+        tool_context.state[:customer_phone] = customer["phone"]
+        tool_context.state[:customer_address] = customer["address"]
+        tool_context.state[:current_plan] = customer["plan"]["name"]
+        tool_context.state[:account_status] = customer["account_status"]
+        tool_context.state[:plan_price] = customer["plan"]["price"]
+        tool_context.state[:next_bill_date] = customer["billing"]["next_bill_date"]
+        tool_context.state[:account_balance] = customer["billing"]["balance"]
+
         # Return the entire customer data as JSON for the agent to process
         customer.to_json
       rescue StandardError

data/lib/agents/agent.rb

@@ -13,11 +13,16 @@
 #     tools: [calculator_tool, weather_tool]
 #   )
 #
-# @example Creating an agent with dynamic instructions
+# @example Creating an agent with dynamic state-aware instructions
 #   agent = Agents::Agent.new(
 #     name: "Support Agent",
 #     instructions: ->(context) {
-#       "You are supporting user #{context.context[:user_name]}"
+#       state = context.context[:state] || {}
+#       base = "You are a support agent."
+#       if state[:customer_name]
+#         base += " Customer: #{state[:customer_name]} (#{state[:customer_id]})"
+#       end
+#       base
 #     }
 #   )
 #
@@ -147,18 +152,25 @@ module Agents
     #     instructions: "You are a helpful support agent"
     #   )
     #
-    # @example Dynamic instructions based on context
+    # @example Dynamic instructions with state awareness
     #   agent = Agent.new(
-    #     name: "Support",
+    #     name: "Sales Agent",
     #     instructions: ->(context) {
-    #       user = context.context[:user]
-    #       "You are helping #{user.name}. They are a #{user.tier} customer with account #{user.id}"
+    #       state = context.context[:state] || {}
+    #       base = "You are a sales agent."
+    #       if state[:customer_name] && state[:current_plan]
+    #         base += " Customer: #{state[:customer_name]} on #{state[:current_plan]} plan."
+    #       end
+    #       base
     #     }
     #   )
     #
     # @param context [Agents::RunContext] The current execution context containing runtime data
     # @return [String, nil] The system prompt string or nil if no instructions are set
     def get_system_prompt(context)
+      # TODO: Add string interpolation support for instructions
+      # Allow instructions like "You are helping %{customer_name}" that automatically
+      # get state values injected from context[:state] using Ruby's % formatting
       case instructions
       when String
         instructions
@@ -166,5 +178,39 @@ module Agents
         instructions.call(context)
       end
     end
+
+    # Transform this agent into a tool, callable by other agents.
+    # This enables agent-to-agent collaboration without conversation handoffs.
+    #
+    # Agent-as-tool is different from handoffs in two key ways:
+    # 1. The wrapped agent receives generated input, not conversation history
+    # 2. The wrapped agent returns a result to the calling agent, rather than taking over
+    #
+    # @param name [String, nil] Override the tool name (defaults to snake_case agent name)
+    # @param description [String, nil] Override the tool description
+    # @param output_extractor [Proc, nil] Custom proc to extract/transform the agent's output
+    # @param params [Hash] Additional parameter definitions for the tool
+    # @return [Agents::AgentTool] A tool that wraps this agent
+    #
+    # @example Basic agent-as-tool
+    #   research_agent = Agent.new(name: "Researcher", instructions: "Research topics")
+    #   research_tool = research_agent.as_tool(
+    #     name: "research_topic",
+    #     description: "Research a topic using company knowledge base"
+    #   )
+    #
+    # @example Custom output extraction
+    #   analyzer_tool = analyzer_agent.as_tool(
+    #     output_extractor: ->(result) { result.context[:extracted_data]&.to_json || result.output }
+    #   )
+    #
+    def as_tool(name: nil, description: nil, output_extractor: nil)
+      AgentTool.new(
+        agent: self,
+        name: name,
+        description: description,
+        output_extractor: output_extractor
+      )
+    end
   end
 end

data/lib/agents/agent_tool.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Agents
+  # AgentTool wraps an agent as a tool, enabling agent-to-agent collaboration
+  # without conversation handoffs. This implementation constrains wrapped agents
+  # for safety and predictability.
+  #
+  # Key constraints:
+  # 1. Wrapped agents cannot perform handoffs (empty registry)
+  # 2. Limited turn count to prevent infinite loops
+  # 3. Isolated context (only shared state, no conversation history)
+  # 4. Always returns to calling agent
+  #
+  # @example Customer support copilot with specialized agents
+  #   conversation_agent = Agent.new(
+  #     name: "ConversationAnalyzer",
+  #     instructions: "Extract order IDs and customer intent from conversation history"
+  #   )
+  #
+  #   actions_agent = Agent.new(
+  #     name: "ShopifyActions",
+  #     instructions: "Perform Shopify operations",
+  #     tools: [shopify_tool]
+  #   )
+  #
+  #   copilot = Agent.new(
+  #     name: "SupportCopilot",
+  #     tools: [
+  #       conversation_agent.as_tool(
+  #         name: "analyze_conversation",
+  #         description: "Extract key info from conversation history"
+  #       ),
+  #       actions_agent.as_tool(
+  #         name: "shopify_action",
+  #         description: "Perform Shopify operations like refunds"
+  #       )
+  #     ]
+  #   )
+  class AgentTool < Tool
+    attr_reader :wrapped_agent, :tool_name, :tool_description, :output_extractor
+
+    # Default parameter for agent tools
+    param :input, type: "string", desc: "Input message for the agent"
+
+    # Initialize an AgentTool that wraps an agent as a callable tool
+    #
+    # @param agent [Agents::Agent] The agent to wrap as a tool
+    # @param name [String, nil] Override the tool name (defaults to snake_case agent name)
+    # @param description [String, nil] Override the tool description
+    # @param output_extractor [Proc, nil] Custom proc to extract/transform the agent's output
+    def initialize(agent:, name: nil, description: nil, output_extractor: nil)
+      @wrapped_agent = agent
+      @tool_name = name || transform_agent_name(agent.name)
+      @tool_description = description || "Execute #{agent.name} agent"
+      @output_extractor = output_extractor
+
+      super()
+    end
+
+    def name
+      @tool_name
+    end
+
+    def description
+      @tool_description
+    end
+
+    # Execute the wrapped agent with constraints to prevent handoffs and recursion
+    def perform(tool_context, input:)
+      # Create isolated context for the wrapped agent
+      isolated_context = create_isolated_context(tool_context.context)
+
+      # Execute with explicit constraints:
+      # 1. Empty registry prevents handoffs
+      # 2. Low max_turns prevents infinite loops
+      # 3. Isolated context prevents history access
+      result = Runner.new.run(
+        @wrapped_agent,
+        input,
+        context: isolated_context,
+        registry: {}, # CONSTRAINT: No handoffs allowed
+        max_turns: 3  # CONSTRAINT: Limited turns for tool execution
+      )
+
+      return "Agent execution failed: #{result.error.message}" if result.error
+
+      # Extract output
+      if @output_extractor
+        @output_extractor.call(result)
+      else
+        result.output || "No output from #{@wrapped_agent.name}"
+      end
+    rescue StandardError => e
+      "Error executing #{@wrapped_agent.name}: #{e.message}"
+    end
+
+    private
+
+    def transform_agent_name(name)
+      name.downcase.gsub(/\s+/, "_").gsub(/[^a-z0-9_]/, "")
+    end
+
+    # Create isolated context that only shares state, not conversation artifacts
+    def create_isolated_context(parent_context)
+      isolated = {}
+
+      # Only share the state - everything else is conversation-specific
+      isolated[:state] = parent_context[:state] if parent_context[:state]
+
+      isolated
+    end
+  end
+end

data/lib/agents/handoff.rb

@@ -12,35 +12,10 @@ module Agents
   # 4. The tool signals the handoff through context
   # 5. The Runner detects this and switches to the new agent
   #
-  # ## First-Call-Wins Implementation
-  # This implementation uses "first-call-wins" semantics to prevent infinite handoff loops.
-  #
-  # ### The Problem We Solved
-  # During development, we discovered that LLMs could call the same handoff tool multiple times
-  # in a single response, leading to infinite loops:
-  #
-  # 1. User: "My internet isn't working but my account shows active"
-  # 2. Triage Agent hands off to Support Agent
-  # 3. Support Agent sees account info is needed, hands back to Triage Agent
-  # 4. Triage Agent sees technical issue, hands off to Support Agent again
-  # 5. This creates an infinite ping-pong loop
-  #
-  # ### Root Cause Analysis
-  # Unlike OpenAI's SDK which processes tool calls before execution, RubyLLM automatically
-  # executes all tool calls in a response. This meant:
-  # - LLM calls handoff tool 10+ times in one response
-  # - Each call sets context[:pending_handoff], overwriting previous values
-  # - Runner processes handoffs after tool execution, seeing only the last one
-  # - Multiple handoff signals created conflicting state
-  #
-  # TODO: Overall, this problem can be tackled better if we replace the RubyLLM chat
-  # program with our own implementation.
-  #
-  # ### The Solution
-  # We implemented first-call-wins semantics inspired by OpenAI's approach:
-  # - First handoff call in a response sets the pending handoff
-  # - Subsequent calls are ignored with a "transfer in progress" message
-  # - This prevents loops and mirrors OpenAI SDK behavior
+  # ## Loop Prevention
+  # The library prevents infinite handoff loops by processing only the first handoff
+  # tool call in any LLM response. This is handled automatically by the Chat class
+  # which detects handoff tools and processes them separately from regular tools.
   #
   # ## Why Tools Instead of Instructions
   # Using tools for handoffs has several advantages:
@@ -66,12 +41,11 @@ module Agents
   #   # LLM calls: handoff_to_billing()
   #   # Runner switches to billing_agent for the next turn
   #
-  # @example First-call-wins in action
+  # @example Multiple handoff handling
   #   # Single LLM response with multiple handoff calls:
-  #   # Call 1: handoff_to_support() -> Sets pending_handoff, returns "Transferring to Support"
-  #   # Call 2: handoff_to_support() -> Ignored, returns "Transfer already in progress"
-  #   # Call 3: handoff_to_billing() -> Ignored, returns "Transfer already in progress"
-  #   # Result: Only transfers to Support Agent (first call wins)
+  #   # Call 1: handoff_to_support() -> Processed and executed
+  #   # Call 2: handoff_to_billing() -> Ignored (only first handoff processed)
+  #   # Result: Only transfers to Support Agent
   class HandoffTool < Tool
     attr_reader :target_agent
 

data/lib/agents/tool_context.rb

@@ -94,5 +94,41 @@ module Agents
     def usage
       @run_context.usage
     end
+
+    # Convenient access to the shared state hash within the context.
+    # This provides tools with a dedicated space to store and retrieve
+    # state that persists across agent interactions within a conversation.
+    #
+    # State is automatically initialized as an empty hash if it doesn't exist.
+    # All state modifications are automatically included in context serialization,
+    # making it persist across process boundaries (e.g., Rails with ActiveRecord).
+    #
+    # @return [Hash] The shared state hash
+    # @example Tool storing customer information in state
+    #   def perform(tool_context, customer_id:)
+    #     customer = Customer.find(customer_id)
+    #
+    #     # Store in shared state for other tools/agents to access
+    #     tool_context.state[:customer_id] = customer_id
+    #     tool_context.state[:customer_name] = customer.name
+    #     tool_context.state[:plan_type] = customer.plan
+    #
+    #     "Found customer #{customer.name}"
+    #   end
+    #
+    # @example Tool reading from shared state
+    #   def perform(tool_context)
+    #     customer_id = tool_context.state[:customer_id]
+    #     plan_type = tool_context.state[:plan_type]
+    #
+    #     if customer_id && plan_type
+    #       "Current plan: #{plan_type} for customer #{customer_id}"
+    #     else
+    #       "No customer information available"
+    #     end
+    #   end
+    def state
+      context[:state] ||= {}
+    end
   end
 end

data/lib/agents/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Agents
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

data/lib/agents.rb

@@ -82,3 +82,4 @@ require_relative "agents/chat"
 require_relative "agents/tool_wrapper"
 require_relative "agents/agent_runner"
 require_relative "agents/runner"
+require_relative "agents/agent_tool"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ai-agents
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Shivam Mishra
@@ -37,7 +37,48 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- docs/Gemfile
+- docs/Gemfile.lock
+- docs/_config.yml
+- docs/_sass/color_schemes/ruby.scss
+- docs/_sass/custom/custom.scss
+- docs/architecture.md
+- docs/assets/fonts/InterVariable.woff2
+- docs/concepts.md
+- docs/concepts/agent-tool.md
+- docs/concepts/agents.md
+- docs/concepts/context.md
+- docs/concepts/handoffs.md
+- docs/concepts/runner.md
+- docs/concepts/tools.md
+- docs/guides.md
+- docs/guides/agent-as-tool-pattern.md
+- docs/guides/multi-agent-systems.md
+- docs/guides/rails-integration.md
+- docs/guides/state-persistence.md
+- docs/index.md
 - examples/README.md
+- examples/collaborative-copilot/README.md
+- examples/collaborative-copilot/agents/analysis_agent.rb
+- examples/collaborative-copilot/agents/answer_suggestion_agent.rb
+- examples/collaborative-copilot/agents/copilot_orchestrator.rb
+- examples/collaborative-copilot/agents/integrations_agent.rb
+- examples/collaborative-copilot/agents/research_agent.rb
+- examples/collaborative-copilot/data/contacts.json
+- examples/collaborative-copilot/data/conversations.json
+- examples/collaborative-copilot/data/knowledge_base.json
+- examples/collaborative-copilot/data/linear_issues.json
+- examples/collaborative-copilot/data/stripe_billing.json
+- examples/collaborative-copilot/interactive.rb
+- examples/collaborative-copilot/tools/create_linear_ticket_tool.rb
+- examples/collaborative-copilot/tools/get_article_tool.rb
+- examples/collaborative-copilot/tools/get_contact_tool.rb
+- examples/collaborative-copilot/tools/get_conversation_tool.rb
+- examples/collaborative-copilot/tools/get_stripe_billing_tool.rb
+- examples/collaborative-copilot/tools/search_contacts_tool.rb
+- examples/collaborative-copilot/tools/search_conversations_tool.rb
+- examples/collaborative-copilot/tools/search_knowledge_base_tool.rb
+- examples/collaborative-copilot/tools/search_linear_issues_tool.rb
 - examples/isp-support/README.md
 - examples/isp-support/agents_factory.rb
 - examples/isp-support/data/customers.json
@@ -52,6 +93,7 @@ files:
 - lib/agents.rb
 - lib/agents/agent.rb
 - lib/agents/agent_runner.rb
+- lib/agents/agent_tool.rb
 - lib/agents/chat.rb
 - lib/agents/handoff.rb
 - lib/agents/result.rb
@@ -75,7 +117,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="