ai-agents 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a7f03e74e5438811518c7dc1f6cf24414d24453770858d2a8e12dda823ba428
-  data.tar.gz: d87e91cc47ae009e23db840a29f0fbce3d4c0e913ca3364c1fdaddcdc1816623
+  metadata.gz: 71f4852e0a5f1048dfeefa4b3ab678de189977940330f81425b60f687e66adc0
+  data.tar.gz: 5661b109441687dbdba66208c71798e91bbd338e857619fcc3b634b4542662cb
 SHA512:
-  metadata.gz: 900501d264a748f85f2c0faa1eb3e1d23a0d9bfc0416eaeebc6fa814446ba0e22d61a93cc97095a76982b915c711603fd7ded72fcc7911bc18875834f95530ab
-  data.tar.gz: 3fceb514188c816412726fa27ff5f88c32b81d6d2d19fe8895576428235ac44eab8161c729e08424c560b44a907dfd9c1c412aa703aaed1bc9694fdb7065f79f
+  metadata.gz: 8070c4bc7fd3d9aa9477b2566d0e96f44166c8320b12cdf50017c9c19081ef539a7c20b369714afc0fb468f7c767fcb8f50ff52aae3491357bee69971c99a531
+  data.tar.gz: 0d11ee7a275f5a240ceaf695ac3a3a1aea196aaa452f6fb38cb79ca8e411fd278b9fa526e3a48911ec856c96d84d2cc565ff5f7359771d3a2057ecbdf6b4f675

data/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2025-07-22
+
+### Added
+- Temperature control for agent responses
+  - Added `temperature` parameter to `Agent#initialize` with default value of 0.7
+  - Temperature controls randomness in LLM responses (0.0 = deterministic, 1.0 = very random)
+  - Temperature is passed through to underlying Chat instance for model configuration
+  - Agent cloning supports temperature overrides via `clone(temperature: value)`
+
 ## [0.2.2] - 2025-07-14
 
 ### Added

data/docs/concepts/agents.md

@@ -21,6 +21,7 @@ This project is in early development. While thread safety is a core design goal
 *   **`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.
+*   **`temperature`**: Controls randomness in responses (0.0 = deterministic, 1.0 = very random, default: 0.7)
 
 ### Example
 
@@ -30,7 +31,8 @@ assistant_agent = Agents::Agent.new(
   name: "Assistant",
   instructions: "You are a helpful assistant.",
   model: "gpt-4.1-mini",
-  tools: [CalculatorTool.new]
+  tools: [CalculatorTool.new],
+  temperature: 0.3
 )
 
 # Create a specialized agent by cloning the base agent

data/docs/concepts/context.md

@@ -19,7 +19,7 @@ The main context hash that persists across sessions:
 context = {
   user_id: 123,
   conversation_history: [...],
-  current_agent_name: "Billing",
+  current_agent: "Billing",
   state: { customer_tier: "premium" }  # Tools use this nested hash for persistent data
 }
 ```
@@ -69,7 +69,7 @@ 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"
+# Context includes: current_agent: "Billing"
 
 # Continue conversation
 result2 = runner.run("What payment methods do you accept?", context: result1.context)

data/docs/concepts/runner.md

