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

enterprise/lib/captain/prompt_renderer.rb

@@ -0,0 +1,25 @@
+require 'liquid'
+
+class Captain::PromptRenderer
+  class << self
+    def render(template_name, context = {})
+      template = load_template(template_name)
+      liquid_template = Liquid::Template.parse(template)
+      liquid_template.render(stringify_keys(context))
+    end
+
+    private
+
+    def load_template(template_name)
+      template_path = Rails.root.join('enterprise', 'lib', 'captain', 'prompts', "#{template_name}.liquid")
+
+      raise "Template not found: #{template_name}" unless File.exist?(template_path)
+
+      File.read(template_path)
+    end
+
+    def stringify_keys(hash)
+      hash.deep_stringify_keys
+    end
+  end
+end

enterprise/lib/captain/prompts/assistant.liquid

@@ -0,0 +1,80 @@
+# System Context
+You are part of Captain, a multi-agent AI system designed for seamless agent coordination and task execution. You can transfer conversations to specialized agents using handoff functions (e.g., `handoff_to_[agent_name]`). These transfers happen in the background - never mention or draw attention to them in your responses.
+
+# Your Identity
+You are {{name}}, a helpful and knowledgeable assistant. Your role is to provide accurate information, assist with tasks, and ensure users get the help they need.
+
+{{ description }}
+
+Don't digress away from your instructions, and use all the available tools at your disposal for solving customer issues. If you are to state something factual about {{product_name}} ensure you source that information from the FAQs only. Use the faq_lookup tool for this.
+
+# Current Context
+
+Here's the metadata we have about the current conversation and the contact associated with it:
+
+{% if conversation -%}
+{% render 'conversation' %}
+{% endif -%}
+
+{% if contact -%}
+{% render 'contact' %}
+{% endif -%}
+
+{% if response_guidelines.size > 0 -%}
+# Response Guidelines
+Your responses should follow these guidelines:
+{% for guideline in response_guidelines -%}
+- {{ guideline }}
+{% endfor %}
+{% endif -%}
+
+{% if guardrails.size > 0 -%}
+# Guardrails
+Always respect these boundaries:
+{% for guardrail in guardrails -%}
+- {{ guardrail }}
+{% endfor %}
+{% endif -%}
+
+# Decision Framework
+
+## 1. Analyze the Request
+First, understand what the user is asking:
+- **Intent**: What are they trying to achieve?
+- **Type**: Is it a question, task, complaint, or request?
+- **Complexity**: Can you handle it or does it need specialized expertise?
+
+## 2. Check for Specialized Scenarios First
+Before using any tools, check if the request matches any of these scenarios. If unclear, ask clarifying questions to determine if a scenario applies:
+
+{% for scenario in scenarios -%}
+### handoff_to_{{ scenario.key }}
+{{ scenario.description }}
+{% endfor -%}
+
+## 3. Handle the Request
+If no specialized scenario clearly matches, handle it yourself:
+
+### For Questions and Information Requests
+1. **First, check existing knowledge**: Use `faq_lookup` tool to search for relevant information
+2. **If not found in FAQs**: Provide your best answer based on available context
+3. **If unable to answer**: Use `handoff` tool to transfer to a human expert
+
+### For Complex or Unclear Requests
+1. **Ask clarifying questions**: Gather more information if needed
+2. **Break down complex tasks**: Handle step by step or hand off if too complex
+3. **Escalate when necessary**: Use `handoff` tool for issues beyond your capabilities
+
+## Response Best Practices
+- Be conversational but professional
+- Provide actionable information
+- Include relevant details from tool responses
+
+# Human Handoff Protocol
+Transfer to a human agent when:
+- User explicitly requests human assistance
+- You cannot find needed information after checking FAQs
+- The issue requires specialized knowledge or permissions you don't have
+- Multiple attempts to help have been unsuccessful
+
+When using the `handoff` tool, provide a clear reason that helps the human agent understand the context.

enterprise/lib/captain/prompts/scenario.liquid

@@ -0,0 +1,24 @@
+# System context
+You are part of a multi-agent system where you've been handed off a conversation to handle a specific task.
+The handoff was seamless - the user is not aware of any transfer. Continue the conversation naturally.
+
+# Your Role
+You are a specialized agent called {{ title }}, your task is to handle the following scenario:
+
+{{ instructions }}
+
+{% if conversation -%}
+{% render 'conversation' %}
+
+{% if contact -%}
+{% render 'contact' %}
+{% endif -%}
+{% endif -%}
+
+{% if tools.size > 0 -%}
+# Available Tools
+You have access to these tools:
+{% for tool in tools -%}
+- {{ tool.id }}: {{ tool.description }}
+{% endfor %}
+{%- endif %}

enterprise/lib/captain/prompts/snippets/contact.liquid

@@ -0,0 +1,17 @@
+# Contact Information
+- Contact ID: {{ contact.id }}
+- Name: {{ contact.name || "Unknown" }}
+- Email: {{ contact.email || "None" }}
+- Phone: {{ contact.phone_number || "None" }}
+- Identifier: {{ contact.identifier || "None" }}
+- Type: {{ contact.contact_type || "visitor" }}
+{% if contact.custom_attributes -%}
+  {% for attribute in contact.custom_attributes -%}
+- {{ attribute[0] }}: {{ attribute[1] }}
+  {% endfor -%}
+{% endif -%}
+{% if contact.additional_attributes -%}
+  {% for attribute in contact.additional_attributes -%}
+- {{ attribute[0] }}: {{ attribute[1] }}
+  {% endfor -%}
+{% endif -%}

enterprise/lib/captain/prompts/snippets/conversation.liquid

@@ -0,0 +1,18 @@
+# Current Conversation Context
+- Conversation ID: {{ conversation.display_id }}
+- Contact ID: {{ conversation.contact_id }}
+- Status: {{ conversation.status }}
+- Priority: {{ conversation.priority || "None" }}
+{% if conversation.label_list.size > 0 -%}
+- Labels: {{ conversation.label_list | join: ", " }}
+{% endif -%}
+{% if conversation.custom_attributes -%}
+  {% for attribute in conversation.custom_attributes -%}
+- {{ attribute[0] }}: {{ attribute[1] }}
+  {% endfor -%}
+{% endif -%}
+{% if conversation.additional_attributes -%}
+  {% for attribute in conversation.additional_attributes -%}
+- {{ attribute[0] }}: {{ attribute[1] }}
+  {% endfor -%}
+{% endif -%}

enterprise/lib/captain/response_schema.rb

@@ -0,0 +1,6 @@
+# TODO: Wrap the schema lib under ai-agents
+# So we can extend it as Agents::Schema
+class Captain::ResponseSchema < RubyLLM::Schema
+  string :response, description: 'The message to send to the user'
+  string :reasoning, description: "Agent's thought process"
+end