ai-agents 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a7f03e74e5438811518c7dc1f6cf24414d24453770858d2a8e12dda823ba428
-  data.tar.gz: d87e91cc47ae009e23db840a29f0fbce3d4c0e913ca3364c1fdaddcdc1816623
+  metadata.gz: 9a2d71857e9614f2dad748a9510a5f29925cf070dd7a7dad59ac8a243eadbc28
+  data.tar.gz: e0f836ad647303fdd3482ca1f1d144bda34573d74ff8741487a4a0b550860f01
 SHA512:
-  metadata.gz: 900501d264a748f85f2c0faa1eb3e1d23a0d9bfc0416eaeebc6fa814446ba0e22d61a93cc97095a76982b915c711603fd7ded72fcc7911bc18875834f95530ab
-  data.tar.gz: 3fceb514188c816412726fa27ff5f88c32b81d6d2d19fe8895576428235ac44eab8161c729e08424c560b44a907dfd9c1c412aa703aaed1bc9694fdb7065f79f
+  metadata.gz: 2728cc0f9e4b377c438ecfd73db1ff0e72e3399f8c5602c330b78fcfb53f081bbd80e44bb3036549f0b906b8df09da5ecff371af3b895f7b0e98645e74809967
+  data.tar.gz: c22baa1ce3c5aef5e1a2d17e208eb040f49edb46f4d275946e93fab506dcb3cc40eb1dfc9638f62beadec19a61421fe27d9fe079268b0b867b7c787a2c31cb19

data/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.4.0] - 2025-08-01
+
+### Added
+- **Structured Output Support**: Agents can now enforce JSON schema validation for responses
+  - Added `response_schema` parameter to `Agent#initialize` supporting both JSON Schema objects and `RubyLLM::Schema` classes
+  - Automatic response validation ensures agents return data in predictable formats
+  - Full support for complex nested schemas with objects, arrays, and validation constraints
+  - Multi-agent systems can use different response schemas per agent
+  - Comprehensive documentation with examples for data extraction and API integrations
+- Updated to RubyLLM 1.5.0 with enhanced structured output capabilities
+- New structured output documentation guide with practical examples
+
+### Changed
+- Enhanced `Chat` class to pass through `response_schema` configuration to underlying RubyLLM provider
+- Improved agent cloning to preserve and override response schemas
+
+## [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/README.md

@@ -18,6 +18,7 @@ A delightful provider agnostic Ruby SDK for building multi-agent AI workflows wi
 - **🤖 Multi-Agent Orchestration**: Create specialized AI agents that work together
 - **🔄 Seamless Handoffs**: Transparent agent-to-agent transfers (users never know!)
 - **🛠️ Tool Integration**: Agents can use custom tools and functions
+- **📊 Structured Output**: JSON schema-validated responses for reliable data extraction
 - **💾 Shared Context**: State management across agent interactions
 - **🔌 Provider Agnostic**: Works with OpenAI, Anthropic, and other LLM providers
 

data/docs/_config.yml

@@ -2,6 +2,8 @@ title: AI Agents
 description: A Ruby SDK for building multi-agent AI workflows
 baseurl: ""
 url: ""
+logo: "/assets/images/ai-agents.png"
+favicon_ico: "/assets/images/favicon.png"
 
 # Theme
 theme: just-the-docs
@@ -12,19 +14,19 @@ color_scheme: ruby
 # Search
 search_enabled: true
 search:
-  heading_level: 2
-  previews: 3
-  preview_words_before: 5
-  preview_words_after: 10
-  tokenizer_separator: /[\s/]+/
+  heading_level: 3
   rel_url: true
-  button: false
+  focus_shortcut_key: "k"
 
 # Navigation
 nav_sort: case_insensitive
 nav_external_links:
   - title: GitHub
     url: https://github.com/chatwoot/ai-agents
+  - title: RubyLLM
+    url: https://rubyllm.com
+  - title: Chatwoot
+    url: https://chatwoot.com/
 
 # Footer
 footer_content: "Copyright © 2025 Chatwoot Inc."

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/structured-output.md

