ai-agents 0.1.2 → 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/lib/agents/agent.rb

@@ -178,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Agents
-  VERSION = "0.1.2"
+  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.2
+  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