feat: scenario agents & runner (#11944)

Co-authored-by: Muhsin Keloth <muhsinkeramam@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Sojan Jose <sojan@pepalo.com>
Co-authored-by: Pranav <pranav@chatwoot.com>
Co-authored-by: Sivin Varghese <64252451+iamsivin@users.noreply.github.com>

enterprise/app/jobs/captain/conversation/response_builder_job.rb

@@ -26,9 +26,15 @@ class Captain::Conversation::ResponseBuilderJob < ApplicationJob
   delegate :account, :inbox, to: :@conversation
 
   def generate_and_process_response
-    @response = Captain::Llm::AssistantChatService.new(assistant: @assistant).generate_response(
-      message_history: collect_previous_messages
-    )
+    @response = if captain_v2_enabled?
+                  Captain::Assistant::AgentRunnerService.new(assistant: @assistant, conversation: @conversation).generate_response(
+                    message_history: collect_previous_messages
+                  )
+                else
+                  Captain::Llm::AssistantChatService.new(assistant: @assistant).generate_response(
+                    message_history: collect_previous_messages
+                  )
+                end
 
     return process_action('handoff') if handoff_requested?
 
@@ -104,4 +110,8 @@ class Captain::Conversation::ResponseBuilderJob < ApplicationJob
   def log_error(error)
     ChatwootExceptionTracker.new(error, account: account).capture_exception
   end
+
+  def captain_v2_enabled?
+    return account.feature_enabled?('captain_integration_v2')
+  end
 end

enterprise/app/models/captain/assistant.rb

@@ -19,6 +19,7 @@
 class Captain::Assistant < ApplicationRecord
   include Avatarable
   include Concerns::CaptainToolsHelpers
+  include Concerns::Agentable
 
   self.table_name = 'captain_assistants'
 
@@ -35,6 +36,8 @@ class Captain::Assistant < ApplicationRecord
   has_many :copilot_threads, dependent: :destroy_async
   has_many :scenarios, class_name: 'Captain::Scenario', dependent: :destroy_async
 
+  store_accessor :config, :temperature, :feature_faq, :feature_memory, :product_name
+
   validates :name, presence: true
   validates :description, presence: true
   validates :account_id, presence: true
@@ -71,6 +74,33 @@ class Captain::Assistant < ApplicationRecord
 
   private
 
+  def agent_name
+    name
+  end
+
+  def agent_tools
+    [
+      self.class.resolve_tool_class('faq_lookup').new(self),
+      self.class.resolve_tool_class('handoff').new(self)
+    ]
+  end
+
+  def prompt_context
+    {
+      name: name,
+      description: description,
+      product_name: config['product_name'] || 'this product',
+      scenarios: scenarios.enabled.map do |scenario|
+        {
+          key: scenario.title.parameterize.underscore,
+          description: scenario.description
+        }
+      end,
+      response_guidelines: response_guidelines || [],
+      guardrails: guardrails || []
+    }
+  end
+
   def default_avatar_url
     "#{ENV.fetch('FRONTEND_URL', nil)}/assets/images/dashboard/captain/logo.svg"
   end

enterprise/app/models/captain/scenario.rb

@@ -22,6 +22,7 @@
 #
 class Captain::Scenario < ApplicationRecord
   include Concerns::CaptainToolsHelpers
+  include Concerns::Agentable
 
   self.table_name = 'captain_scenarios'
 
@@ -37,10 +38,43 @@ class Captain::Scenario < ApplicationRecord
 
   scope :enabled, -> { where(enabled: true) }
 
+  delegate :temperature, :feature_faq, :feature_memory, :product_name, to: :assistant
+
   before_save :resolve_tool_references
 
+  def prompt_context
+    {
+      title: title,
+      instructions: resolved_instructions,
+      tools: resolved_tools
+    }
+  end
+
   private
 
+  def agent_name
+    "#{title} Agent".titleize
+  end
+
+  def agent_tools
+    resolved_tools.map { |tool| self.class.resolve_tool_class(tool[:id]) }.map { |tool| tool.new(assistant) }
+  end
+
+  def resolved_instructions
+    instruction.gsub(TOOL_REFERENCE_REGEX) do |match|
+      "#{match} tool "
+    end
+  end
+
+  def resolved_tools
+    return [] if tools.blank?
+
+    available_tools = self.class.available_agent_tools
+    tools.filter_map do |tool_id|
+      available_tools.find { |tool| tool[:id] == tool_id }
+    end
+  end
+
   # Validates that all tool references in the instruction are valid.
   # Parses the instruction for tool references and checks if they exist
   # in the available tools configuration.

enterprise/app/models/concerns/agentable.rb

@@ -0,0 +1,56 @@
+module Concerns::Agentable
+  extend ActiveSupport::Concern
+
+  def agent
+    Agents::Agent.new(
+      name: agent_name,
+      instructions: ->(context) { agent_instructions(context) },
+      tools: agent_tools,
+      model: agent_model,
+      temperature: temperature.to_f || 0.7,
+      response_schema: agent_response_schema
+    )
+  end
+
+  def agent_instructions(context = nil)
+    enhanced_context = prompt_context
+
+    if context
+      state = context.context[:state] || {}
+      conversation_data = state[:conversation] || {}
+      contact_data = state[:contact] || {}
+      enhanced_context = enhanced_context.merge(
+        conversation: conversation_data,
+        contact: contact_data
+      )
+    end
+
+    Captain::PromptRenderer.render(template_name, enhanced_context.with_indifferent_access)
+  end
+
+  private
+
+  def agent_name
+    raise NotImplementedError, "#{self.class} must implement agent_name"
+  end
+
+  def template_name
+    self.class.name.demodulize.underscore
+  end
+
+  def agent_tools
+    []  # Default implementation, override if needed
+  end
+
+  def agent_model
+    InstallationConfig.find_by(name: 'CAPTAIN_OPEN_AI_MODEL')&.value.presence || OpenAiConstants::DEFAULT_MODEL
+  end
+
+  def agent_response_schema
+    Captain::ResponseSchema
+  end
+
+  def prompt_context
+    raise NotImplementedError, "#{self.class} must implement prompt_context"
+  end
+end

enterprise/app/services/captain/assistant/agent_runner_service.rb

@@ -0,0 +1,161 @@
+require 'agents'
+
+class Captain::Assistant::AgentRunnerService
+  CONVERSATION_STATE_ATTRIBUTES = %i[
+    id display_id inbox_id contact_id status priority
+    label_list custom_attributes additional_attributes
+  ].freeze
+
+  CONTACT_STATE_ATTRIBUTES = %i[
+    id name email phone_number identifier contact_type
+    custom_attributes additional_attributes
+  ].freeze
+
+  def initialize(assistant:, conversation: nil, callbacks: {})
+    @assistant = assistant
+    @conversation = conversation
+    @callbacks = callbacks
+  end
+
+  def generate_response(message_history: [])
+    agents = build_and_wire_agents
+    context = build_context(message_history)
+    message_to_process = extract_last_user_message(message_history)
+    runner = Agents::Runner.with_agents(*agents)
+    runner = add_callbacks_to_runner(runner) if @callbacks.any?
+    result = runner.run(message_to_process, context: context)
+
+    process_agent_result(result)
+  rescue StandardError => e
+    # when running the agent runner service in a rake task, the conversation might not have an account associated
+    # for regular production usage, it will run just fine
+    ChatwootExceptionTracker.new(e, account: @conversation&.account).capture_exception
+    Rails.logger.error "[Captain V2] AgentRunnerService error: #{e.message}"
+    Rails.logger.error e.backtrace.join("\n")
+
+    error_response(e.message)
+  end
+
+  private
+
+  def build_context(message_history)
+    conversation_history = message_history.map do |msg|
+      content = extract_text_from_content(msg[:content])
+
+      {
+        role: msg[:role].to_sym,
+        content: content,
+        agent_name: msg[:agent_name]
+      }
+    end
+
+    {
+      conversation_history: conversation_history,
+      state: build_state
+    }
+  end
+
+  def extract_last_user_message(message_history)
+    last_user_msg = message_history.reverse.find { |msg| msg[:role] == 'user' }
+
+    extract_text_from_content(last_user_msg[:content])
+  end
+
+  def extract_text_from_content(content)
+    # Handle structured output from agents
+    return content[:response] || content['response'] || content.to_s if content.is_a?(Hash)
+
+    return content unless content.is_a?(Array)
+
+    text_parts = content.select { |part| part[:type] == 'text' }.pluck(:text)
+    text_parts.join(' ')
+  end
+
+  # Response formatting methods
+  def process_agent_result(result)
+    Rails.logger.info "[Captain V2] Agent result: #{result.inspect}"
+    format_response(result.output)
+  end
+
+  def format_response(output)
+    return output.with_indifferent_access if output.is_a?(Hash)
+
+    # Fallback for backwards compatibility
+    {
+      'response' => output.to_s,
+      'reasoning' => 'Processed by agent'
+    }
+  end
+
+  def error_response(error_message)
+    {
+      'response' => 'conversation_handoff',
+      'reasoning' => "Error occurred: #{error_message}"
+    }
+  end
+
+  def build_state
+    state = {
+      account_id: @assistant.account_id,
+      assistant_id: @assistant.id,
+      assistant_config: @assistant.config
+    }
+
+    if @conversation
+      state[:conversation] = @conversation.attributes.symbolize_keys.slice(*CONVERSATION_STATE_ATTRIBUTES)
+      state[:contact] = @conversation.contact.attributes.symbolize_keys.slice(*CONTACT_STATE_ATTRIBUTES) if @conversation.contact
+    end
+
+    state
+  end
+
+  def build_and_wire_agents
+    assistant_agent = @assistant.agent
+    scenario_agents = @assistant.scenarios.enabled.map(&:agent)
+
+    assistant_agent.register_handoffs(*scenario_agents) if scenario_agents.any?
+    scenario_agents.each { |scenario_agent| scenario_agent.register_handoffs(assistant_agent) }
+
+    [assistant_agent] + scenario_agents
+  end
+
+  def add_callbacks_to_runner(runner)
+    runner = add_agent_thinking_callback(runner) if @callbacks[:on_agent_thinking]
+    runner = add_tool_start_callback(runner) if @callbacks[:on_tool_start]
+    runner = add_tool_complete_callback(runner) if @callbacks[:on_tool_complete]
+    runner = add_agent_handoff_callback(runner) if @callbacks[:on_agent_handoff]
+    runner
+  end
+
+  def add_agent_thinking_callback(runner)
+    runner.on_agent_thinking do |*args|
+      @callbacks[:on_agent_thinking].call(*args)
+    rescue StandardError => e
+      Rails.logger.warn "[Captain] Callback error for agent_thinking: #{e.message}"
+    end
+  end
+
+  def add_tool_start_callback(runner)
+    runner.on_tool_start do |*args|
+      @callbacks[:on_tool_start].call(*args)
+    rescue StandardError => e
+      Rails.logger.warn "[Captain] Callback error for tool_start: #{e.message}"
+    end
+  end
+
+  def add_tool_complete_callback(runner)
+    runner.on_tool_complete do |*args|
+      @callbacks[:on_tool_complete].call(*args)
+    rescue StandardError => e
+      Rails.logger.warn "[Captain] Callback error for tool_complete: #{e.message}"
+    end
+  end
+
+  def add_agent_handoff_callback(runner)
+    runner.on_agent_handoff do |*args|
+      @callbacks[:on_agent_handoff].call(*args)
+    rescue StandardError => e
+      Rails.logger.warn "[Captain] Callback error for agent_handoff: #{e.message}"
+    end
+  end
+end