ai-agents 0.1.0 → 0.1.2

data/lib/agents/tool.rb

@@ -36,52 +36,8 @@
 #     end
 #   end
 #
-# @example Using the functional tool definition
-#   # Define a calculator tool
-#   calculator = Agents::Tool.tool(
-#     "calculate",
-#     description: "Perform mathematical calculations"
-#   ) do |tool_context, expression:|
-#     begin
-#       result = eval(expression)
-#       result.to_s
-#     rescue => e
-#       "Calculation error: #{e.message}"
-#     end
-#   end
-#
-#   # Use the tool in an agent
-#   agent = Agents::Agent.new(
-#     name: "Math Assistant",
-#     instructions: "You are a helpful math assistant",
-#     tools: [calculator]
-#   )
-#
-#   # During execution, the runner would call it like this:
-#   run_context = Agents::RunContext.new({ user_id: 123 })
-#   tool_context = Agents::ToolContext.new(run_context: run_context)
-#
-#   result = calculator.execute(tool_context, expression: "2 + 2 * 3")
-#   # => "8"
 module Agents
   class Tool < RubyLLM::Tool
-    class << self
-      def param(name, type = String, desc = nil, required: true, **options)
-        # Convert Ruby types to JSON schema types
-        json_type = case type
-                    when String, "string" then "string"
-                    when Integer, "integer" then "integer"
-                    when Float, "number" then "number"
-                    when TrueClass, FalseClass, "boolean" then "boolean"
-                    when Array, "array" then "array"
-                    when Hash, "object" then "object"
-                    else "string"
-                    end
-
-        # Call parent param method
-        super(name, type: json_type, desc: desc, required: required, **options)
-      end
-    end
     # Execute the tool with context injection.
     # This method is called by the runner and handles the thread-safe
     # execution pattern by passing all state through parameters.
@@ -112,42 +68,5 @@ module Agents
     def perform(tool_context, **params)
       raise NotImplementedError, "Tools must implement #perform(tool_context, **params)"
     end
-
-    # Create a tool instance using a functional style definition.
-    # This is an alternative to creating a full class for simple tools.
-    # The block becomes the tool's perform method.
-    #
-    # @param name [String] The tool's name (used in function calling)
-    # @param description [String] Brief description of what the tool does
-    # @yield [tool_context, **params] The block that implements the tool's logic
-    # @return [Agents::Tool] A new tool instance
-    # @example Creating a simple tool functionally
-    #   math_tool = Agents::Tool.tool(
-    #     "add_numbers",
-    #     description: "Add two numbers together"
-    #   ) do |tool_context, a:, b:|
-    #     (a + b).to_s
-    #   end
-    #
-    # @example Tool accessing context with error handling
-    #   greeting_tool = Agents::Tool.tool("greet", description: "Greet a user") do |tool_context, name:|
-    #     language = tool_context.context[:language] || "en"
-    #     case language
-    #     when "es" then "¡Hola, #{name}!"
-    #     when "fr" then "Bonjour, #{name}!"
-    #     else "Hello, #{name}!"
-    #     end
-    #   rescue => e
-    #     "Sorry, I couldn't greet you: #{e.message}"
-    #   end
-    def self.tool(name, description: "", &block)
-      # Create anonymous class that extends Tool
-      Class.new(Tool) do
-        self.name = name
-        self.description = description
-
-        define_method :perform, &block
-      end.new
-    end
   end
 end

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.0"
+  VERSION = "0.1.2"
 end

data/lib/agents.rb

@@ -11,6 +11,18 @@ require_relative "agents/version"
 module Agents
   class Error < StandardError; end
 
+  # OpenAI's recommended system prompt prefix for multi-agent workflows
+  # This helps agents understand they're part of a coordinated system
+  RECOMMENDED_HANDOFF_PROMPT_PREFIX =
+    "# System context\n" \
+    "You are part of a multi-agent system called the Ruby Agents SDK, designed to make agent " \
+    "coordination and execution easy. Agents uses two primary abstraction: **Agents** and " \
+    "**Handoffs**. An agent encompasses instructions and tools and can hand off a " \
+    "conversation to another agent when appropriate. " \
+    "Handoffs are achieved by calling a handoff function, generally named " \
+    "`handoff_to_<agent_name>`. Transfers between agents are handled seamlessly in the background; " \
+    "do not mention or draw attention to these transfers in your conversation with the user.\n"
+
   class << self
     # Logger for debugging (can be set by users)
     attr_accessor :logger
@@ -66,5 +78,7 @@ require_relative "agents/handoff"
 require_relative "agents/agent"
 
 # Execution components
+require_relative "agents/chat"
 require_relative "agents/tool_wrapper"
+require_relative "agents/agent_runner"
 require_relative "agents/runner"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ai-agents
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Shivam Mishra
@@ -51,6 +51,8 @@ files:
 - examples/isp-support/tools/search_docs_tool.rb
 - lib/agents.rb
 - lib/agents/agent.rb
+- lib/agents/agent_runner.rb
+- lib/agents/chat.rb
 - lib/agents/handoff.rb
 - lib/agents/result.rb
 - lib/agents/run_context.rb
@@ -73,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:
   - - ">="