ai-agents 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71f4852e0a5f1048dfeefa4b3ab678de189977940330f81425b60f687e66adc0
-  data.tar.gz: 5661b109441687dbdba66208c71798e91bbd338e857619fcc3b634b4542662cb
+  metadata.gz: 9a2d71857e9614f2dad748a9510a5f29925cf070dd7a7dad59ac8a243eadbc28
+  data.tar.gz: e0f836ad647303fdd3482ca1f1d144bda34573d74ff8741487a4a0b550860f01
 SHA512:
-  metadata.gz: 8070c4bc7fd3d9aa9477b2566d0e96f44166c8320b12cdf50017c9c19081ef539a7c20b369714afc0fb468f7c767fcb8f50ff52aae3491357bee69971c99a531
-  data.tar.gz: 0d11ee7a275f5a240ceaf695ac3a3a1aea196aaa452f6fb38cb79ca8e411fd278b9fa526e3a48911ec856c96d84d2cc565ff5f7359771d3a2057ecbdf6b4f675
+  metadata.gz: 2728cc0f9e4b377c438ecfd73db1ff0e72e3399f8c5602c330b78fcfb53f081bbd80e44bb3036549f0b906b8df09da5ecff371af3b895f7b0e98645e74809967
+  data.tar.gz: c22baa1ce3c5aef5e1a2d17e208eb040f49edb46f4d275946e93fab506dcb3cc40eb1dfc9638f62beadec19a61421fe27d9fe079268b0b867b7c787a2c31cb19

data/CHANGELOG.md

@@ -5,6 +5,22 @@ 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

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/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

@@ -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

@@ -45,7 +45,8 @@ module ISPSupport
         instructions: triage_instructions,
         model: "gpt-4.1-mini",
         tools: [],
-        temperature: 0.3  # Lower temperature for consistent routing decisions
+        temperature: 0.3, # Lower temperature for consistent routing decisions
+        response_schema: triage_response_schema
       )
     end
 
@@ -88,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, :temperature
+    attr_reader :name, :instructions, :model, :tools, :handoff_agents, :temperature, :response_schema
 
     # Initialize a new Agent instance
     #
@@ -43,13 +60,16 @@ module Agents
     # @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)
-    def initialize(name:, instructions: nil, model: "gpt-4.1-mini", tools: [], handoff_agents: [], temperature: 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
@@ -134,6 +154,7 @@ module Agents
     # @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(
@@ -142,7 +163,8 @@ module Agents
         model: changes.fetch(:model, @model),
         tools: changes.fetch(:tools, @tools.dup),
         handoff_agents: changes.fetch(:handoff_agents, @handoff_agents),
-        temperature: changes.fetch(:temperature, @temperature)
+        temperature: changes.fetch(:temperature, @temperature),
+        response_schema: changes.fetch(:response_schema, @response_schema)
       )
     end
 

data/lib/agents/chat.rb

@@ -26,7 +26,8 @@ module Agents
       end
     end
 
-    def initialize(model: nil, handoff_tools: [], context_wrapper: nil, temperature: 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
@@ -34,6 +35,9 @@ module Agents
       # 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

@@ -248,7 +248,8 @@ module Agents
         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.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ai-agents
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  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