@@ -84,4 +84,4 @@ result1 = runner.run("I need help with my bill")
 result2 = runner.run("What payment methods do you accept?", context: result1.context)
 ```
 
-The `run` method returns a `RunResult` with output, conversation history, usage metrics, and updated context.
+The `run` method returns a `RunResult` with output, messages, usage metrics, error status, and updated context.

data/docs/concepts/tools.md

@@ -27,36 +27,22 @@ By passing all the necessary data through the `ToolContext`, we ensure that tool
 
 ## Creating a Tool
 
-You can create a tool in two ways:
-
-1.  **Creating a Tool Class:** For more complex tools, you can create a class that inherits from `Agents::Tool` and implements the `perform` method.
-
-    ```ruby
-    class WeatherTool < Agents::Tool
-      name "get_weather"
-      description "Get the current weather for a location."
-      param :location, type: "string", desc: "The city and state, e.g., San Francisco, CA"
-
-      def perform(tool_context, location:)
-        # Access the API key from the shared context
-        api_key = tool_context.context[:weather_api_key]
-
-        # Call the weather API and return the result
-        WeatherApi.get(location, api_key)
-      end
-    end
-    ```
-
-2.  **Using the Functional Tool Definition:** For simpler tools, you can use the `Agents::Tool.tool` helper to define a tool with a block.
-
-    ```ruby
-    calculator_tool = Agents::Tool.tool(
-      "calculate",
-      description: "Perform a mathematical calculation."
-    ) do |tool_context, expression:|
-      # Perform the calculation and return the result
-      eval(expression).to_s
-    end
-    ```
-
-In both cases, the `perform` method receives the `tool_context` and the tool's parameters as arguments. This design ensures that your tools are always thread-safe and easy to test.
+You create tools by creating a class that inherits from `Agents::Tool` and implements the `perform` method:
+
+```ruby
+class WeatherTool < Agents::Tool
+  name "get_weather"
+  description "Get the current weather for a location."
+  param :location, type: "string", desc: "The city and state, e.g., San Francisco, CA"
+
+  def perform(tool_context, location:)
+    # Access the API key from the shared context
+    api_key = tool_context.context[:weather_api_key]
+
+    # Call the weather API and return the result
+    WeatherApi.get(location, api_key)
+  end
+end
+```
+
+The `perform` method receives the `tool_context` and the tool's parameters as arguments. This design ensures that your tools are always thread-safe and easy to test.

data/docs/guides/multi-agent-systems.md

@@ -210,7 +210,7 @@ RSpec.describe "Customer Support Workflow" do
     result = runner.run("I have a billing question")
     
     # Verify handoff occurred
-    expect(result.context.current_agent_name).to eq("Billing")
+    expect(result.context[:current_agent]).to eq("Billing")
     
     # Test continued conversation
     followup = runner.run("What are your payment terms?", context: result.context)

data/docs/guides/rails-integration.md

@@ -85,7 +85,7 @@ class Conversation < ApplicationRecord
     create!(
       user: user,
       context: result.context.to_h,
-      current_agent: result.context.current_agent_name
+      current_agent: result.context[:current_agent]
     )
   end
 end
@@ -209,7 +209,7 @@ class AgentConversationsController < ApplicationController
       
       render json: {
         response: result.output,
-        agent: result.context.current_agent_name,
+        agent: result.context[:current_agent],
         conversation_id: result.context[:conversation_id]
       }
     rescue => e
@@ -313,7 +313,7 @@ class AgentConversationJob < ApplicationJob
       "agent_conversation_#{user_id}",
       {
         response: result.output,
-        agent: result.context.current_agent_name,
+        agent: result.context[:current_agent],
         conversation_id: conversation_id
       }
     )

data/docs/guides/state-persistence.md

@@ -183,7 +183,7 @@ class ContextCleaner
     # Limit total context size
     if cleaned.keys.size > MAX_CONTEXT_KEYS
       # Keep essential keys, remove extras
-      essential_keys = [:user_id, :current_agent_name, :conversation_history]
+      essential_keys = [:user_id, :current_agent, :conversation_history]
       extra_keys = cleaned.keys - essential_keys
       extra_keys.first(cleaned.keys.size - MAX_CONTEXT_KEYS).each do |key|
         cleaned.delete(key)
@@ -292,7 +292,7 @@ class VersionedContext
       {
         version: index,
         timestamp: context[:updated_at],
-        agent: context[:current_agent_name]
+        agent: context[:current_agent]
       }
     end
   end
@@ -409,12 +409,10 @@ class ContextMigrator
   private
   
   def self.migrate_v1_to_v2(context)
-    # V1 -> V2: Rename 'current_agent' to 'current_agent_name'
+    # V1 -> V2: Rename 'current_agent' to 'current_agent' (no change needed)
     migrated = context.deep_dup
     
-    if migrated[:current_agent]
-      migrated[:current_agent_name] = migrated.delete(:current_agent)
-    end
+    # No migration needed - current_agent is already the correct field name
     
     migrated[:_version] = 2
     migrated

data/docs/guides.md

@@ -2,7 +2,7 @@
 layout: default
 title: Guides
 nav_order: 3
-published: false
+published: true
 has_children: true
 ---
 

data/examples/isp-support/agents_factory.rb

@@ -44,7 +44,8 @@ module ISPSupport
         name: "Triage Agent",
         instructions: triage_instructions,
         model: "gpt-4.1-mini",
-        tools: []
+        tools: [],
+        temperature: 0.3  # Lower temperature for consistent routing decisions
       )
     end
 
@@ -53,7 +54,8 @@ module ISPSupport
         name: "Sales Agent",
         instructions: sales_instructions_with_state,
         model: "gpt-4.1-mini",
-        tools: [ISPSupport::CreateLeadTool.new, ISPSupport::CreateCheckoutTool.new]
+        tools: [ISPSupport::CreateLeadTool.new, ISPSupport::CreateCheckoutTool.new],
+        temperature: 0.8  # Higher temperature for more persuasive, varied sales language
       )
     end
 
@@ -66,7 +68,8 @@ module ISPSupport
           ISPSupport::CrmLookupTool.new,
           ISPSupport::SearchDocsTool.new,
           ISPSupport::EscalateToHumanTool.new
-        ]
+        ],
+        temperature: 0.5  # Balanced temperature for helpful but consistent technical support
       )
     end
 

data/lib/agents/agent.rb

@@ -33,7 +33,7 @@
 #   )
 module Agents
   class Agent
-    attr_reader :name, :instructions, :model, :tools, :handoff_agents
+    attr_reader :name, :instructions, :model, :tools, :handoff_agents, :temperature
 
     # Initialize a new Agent instance
     #
@@ -42,12 +42,14 @@ module Agents
     # @param model [String] The LLM model to use (default: "gpt-4.1-mini")
     # @param tools [Array<Agents::Tool>] Array of tool instances the agent can use
     # @param handoff_agents [Array<Agents::Agent>] Array of agents this agent can hand off to
-    def initialize(name:, instructions: nil, model: "gpt-4.1-mini", tools: [], handoff_agents: [])
+    # @param temperature [Float] Controls randomness in responses (0.0 = deterministic, 1.0 = very random, default: 0.7)
+    def initialize(name:, instructions: nil, model: "gpt-4.1-mini", tools: [], handoff_agents: [], temperature: 0.7)
       @name = name
       @instructions = instructions
       @model = model
       @tools = tools.dup
       @handoff_agents = []
+      @temperature = temperature
 
       # Mutex for thread-safe handoff registration
       # While agents are typically configured at startup, we want to ensure
@@ -131,6 +133,7 @@ module Agents
     # @option changes [String] :model New model identifier
     # @option changes [Array<Agents::Tool>] :tools New tools array (replaces all tools)
     # @option changes [Array<Agents::Agent>] :handoff_agents New handoff agents
+    # @option changes [Float] :temperature Temperature for LLM responses (0.0-1.0)
     # @return [Agents::Agent] A new frozen agent instance with the specified changes
     def clone(**changes)
       self.class.new(
@@ -138,7 +141,8 @@ module Agents
         instructions: changes.fetch(:instructions, @instructions),
         model: changes.fetch(:model, @model),
         tools: changes.fetch(:tools, @tools.dup),
-        handoff_agents: changes.fetch(:handoff_agents, @handoff_agents)
+        handoff_agents: changes.fetch(:handoff_agents, @handoff_agents),
+        temperature: changes.fetch(:temperature, @temperature)
       )
     end
 

data/lib/agents/chat.rb

@@ -26,11 +26,14 @@ module Agents
       end
     end
 
-    def initialize(model: nil, handoff_tools: [], context_wrapper: nil, **options)
+    def initialize(model: nil, handoff_tools: [], context_wrapper: nil, temperature: nil, **options)
       super(model: model, **options)
       @handoff_tools = handoff_tools
       @context_wrapper = context_wrapper
 
+      # Set temperature if provided (RubyLLM::Chat sets this via accessor)
+      @temperature = temperature if temperature
+
       # Register handoff tools with RubyLLM for schema generation
       @handoff_tools.each { |tool| with_tool(tool) }
     end

data/lib/agents/runner.rb

@@ -246,6 +246,7 @@ module Agents
       # Create extended chat with handoff awareness and context
       chat = Agents::Chat.new(
         model: agent.model,
+        temperature: agent.temperature,
         handoff_tools: handoff_tools,        # Direct tools, no wrapper
         context_wrapper: context_wrapper     # Pass context directly
       )

data/lib/agents/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ai-agents
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Shivam Mishra