@@ -0,0 +1,76 @@
+---
+layout: default
+title: Structured Output
+parent: Guides
+nav_order: 5
+---
+
+# Structured Output
+
+Structured output ensures AI agents return responses in a predictable JSON format that conforms to a specified schema. This is useful for building reliable integrations, data extraction workflows, and applications that need consistent response formats.
+
+## Basic Usage
+
+Add a `response_schema` when creating an agent to enforce structured responses:
+
+```ruby
+# JSON Schema approach
+extraction_agent = Agents::Agent.new(
+  name: "DataExtractor",
+  instructions: "Extract key information from user messages",
+  response_schema: {
+    type: 'object',
+    properties: {
+      entities: { type: 'array', items: { type: 'string' } },
+      sentiment: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
+      summary: { type: 'string' }
+    },
+    required: ['entities', 'sentiment'],
+    additionalProperties: false
+  }
+)
+
+runner = Agents::AgentRunner.with_agents(extraction_agent)
+result = runner.run("I love the new product features, especially the API and dashboard!")
+
+# Response will be valid JSON matching the schema:
+# {
+#   "entities": ["API", "dashboard"],
+#   "sentiment": "positive",
+#   "summary": "User expresses enthusiasm for new product features"
+# }
+```
+
+## RubyLLM::Schema (Recommended)
+
+For more complex schemas, use `RubyLLM::Schema` which provides a cleaner Ruby DSL:
+
+```ruby
+class ContactSchema < RubyLLM::Schema
+  string :name, description: "Full name of the person"
+  string :email, description: "Email address"
+  string :phone, description: "Phone number", required: false
+  string :company, description: "Company name", required: false
+  array :interests, description: "List of interests or topics mentioned" do
+    string description: "Individual interest or topic"
+  end
+end
+
+contact_agent = Agents::Agent.new(
+  name: "ContactExtractor",
+  instructions: "Extract contact information from business communications",
+  response_schema: ContactSchema
+)
+
+runner = Agents::AgentRunner.with_agents(contact_agent)
+result = runner.run("Hi, I'm Sarah Johnson from TechCorp. You can reach me at sarah@techcorp.com or 555-0123. I'm interested in AI and automation solutions.")
+
+# Returns structured contact data:
+# {
+#   "name": "Sarah Johnson",
+#   "email": "sarah@techcorp.com",
+#   "phone": "555-0123",
+#   "company": "TechCorp",
+#   "interests": ["AI", "automation solutions"]
+# }
+```

data/docs/guides.md

@@ -2,7 +2,7 @@
 layout: default
 title: Guides
 nav_order: 3
-published: false
+published: true
 has_children: true
 ---
 
@@ -16,3 +16,4 @@ Practical guides for building real-world applications with the AI Agents library
 - **[Agent-as-Tool Pattern](guides/agent-as-tool-pattern.html)** - Enable agent collaboration behind the scenes without conversation handoffs
 - **[Rails Integration](guides/rails-integration.html)** - Integrating agents with Ruby on Rails applications and ActiveRecord persistence
 - **[State Persistence](guides/state-persistence.html)** - Managing conversation state and context across sessions and processes
+- **[Structured Output](guides/structured-output.html)** - Enforcing JSON schema validation for reliable agent responses

data/examples/collaborative-copilot/agents/analysis_agent.rb

@@ -11,7 +11,8 @@ module Copilot
         model: "gpt-4o-mini",
         tools: [
           GetConversationTool.new
-        ]
+        ],
+        response_schema: analysis_response_schema
       )
     end
 
@@ -34,15 +35,123 @@ module Copilot
         3. Assess how well the conversation is progressing
         4. Identify any escalation risks or satisfaction issues
 
-        **Provide analysis in this format:**
-        - **Conversation Health**: Overall assessment of how the conversation is going
-        - **Customer Sentiment**: Current emotional state and any changes over time
-        - **Communication Quality**: How well the agent is handling the situation
-        - **Risk Assessment**: Any signs of escalation or dissatisfaction
-        - **Tone Recommendations**: Suggested communication approach and tone
-
+        Your response MUST be in the required JSON format with all the specified fields.
         Focus on practical communication advice that will improve the interaction.
       INSTRUCTIONS
     end
