ai-agents 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7948199bfccd3d11e42735b9ee9f34a2431d00de5876785fa26e369a128a686c
-  data.tar.gz: 7a5a91260825a6c2fc59192dee83e8e050a1260fef3d6a0589a9d1dbd0fbc0fe
+  metadata.gz: 66cc6b306e84c6d62c5bf30b34104de9f683a3ec106eb11de12625000b07795d
+  data.tar.gz: dfe243cb0723ef5ef6c79fbb14342cb78a8b5362ccbb4d42356c2f2386d832a5
 SHA512:
-  metadata.gz: d314e6d427f6c9ac5d38ea39b77191c8535e5d0e400690afb15cff48588b7e969b7cb30e88d12e78c027175cdc497e92a74feb899b99f50416af006e3edabe79
-  data.tar.gz: 67b9da18847cddfae2b7866f606d335b51690aeb13c9062b8ae2afa8526ed9ae3343fbf86dd435354ee42b6d3145cefcac3e090ee5ca170895cbfc84f3b510b0
+  metadata.gz: 9db32ad036739a09f198995cf98426c477e5afd4a309dae9f33af11a0baf785808268d5d23539b71fe01c0c3f44ff2e7f1a34fcb3d783d44c171bb7175bed00f
+  data.tar.gz: a263f704efb3122b60bcd4b245e7d84a04c65ed640eae72befbc7e51c6948e668c01bb4115a2d02351e311bf4933a88a081883947970c522484bed4731cdf0e6

data/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- Require RubyLLM 2.0 starting with ai-agents 0.13.0. Applications using RubyLLM 1.x can keep ai-agents 0.12.0.
+- Keep the previous `param :name, desc: "..."` tool declaration syntax working with RubyLLM 2.0.
+
 ## [0.12.0] - 2026-06-29
 
 ### Added

data/CLAUDE.md

@@ -256,7 +256,7 @@ The SDK includes optional OpenTelemetry instrumentation (`lib/agents/instrumenta
 
 6. **Don't use `.delete` for shared tracing state**: If a value in `context[:__otel_tracing]` needs to be read by multiple callbacks, use `tracing[:key]` not `tracing.delete(:key)`. Delete is a destructive side-effect that breaks subsequent reads.
 
-7. **Per-call LLM spans via `on_end_message`**: Individual GENERATION spans are created by hooking into RubyLLM's `chat.on_end_message` (registered in `on_chat_created`). Each span is created and immediately finished. There is no `current_llm_span` in tracing state — only `current_tool_span` needs single-slot tracking.
+7. **Per-call LLM spans via `after_message`**: Individual GENERATION spans are created by hooking into RubyLLM's `chat.after_message` (registered in `on_chat_created`). Each span is created and immediately finished. There is no `current_llm_span` in tracing state — only `current_tool_span` needs single-slot tracking.
 
 8. **Conversation history deduplication**: `Runner#last_message_matches?` checks if the last restored message already matches the current input. If so, uses `chat.complete` instead of `chat.ask(input)` to avoid sending the user message twice.
 

data/README.md

@@ -128,9 +128,9 @@ agent.register_handoffs(technical_support, billing)
 ```ruby
 class EmailTool < Agents::Tool
   description "Send emails to customers"
-  param :to, type: "string", desc: "Email address"
-  param :subject, type: "string", desc: "Email subject"
-  param :body, type: "string", desc: "Email body"
+  parameter :to, type: "string", description: "Email address"
+  parameter :subject, type: "string", description: "Email subject"
+  parameter :body, type: "string", description: "Email body"
 
   def perform(tool_context, to:, subject:, body:)
     # Send email logic here

data/docs/architecture.md

@@ -301,7 +301,7 @@ The tool system is fully extensible:
 class CustomTool < Agents::Tool
   name "custom_action"
   description "Perform custom business logic"
-  param :input, type: "string"
+  parameter :input, type: "string"
 
   def perform(tool_context, input:)
     # Access context for state

data/docs/concepts/agents.md

@@ -22,6 +22,8 @@ This project is in early development. While thread safety is a core design goal
 *   **`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)
+*   **`protocol`**: Optional RubyLLM provider protocol, such as `:responses` or `:chat_completions`.
+*   **`thinking`**: Optional RubyLLM thinking options, such as `effort:` and `display:`.
 
 ### Example
 
