ai-agents 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc088132bc2b8dafa23669d0e2e15d110f6a8cb982f54ba026247008a90322ca
-  data.tar.gz: 93086217d9aa75ebf072a299aeadacf688cede7216bd41d64dc539072ec1469b
+  metadata.gz: 004f33c8652e5b8c4d8be7bd84e959c55f6926411d3cac8bd3b3d029b7b21690
+  data.tar.gz: 6592c590cd91809ee47865a25adcf734370695bd4c697b1926aabc95c6e2d574
 SHA512:
-  metadata.gz: 7ac77c92850152aa9bb716d3d1ecd37444e7cab76c9ab5e4e63aef20ad337a2416f9b4a1d55895ff0d0af97d4e8903c1e73f03c3e7a8f9bd6de0b8ed2f4279d6
-  data.tar.gz: 4b3055a233c48902fdb570ca8dce896d09cdbd30dc52a0a5f03fb290c7f60725804d574e5df3e3d4428c61ad1af58b97d0f173c5b576a324ae84598f4d48fbbc
+  metadata.gz: 0baadd9d0771c8e2bdd345a0a8e00bc792c6a607ec78b8796a6718e4695dc5e92b2fdc2ec11b4384c77ad409af4660be5288b020c6404750a2db5a66d1cf094c
+  data.tar.gz: de6edbb743e8b01634aaa12c656bc7cfa618de8086aa4e4e6add08683e8383b611856b4b9fa452c2e2e2bbd3efa2a74edefcc17af8188d2605babfc5067ecaf2

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

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.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ai-agents
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Shivam Mishra
@@ -75,7 +75,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:
   - - ">="