+
+    def self.analysis_response_schema
+      {
+        type: "object",
+        properties: {
+          conversation_health: {
+            type: "object",
+            properties: {
+              status: {
+                type: "string",
+                enum: %w[excellent good fair concerning critical],
+                description: "Overall health status of the conversation"
+              },
+              summary: {
+                type: "string",
+                description: "Brief assessment of how the conversation is progressing"
+              }
+            },
+            required: %w[status summary]
+          },
+          customer_sentiment: {
+            type: "object",
+            properties: {
+              current: {
+                type: "string",
+                enum: %w[very_positive positive neutral negative very_negative],
+                description: "Current emotional state"
+              },
+              trajectory: {
+                type: "string",
+                enum: %w[improving stable declining],
+                description: "How sentiment is changing over time"
+              },
+              key_emotions: {
+                type: "array",
+                items: { type: "string" },
+                description: "Dominant emotions detected (e.g., frustrated, satisfied, confused)"
+              }
+            },
+            required: %w[current trajectory key_emotions]
+          },
+          communication_quality: {
+            type: "object",
+            properties: {
+              score: {
+                type: "integer",
+                minimum: 1,
+                maximum: 10,
+                description: "Overall communication quality score"
+              },
+              strengths: {
+                type: "array",
+                items: { type: "string" },
+                description: "What the agent is doing well"
+              },
+              areas_for_improvement: {
+                type: "array",
+                items: { type: "string" },
+                description: "Areas that could be improved"
+              }
+            },
+            required: %w[score strengths areas_for_improvement]
+          },
+          risk_assessment: {
+            type: "object",
+            properties: {
+              escalation_risk: {
+                type: "string",
+                enum: %w[none low medium high],
+                description: "Risk of conversation escalating"
+              },
+              churn_risk: {
+                type: "string",
+                enum: %w[none low medium high],
+                description: "Risk of customer churning"
+              },
+              warning_signs: {
+                type: "array",
+                items: { type: "string" },
+                description: "Specific warning signs detected"
+              }
+            },
+            required: %w[escalation_risk churn_risk warning_signs]
+          },
+          tone_recommendations: {
+            type: "object",
+            properties: {
+              recommended_tone: {
+                type: "string",
+                description: "Suggested overall tone (e.g., empathetic, professional, friendly)"
+              },
+              key_phrases: {
+                type: "array",
+                items: { type: "string" },
+                description: "Suggested phrases to use"
+              },
+              avoid_phrases: {
+                type: "array",
+                items: { type: "string" },
+                description: "Phrases or approaches to avoid"
+              },
+              next_steps: {
+                type: "string",
+                description: "Recommended immediate next action"
+              }
+            },
+            required: %w[recommended_tone key_phrases avoid_phrases next_steps]
+          }
+        },
+        required: %w[conversation_health customer_sentiment communication_quality risk_assessment
+                     tone_recommendations],
+        additionalProperties: false
+      }
+    end
   end
 end

data/examples/collaborative-copilot/interactive.rb

@@ -1,6 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+require "json"
 require_relative "../../lib/agents"
 require_relative "agents/copilot_orchestrator"
 
@@ -80,7 +81,53 @@ loop do
     # Update context with the returned context from Runner
     context = result.context if result.respond_to?(:context) && result.context
 