@@ -43,3 +45,17 @@ specialized_agent = assistant_agent.clone(
 ```
 
 In this example, we create a base `assistant_agent` and then create a `specialized_agent` by cloning it and adding a new tool. This approach allows for easy composition and reuse of agent configurations.
+
+For an OpenAI reasoning model, select Responses for that agent and leave temperature unset:
+
+```ruby
+reasoning_agent = Agents::Agent.new(
+  name: "Reasoning",
+  model: "your-reasoning-model",
+  protocol: :responses,
+  temperature: nil,
+  thinking: { effort: :medium, display: :summarized }
+)
+```
+
+Other agents can use `protocol: :chat_completions`. The runner applies each agent's protocol and thinking settings when it starts or hands off a conversation.

data/docs/concepts/tools.md

@@ -33,7 +33,7 @@ You create tools by creating a class that inherits from `Agents::Tool` and imple
 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"
+  parameter :location, type: "string", description: "The city and state, e.g., San Francisco, CA"
 
   def perform(tool_context, location:)
     # Access the API key from the shared context

data/docs/guides/instrumentation.md

@@ -18,8 +18,41 @@ The `Agents::Instrumentation` module produces OTel spans that give you full visi
 - **Agent container spans** grouping related LLM and tool calls
 - **Handoff events** recording agent-to-agent transfers
 
+Generation inputs include MIME types for RubyLLM message attachments. Their URLs, local paths, and image data are omitted. Structured image inputs also omit the image URL.
+
 Spans follow the [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) and include Langfuse-specific attributes for rich rendering in the Langfuse dashboard.
 
+### RubyLLM 2.0 events and Langfuse
+
+RubyLLM 2.0 emits `chat.ruby_llm`, `tool_call.ruby_llm`, and `usage.ruby_llm` events. In Rails, these use `ActiveSupport::Notifications`. Outside Rails, configure a RubyLLM instrumenter to receive them. The events are useful for logging and per-attempt usage, but RubyLLM does not turn them into this runner's Langfuse trace. Keep `Agents::Instrumentation` when you need the following mapping:
+
+| Runner span or event | Data in Langfuse | RubyLLM event alone |
+|----------------------|------------------|---------------------|
+| Root span | Overall input and output, session, user, tags, and Chatwoot metadata | No runner-level input, output, or Chatwoot context |
+| Agent span | Agent name and the generations and tools it owns | No agent handoff boundary |
+| Generation span | Request messages, response, model, temperature, and response tokens | `chat.ruby_llm` has the model and response, but needs an OTLP and Langfuse attribute adapter |
+| Tool span | Tool arguments, result, and error status | `tool_call.ruby_llm` has the call, but needs the same adapter |
+| Handoff event | Source agent, target agent, and reason | No RubyLLM handoff event for this runner |
+
+RubyLLM's `usage.ruby_llm` event reports each provider attempt, including failed and cancelled attempts. The generation spans here use tokens from completed messages. Use a separate `usage.ruby_llm` subscriber for attempt-level accounting; do not add its tokens to the same generation spans or costs may be counted twice. See the [RubyLLM instrumentation guide](https://rubyllm.com/instrumentation/) for event payloads.
+
+For an app outside Rails, add `activesupport` and configure RubyLLM before creating a chat:
+
+```ruby
+require "active_support"
+require "active_support/notifications"
+
+RubyLLM.configure do |config|
+  config.instrumenter = ActiveSupport::Notifications
+end
+
+ActiveSupport::Notifications.subscribe("usage.ruby_llm") do |event|
+  puts event.payload.inspect # Replace with your per-attempt usage collector.
+end
+```
+
+This enables RubyLLM's native events. The runner spans still require `Agents::Instrumentation.install` and an OTel exporter, as shown below.
+
 ## Setup
 
 ### 1. Install dependencies
@@ -144,7 +177,7 @@ OpenTelemetry::SDK.configure do |c|
     OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
       OpenTelemetry::Exporter::OTLP::Exporter.new(
         endpoint: "#{langfuse_host}/api/public/otel/v1/traces",
-        headers: { "Authorization" => "Basic #{auth_token}" }
+        headers: { "Authorization" => "Basic #{auth_token}", "x-langfuse-ingestion-version" => "4" }
       )
     )
   )
@@ -157,8 +190,8 @@ The instrumentation sets Langfuse-specific attributes that map to the Langfuse U
 
 | Attribute | Set On | Langfuse Display |
 |-----------|--------|-----------------|
-| `langfuse.trace.input` | Root span | Trace input (top of page) |
-| `langfuse.trace.output` | Root span | Trace output (top of page) |
+| `langfuse.trace.input` | Root span | Legacy trace input for existing evaluators |
+| `langfuse.trace.output` | Root span | Legacy trace output for existing evaluators |
 | `langfuse.observation.input` | All spans | Observation input (sidebar click) |
 | `langfuse.observation.output` | All spans | Observation output (sidebar click) |
 | `langfuse.observation.type` | Tool spans | `"tool"` type indicator |
@@ -168,6 +201,12 @@ The instrumentation sets Langfuse-specific attributes that map to the Langfuse U
 | `gen_ai.request.model` | Generation spans only | Model name + cost calculation |
 | `gen_ai.usage.input_tokens` | Generation spans | Token usage |
 | `gen_ai.usage.output_tokens` | Generation spans | Token usage |
+| `gen_ai.usage.reasoning.output_tokens` | Generation spans, when reported | Reasoning tokens within output tokens |
+| `langfuse.observation.metadata.reasoning_summary` | Responses generation spans with `thinking: { display: :summarized }` | Returned summary, when provided |
+
+Langfuse v4 reads overall input and output from `langfuse.observation.input` and `langfuse.observation.output` on the root span. This integration also keeps the deprecated trace input and output attributes for existing consumers. The Langfuse v4 ingestion path needs the `x-langfuse-ingestion-version: 4` exporter header. See the [Langfuse migration guide](https://langfuse.com/integrations/native/opentelemetry/migration-to-v4).
+
+Reasoning tokens are already part of output tokens, so do not add the two counts. The summary field records only text returned for a requested Responses summary. Encrypted reasoning signatures stay in conversation history for stateless replay and are not added to Langfuse spans. Treat persisted conversation history as sensitive data.
 
 ### EU vs US Cloud
 
@@ -202,7 +241,7 @@ OpenTelemetry::SDK.configure do |c|
     OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
       OpenTelemetry::Exporter::OTLP::Exporter.new(
         endpoint: "#{langfuse_host}/api/public/otel/v1/traces",
-        headers: { "Authorization" => "Basic #{auth_token}" }
+        headers: { "Authorization" => "Basic #{auth_token}", "x-langfuse-ingestion-version" => "4" }
       )
     )
   )
@@ -251,7 +290,7 @@ Langfuse renders empty string attributes as "undefined". The instrumentation gua
 
 ### Double-counted costs
 
-If token costs appear inflated, verify that `gen_ai.request.model` is only set on GENERATION spans, not on container or root spans. The built-in instrumentation handles this correctly. If you set custom `span_attributes` that include `gen_ai.request.model`, costs will be double-counted.
+If token costs appear inflated, verify that `gen_ai.request.model` is only set on GENERATION spans, not on container or root spans. `Agents::Instrumentation` handles this by default. If you set custom `span_attributes` that include `gen_ai.request.model`, costs will be double-counted.
 
 ### Empty spans / missing data
 
@@ -266,3 +305,13 @@ If token costs appear inflated, verify that `gen_ai.request.model` is only set o
 - Check that the Authorization header uses `Basic` (not `Bearer`) with base64-encoded `pk:sk`
 - Use `BatchSpanProcessor` for production; `SimpleSpanProcessor` can be useful for debugging
 - **SSL CRL errors on Ruby 3.4+**: The OTLP exporter silently fails when SSL certificate revocation list (CRL) checks fail. The exporter reports SUCCESS but no data arrives. Fix by passing `ssl_verify_mode: OpenSSL::SSL::VERIFY_NONE` to the exporter in development, or ensure your system CA certificates are up to date
+
+## End-to-end check
+
+The optional Langfuse check stubs the model response, exports real OTel spans to your Langfuse project, and reads them back through the observations API. It covers a handoff, token usage, session and user attributes, and a failed tool. Set `LANGFUSE_HOST`, `LANGFUSE_PUBLIC_KEY`, and `LANGFUSE_SECRET_KEY`, then run:
+
+```sh
+RUN_LANGFUSE_E2E=1 bundle exec rspec spec/integration/langfuse_e2e_spec.rb
+```
+
+The model call is stubbed, so this check does not require a provider API key. Use the separate live LLM smoke suite when you also need to check provider access.

data/docs/guides/rails-integration.md

@@ -264,7 +264,7 @@ Create Rails-specific tools for database operations:
 class CustomerLookupTool < Agents::Tool
   name "lookup_customer"
   description "Look up customer information by email or ID"
-  param :identifier, type: "string", desc: "Email address or customer ID"
+  parameter :identifier, type: "string", description: "Email address or customer ID"
 
   def perform(tool_context, identifier:)
     # Access Rails models safely
@@ -286,7 +286,7 @@ end
 class BillingTool < Agents::Tool
   name "get_billing_info"
   description "Retrieve billing information for a customer"
-  param :user_id, type: "integer", desc: "Customer user ID"
+  parameter :user_id, type: "integer", description: "Customer user ID"
 
   def perform(tool_context, user_id:)
     user = User.find(user_id)

data/docs/guides/state-persistence.md

@@ -210,7 +210,7 @@ Tools should be stateless and rely on context for all data:
 class DatabaseTool < Agents::Tool
   name "query_database"
   description "Query the application database"
-  param :query, type: "string", desc: "SQL query to execute"
+  parameter :query, type: "string", description: "SQL query to execute"
   
   def perform(tool_context, query:)
     # Get database connection from context, not instance variables
@@ -238,7 +238,7 @@ Store tool-specific data in context:
 class FileProcessorTool < Agents::Tool
   name "process_file"
   description "Process uploaded files"
-  param :file_path, type: "string", desc: "Path to file"
+  parameter :file_path, type: "string", description: "Path to file"
   
   def perform(tool_context, file_path:)
     # Initialize tool state in context if needed

data/docs/guides/structured-output.md

@@ -41,12 +41,12 @@ result = runner.run("I love the new product features, especially the API and das
 # }
 ```
 
-## RubyLLM::Schema (Recommended)
+## Schematist::Schema (Recommended)
 
-For more complex schemas, use `RubyLLM::Schema` which provides a cleaner Ruby DSL:
+For more complex schemas, use `Schematist::Schema` which provides a cleaner Ruby DSL:
 
 ```ruby
-class ContactSchema < RubyLLM::Schema
+class ContactSchema < Schematist::Schema
   string :name, description: "Full name of the person"
   string :email, description: "Email address"
   string :phone, description: "Phone number", required: false

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

@@ -6,11 +6,11 @@ module Copilot
   # Tool for creating Linear tickets for engineering issues
   class CreateLinearTicketTool < Agents::Tool
     description "Create a Linear ticket for engineering issues or feature requests"
-    param :title, type: "string", desc: "Title of the issue"
-    param :description, type: "string", desc: "Detailed description of the issue"
-    param :priority, type: "string", desc: "Priority level (low, medium, high)"
-    param :assignee, type: "string", desc: "Optional: email of person to assign to", required: false
-    param :labels, type: "string", desc: "Comma-separated labels (e.g., bug,api,production)"
+    parameter :title, type: "string", description: "Title of the issue"
+    parameter :description, type: "string", description: "Detailed description of the issue"
+    parameter :priority, type: "string", description: "Priority level (low, medium, high)"
+    parameter :assignee, type: "string", description: "Optional: email of person to assign to", required: false
+    parameter :labels, type: "string", description: "Comma-separated labels (e.g., bug,api,production)"
 
     def perform(tool_context, title:, description:, priority: "medium", assignee: nil, labels: "")
       # Generate a ticket ID

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

@@ -6,7 +6,7 @@ module Copilot
   # Tool for retrieving specific knowledge base articles by ID
   class GetArticleTool < Agents::Tool
     description "Get the full content of a specific knowledge base article"
-    param :article_id, type: "string", desc: "ID of the article to retrieve (e.g., ART-001)"
+    parameter :article_id, type: "string", description: "ID of the article to retrieve (e.g., ART-001)"
 
     def perform(tool_context, article_id:)
       data_file = File.join(__dir__, "../data/knowledge_base.json")

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

@@ -6,7 +6,7 @@ module Copilot
   # Tool for retrieving contact/customer information
   class GetContactTool < Agents::Tool
     description "Get customer profile and contact information"
-    param :contact_id, type: "string", desc: "ID of the contact to retrieve"
+    parameter :contact_id, type: "string", description: "ID of the contact to retrieve"
 
     def perform(tool_context, contact_id:)
       data_file = File.join(__dir__, "../data/contacts.json")

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

@@ -6,7 +6,7 @@ module Copilot
   # Tool for retrieving conversation details and context
   class GetConversationTool < Agents::Tool
     description "Get conversation details, messages, and context for analysis"
-    param :conversation_id, type: "string", desc: "ID of the conversation to retrieve"
+    parameter :conversation_id, type: "string", description: "ID of the conversation to retrieve"
 
     def perform(tool_context, conversation_id:)
       data_file = File.join(__dir__, "../data/conversations.json")

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

@@ -6,7 +6,7 @@ module Copilot
   # Tool for retrieving Stripe billing information
   class GetStripeBillingTool < Agents::Tool
     description "Get customer billing information and payment history from Stripe"
-    param :customer_email, type: "string", desc: "Customer email to look up billing info"
+    parameter :customer_email, type: "string", description: "Customer email to look up billing info"
 
     def perform(tool_context, customer_email:)
       data_file = File.join(__dir__, "../data/stripe_billing.json")

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

@@ -6,8 +6,9 @@ module Copilot
   # Tool for searching contacts to find patterns and related customers
   class SearchContactsTool < Agents::Tool
     description "Search contacts to find patterns, related customers, or specific profiles"
-    param :query, type: "string", desc: "Search terms (name, email, company, or tags)"
-    param :plan, type: "string", desc: "Optional: filter by plan type (Basic, Pro, Enterprise)", required: false
+    parameter :query, type: "string", description: "Search terms (name, email, company, or tags)"
+    parameter :plan, type: "string", description: "Filter by plan: Basic, Pro, or Enterprise",
+                     required: false
 
     def perform(_tool_context, query:, plan: nil)
       data_file = File.join(__dir__, "../data/contacts.json")

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

@@ -6,8 +6,8 @@ module Copilot
   # Tool for searching through conversation history to find similar cases
   class SearchConversationsTool < Agents::Tool
     description "Search past conversations for similar cases and resolutions"
-    param :query, type: "string", desc: "Search terms (keywords, tags, or issue description)"
-    param :contact_id, type: "string", desc: "Optional: limit search to specific contact", required: false
+    parameter :query, type: "string", description: "Search terms (keywords, tags, or issue description)"
+    parameter :contact_id, type: "string", description: "Optional: limit search to specific contact", required: false
 
     def perform(_tool_context, query:, contact_id: nil)
       data_file = File.join(__dir__, "../data/conversations.json")

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

@@ -6,9 +6,10 @@ 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
+    parameter :query, type: "string", description: "Search terms or keywords to find relevant articles"
+    parameter :category, type: "string",
+                         description: "Filter by category: troubleshooting, account, development, or billing",
+                         required: false
 
     def perform(_tool_context, query:, category: nil)
       data_file = File.join(__dir__, "../data/knowledge_base.json")

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

@@ -6,10 +6,11 @@ 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
+    parameter :query, type: "string", description: "Search issue keywords, errors, or feature descriptions"
+    parameter :status, type: "string", description: "Filter by status: backlog, in progress, completed, or resolved",
+                       required: false
+    parameter :priority, type: "string", description: "Filter by priority: low, medium, or high",
+                         required: false
 
     def perform(_tool_context, query:, status: nil, priority: nil)
       data_file = File.join(__dir__, "../data/linear_issues.json")

data/examples/isp-support/agents_factory.rb

@@ -6,7 +6,7 @@ require_relative "tools/create_lead_tool"
 require_relative "tools/create_checkout_tool"
 require_relative "tools/search_docs_tool"
 require_relative "tools/escalate_to_human_tool"
-require "ruby_llm/schema"
+require "schematist"
 
 module ISPSupport
   # Factory for creating all ISP support agents with proper handoff relationships.
@@ -98,7 +98,7 @@ module ISPSupport
     end
 
     def triage_response_schema
-      RubyLLM::Schema.create do
+      Schematist::Schema.create do
         string :response, description: "Your response to the customer"
         string :intent, enum: %w[sales support unclear], description: "The detected intent category"
         array :sentiment, description: "Customer sentiment indicators" do
@@ -108,7 +108,7 @@ module ISPSupport
     end
 
     def support_response_schema
-      RubyLLM::Schema.create do
+      Schematist::Schema.create do
         string :response, description: "Your response to the customer"
         string :intent, enum: %w[support], description: "The intent category (always support)"
         array :sentiment, description: "Customer sentiment indicators" do
@@ -118,7 +118,7 @@ module ISPSupport
     end
 
     def sales_response_schema
-      RubyLLM::Schema.create do
+      Schematist::Schema.create do
         string :response, description: "Your response to the customer"
         string :intent, enum: %w[sales], description: "The intent category (always sales)"
         array :sentiment, description: "Customer sentiment indicators" do

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

@@ -6,7 +6,7 @@ module ISPSupport
   # Tool for creating checkout links for new service subscriptions.
   class CreateCheckoutTool < Agents::Tool
     description "Create a secure checkout link for a service plan"
-    param :plan_name, type: "string", desc: "Name of the plan to purchase"
+    parameter :plan_name, type: "string", description: "Name of the plan to purchase"
 
     def perform(_tool_context, plan_name:)
       session_id = SecureRandom.hex(8)

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

@@ -4,9 +4,9 @@ module ISPSupport
   # Tool for creating sales leads in the CRM system.
   class CreateLeadTool < Agents::Tool
     description "Create a new sales lead with customer information"
-    param :name, type: "string", desc: "Customer's full name"
-    param :email, type: "string", desc: "Customer's email address"
-    param :desired_plan, type: "string", desc: "Plan the customer is interested in"
+    parameter :name, type: "string", description: "Customer's full name"
+    parameter :email, type: "string", description: "Customer's email address"
+    parameter :desired_plan, type: "string", description: "Plan the customer is interested in"
 
     def perform(tool_context, name:, email:, desired_plan:)
       # Store lead information in state for follow-up

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

@@ -6,7 +6,7 @@ module ISPSupport
   # Tool for looking up customer information from the CRM system.
   class CrmLookupTool < Agents::Tool
     description "Look up customer account information by account ID"
-    param :account_id, type: "string", desc: "Customer account ID (e.g., CUST001)"
+    parameter :account_id, type: "string", description: "Customer account ID (e.g., CUST001)"
 
     def perform(tool_context, account_id:)
       data_file = File.join(__dir__, "../data/customers.json")

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

@@ -4,7 +4,7 @@ module ISPSupport
   # Tool for searching the knowledge base documentation.
   class SearchDocsTool < Agents::Tool
     description "Search knowledge base for troubleshooting steps and solutions"
-    param :query, type: "string", desc: "Search terms or description of the issue"
+    parameter :query, type: "string", description: "Search terms or description of the issue"
 
     def perform(_tool_context, query:)
       case query.downcase

data/lib/agents/agent.rb

@@ -50,8 +50,8 @@ require_relative "helpers/hash_normalizer"
 #   )
 module Agents
   class Agent
-    attr_reader :name, :instructions, :model, :provider, :assume_model_exists, :tools, :handoff_agents, :temperature,
-                :response_schema, :headers, :params
+    attr_reader :name, :instructions, :model, :provider, :protocol, :assume_model_exists, :tools, :handoff_agents,
+                :temperature, :thinking, :response_schema, :headers, :params
 
     # Initialize a new Agent instance
     #
@@ -59,23 +59,32 @@ module Agents
     # @param instructions [String, Proc, nil] Static string or dynamic Proc that returns instructions
     # @param model [String] The LLM model to use (default: "gpt-4.1-mini")
     # @param provider [Symbol, String, nil] Optional RubyLLM provider override
+    # @param protocol [Symbol, String, nil] Optional provider protocol override (e.g., :responses)
     # @param assume_model_exists [Boolean] Whether RubyLLM should skip registry validation for custom model IDs
     # @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
-    # @param temperature [Float] Controls randomness in responses (0.0 = deterministic, 1.0 = very random, default: 0.7)
+    # @param temperature [Float, nil] Sampling temperature; nil uses the model default
+    # @param thinking [Hash, nil] RubyLLM thinking options (e.g., effort: :medium, display: :summarized)
     # @param response_schema [Hash, nil] JSON schema for structured output responses
     # @param headers [Hash, nil] Default HTTP headers applied to LLM requests
     # @param params [Hash, nil] Default provider-specific parameters applied to LLM requests (e.g., service_tier)
-    def initialize(name:, instructions: nil, model: "gpt-4.1-mini", provider: nil, assume_model_exists: false,
-                   tools: [], handoff_agents: [], temperature: 0.7, response_schema: nil, headers: nil, params: nil)
+    def initialize(name:, instructions: nil, model: "gpt-4.1-mini", provider: nil, protocol: nil,
+                   assume_model_exists: false, tools: [], handoff_agents: [], temperature: 0.7, thinking: nil,
+                   response_schema: nil, headers: nil, params: nil)
       @name = name
       @instructions = instructions
       @model = model
       @provider = provider&.to_sym
+      @protocol = protocol&.to_sym
       @assume_model_exists = assume_model_exists
       @tools = tools.dup
       @handoff_agents = []
       @temperature = temperature
+      @thinking = if thinking.nil?
+                    nil
+                  else
+                    Helpers::HashNormalizer.normalize(thinking, label: "thinking", freeze_result: true)
+                  end
       @response_schema = response_schema
       @headers = Helpers::HashNormalizer.normalize(headers, label: "headers", freeze_result: true)
       @params = Helpers::HashNormalizer.normalize(params, label: "params", freeze_result: true)
@@ -131,7 +140,7 @@ module Agents
 
     # Creates a new agent instance with modified attributes while preserving immutability.
     # The clone method is used when you need to create variations of agents without mutating the original.
-    # This can be used for runtime agent modifications, say in a multi-tenant environment we can do something like the following:
+    # This can be used for runtime agent modifications, such as multi-tenant settings:
     #
     # @example Multi-tenant agent customization
     #   def agent_for_tenant(tenant)
@@ -161,10 +170,12 @@ module Agents
     # @option changes [String, Proc] :instructions New instructions
     # @option changes [String] :model New model identifier
     # @option changes [Symbol, String, nil] :provider New provider override
+    # @option changes [Symbol, String, nil] :protocol New provider protocol override
     # @option changes [Boolean] :assume_model_exists Whether to skip model registry validation
     # @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)
+    # @option changes [Hash, nil] :thinking RubyLLM thinking options
     # @option changes [Hash, nil] :response_schema JSON schema for structured output
     # @return [Agents::Agent] A new frozen agent instance with the specified changes
     def clone(**changes)
@@ -173,10 +184,12 @@ module Agents
         instructions: changes.fetch(:instructions, @instructions),
         model: changes.fetch(:model, @model),
         provider: changes.fetch(:provider, @provider),
+        protocol: changes.fetch(:protocol, @protocol),
         assume_model_exists: changes.fetch(:assume_model_exists, @assume_model_exists),
         tools: changes.fetch(:tools, @tools.dup),
         handoff_agents: changes.fetch(:handoff_agents, @handoff_agents),
         temperature: changes.fetch(:temperature, @temperature),
+        thinking: changes.fetch(:thinking, @thinking),
         response_schema: changes.fetch(:response_schema, @response_schema),
         headers: changes.fetch(:headers, @headers),
         params: changes.fetch(:params, @params)

data/lib/agents/agent_tool.rb

@@ -40,7 +40,7 @@ module Agents
     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"
+    parameter :input, type: "string", description: "Input message for the agent"
 
     # Initialize an AgentTool that wraps an agent as a callable tool
     #

data/lib/agents/handoff.rb

@@ -69,19 +69,16 @@ module Agents
       @tool_description
     end
 
-    # Use RubyLLM's halt mechanism to stop continuation after handoff
+    # The runner switches agents after this tool records the handoff.
     # Store handoff info in context for Runner to detect and process
     def perform(tool_context)
       # Store handoff information in context for Runner to detect
-      # TODO: The following is a race condition that needs to be addressed in future versions
-      # If multiple handoff tools execute concurrently, they overwrite each other's pending_handoff data.
       tool_context.run_context.context[:pending_handoff] = {
         target_agent: @target_agent,
         timestamp: Time.now
       }
 
-      # Return halt to stop LLM continuation
-      halt("I'll transfer you to #{@target_agent.name} who can better assist you with this.")
+      "I'll transfer you to #{@target_agent.name} who can better assist you with this."
     end
 
     # NOTE: RubyLLM will handle schema generation internally when needed