-    puts result.output
+    output = result.output
+
+    # Check if the output might be structured JSON (e.g., from Analysis Agent)
+    if output&.strip&.start_with?("{") && context[:current_agent] == "Analysis Agent"
+      begin
+        analysis = JSON.parse(output)
+
+        # Display structured analysis in a readable format
+        puts "\n📊 Conversation Analysis:"
+        puts "━" * 60
+
+        # Conversation Health
+        health = analysis["conversation_health"]
+        puts "🏥 Health: #{health["status"].upcase} - #{health["summary"]}"
+
+        # Customer Sentiment
+        sentiment = analysis["customer_sentiment"]
+        puts "😊 Sentiment: #{sentiment["current"]} (#{sentiment["trajectory"]})"
+        puts "   Emotions: #{sentiment["key_emotions"].join(", ")}"
+
+        # Communication Quality
+        quality = analysis["communication_quality"]
+        puts "💬 Communication: #{quality["score"]}/10"
+        puts "   ✅ Strengths: #{quality["strengths"].join(", ")}" if quality["strengths"].any?
+        puts "   ⚠️  Improve: #{quality["areas_for_improvement"].join(", ")}" if quality["areas_for_improvement"].any?
+
+        # Risk Assessment
+        risk = analysis["risk_assessment"]
+        puts "⚠️  Risks: Escalation=#{risk["escalation_risk"]}, Churn=#{risk["churn_risk"]}"
+        puts "   Warning signs: #{risk["warning_signs"].join(", ")}" if risk["warning_signs"].any?
+
+        # Tone Recommendations
+        tone = analysis["tone_recommendations"]
+        puts "\n💡 Recommendations:"
+        puts "   Tone: #{tone["recommended_tone"]}"
+        puts "   Next: #{tone["next_steps"]}"
+        puts "   Use: #{tone["key_phrases"].join("; ")}" if tone["key_phrases"].any?
+        puts "   Avoid: #{tone["avoid_phrases"].join("; ")}" if tone["avoid_phrases"].any?
+
+        puts "━" * 60
+      rescue JSON::ParserError
+        # Fall back to regular output if not valid JSON
+        puts output
+      end
+    else
+      puts output
+    end
   rescue StandardError => e
     puts "Error: #{e.message}"
   end

data/examples/isp-support/agents_factory.rb

@@ -44,7 +44,9 @@ module ISPSupport
         name: "Triage Agent",
         instructions: triage_instructions,
         model: "gpt-4.1-mini",
-        tools: []
+        tools: [],
+        temperature: 0.3, # Lower temperature for consistent routing decisions
+        response_schema: triage_response_schema
       )
     end
 
@@ -53,7 +55,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 +69,8 @@ module ISPSupport
           ISPSupport::CrmLookupTool.new,
           ISPSupport::SearchDocsTool.new,
           ISPSupport::EscalateToHumanTool.new
-        ]
+        ],
+        temperature: 0.5  # Balanced temperature for helpful but consistent technical support
       )
     end
 
@@ -85,9 +89,43 @@ module ISPSupport
         - If unclear, ask one clarifying question before routing
 
         Keep responses brief and professional. Use handoff tools to transfer to specialists.
+
+        Your response MUST be in the required JSON format with greeting, intent_category, needs_clarification, clarifying_question, and recommended_agent fields.
       INSTRUCTIONS
     end
 
+    def triage_response_schema
+      {
+        type: "object",
+        properties: {
+          greeting: {
+            type: "string",
+            description: "A brief, friendly greeting acknowledging the customer's inquiry"
+          },
+          intent_category: {
+            type: "string",
+            enum: %w[sales support unclear],
+            description: "The detected category of the customer's intent"
+          },
+          needs_clarification: {
+            type: "boolean",
+            description: "Whether the intent is unclear and needs clarification"
+          },
+          clarifying_question: {
+            type: ["string", "null"],
+            description: "A question to ask if the intent is unclear (null if clear)"
+          },
+          recommended_agent: {
+            type: ["string", "null"],
+            enum: ["Sales Agent", "Support Agent", null],
+            description: "The recommended specialist agent to route to (null if unclear)"
+          }
+        },
+        required: %w[greeting intent_category needs_clarification],
+        additionalProperties: false
+      }
+    end
+
     def sales_instructions
       <<~INSTRUCTIONS
         You are the Sales Agent for an ISP. You handle new customer acquisition, service upgrades,

data/examples/isp-support/interactive.rb

@@ -55,7 +55,24 @@ class ISPSupportDemo
 
       # Clear status and show response
       clear_status_line
-      puts "🤖 #{result.output || "[No output]"}"
+
+      # Handle structured output from triage agent
+      output = result.output || "[No output]"
+      if @context[:current_agent] == "Triage Agent" && output.start_with?("{")
+        begin
+          structured = JSON.parse(output)
+          # Display the greeting from structured response
+          puts "🤖 #{structured["greeting"]}"
+          if structured["intent_category"]
+            puts "   [Intent: #{structured["intent_category"]}, Routing to: #{structured["recommended_agent"] || "TBD"}]"
+          end
+        rescue JSON::ParserError
+          # Fall back to regular output if not valid JSON
+          puts "🤖 #{output}"
+        end
+      else
+        puts "🤖 #{output}"
+      end
 
       puts
     end

data/lib/agents/agent.rb

@@ -13,6 +13,23 @@
 #     tools: [calculator_tool, weather_tool]
 #   )
 #
+# @example Creating an agent with structured output
+#   agent = Agents::Agent.new(
+#     name: "DataExtractor",
+#     instructions: "Extract structured information from user input",
+#     model: "gpt-4o",
+#     response_schema: {
+#       type: 'object',
+#       properties: {
+#         entities: { type: 'array', items: { type: 'string' } },
+#         sentiment: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
+#         summary: { type: 'string' }
+#       },
+#       required: ['entities', 'sentiment'],
+#       additionalProperties: false
+#     }
+#   )
+#
 # @example Creating an agent with dynamic state-aware instructions
 #   agent = Agents::Agent.new(
 #     name: "Support Agent",
@@ -33,7 +50,7 @@
 #   )
 module Agents
   class Agent
-    attr_reader :name, :instructions, :model, :tools, :handoff_agents
+    attr_reader :name, :instructions, :model, :tools, :handoff_agents, :temperature, :response_schema
 
     # Initialize a new Agent instance
     #
@@ -42,12 +59,17 @@ 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)
+    # @param response_schema [Hash, nil] JSON schema for structured output responses
+    def initialize(name:, instructions: nil, model: "gpt-4.1-mini", tools: [], handoff_agents: [], temperature: 0.7,
+                   response_schema: nil)
       @name = name
       @instructions = instructions
       @model = model
       @tools = tools.dup
       @handoff_agents = []
+      @temperature = temperature
+      @response_schema = response_schema
 
       # Mutex for thread-safe handoff registration
       # While agents are typically configured at startup, we want to ensure
@@ -131,6 +153,8 @@ 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)
+    # @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)
       self.class.new(
@@ -138,7 +162,9 @@ 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),
+        response_schema: changes.fetch(:response_schema, @response_schema)
       )
     end
 

data/lib/agents/chat.rb

@@ -26,11 +26,18 @@ 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, response_schema: 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
+
+      # Set response schema if provided
+      with_schema(response_schema) if response_schema
+
       # Register handoff tools with RubyLLM for schema generation
       @handoff_tools.each { |tool| with_tool(tool) }
     end

data/lib/agents/runner.rb

@@ -246,8 +246,10 @@ 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
+        context_wrapper: context_wrapper,    # Pass context directly
+        response_schema: agent.response_schema # Pass structured output schema
       )
 
       chat.with_instructions(system_prompt) if system_prompt

data/lib/agents/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Agents
-  VERSION = "0.2.2"
+  VERSION = "0.4.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.4.0
 platform: ruby
 authors:
 - Shivam Mishra
@@ -46,6 +46,8 @@ files:
 - docs/_sass/custom/custom.scss
 - docs/architecture.md
 - docs/assets/fonts/InterVariable.woff2
+- docs/assets/images/ai-agents.png
+- docs/assets/images/favicon.png
 - docs/concepts.md
 - docs/concepts/agent-tool.md
 - docs/concepts/agents.md
@@ -59,6 +61,7 @@ files:
 - docs/guides/multi-agent-systems.md
 - docs/guides/rails-integration.md
 - docs/guides/state-persistence.md
+- docs/guides/structured-output.md
 - docs/index.md
 - examples/README.md
 - examples/collaborative-copilot/README.md