feat: captain custom tools v1 (#13890)

# Pull Request Template

## Description

Adds custom tool support to v1

## Type of change
- [x] New feature (non-breaking change which adds functionality)


## How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide
instructions so we can reproduce. Please also list any relevant details
for your test configuration.

<img width="1816" height="958" alt="CleanShot 2026-03-24 at 11 37 33@2x"
src="https://github.com/user-attachments/assets/2777a953-8b65-4a2d-88ec-39f395b3fb47"
/>

<img width="378" height="488" alt="CleanShot 2026-03-24 at 11 38 18@2x"
src="https://github.com/user-attachments/assets/f6973c99-efd0-40e4-90fe-4472a2f63cea"
/>

<img width="1884" height="1452" alt="CleanShot 2026-03-24 at 11 38
32@2x"
src="https://github.com/user-attachments/assets/9fba4fc4-0c33-46da-888a-52ec6bad6130"
/>



## Checklist:

- [x] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented on my code, particularly in hard-to-understand
areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published in downstream
modules

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Shivam Mishra <scm.mymail@gmail.com>

enterprise/app/services/captain/llm/assistant_chat_service.rb

@@ -30,7 +30,12 @@ class Captain::Llm::AssistantChatService < Llm::BaseAiService
   private
 
   def build_tools
-    [Captain::Tools::SearchDocumentationService.new(@assistant, user: nil)]
+    tools = [Captain::Tools::SearchDocumentationService.new(@assistant, user: nil)]
+    return tools unless custom_tools_enabled?
+
+    tools + @assistant.account.captain_custom_tools.enabled.map do |ct|
+      ct.tool(@assistant, base_class: Captain::Tools::CustomHttpTool, conversation: @conversation)
+    end
   end
 
   def system_message
@@ -38,11 +43,24 @@ class Captain::Llm::AssistantChatService < Llm::BaseAiService
       role: 'system',
       content: Captain::Llm::SystemPromptsService.assistant_response_generator(
         @assistant.name, @assistant.config['product_name'], @assistant.config,
-        contact: contact_attributes
+        contact: contact_attributes,
+        custom_tools: custom_tools_metadata
       )
     }
   end
 
+  def custom_tools_metadata
+    return [] unless custom_tools_enabled?
+
+    @assistant.account.captain_custom_tools.enabled.map do |ct|
+      { name: ct.slug, description: ct.description }
+    end
+  end
+
+  def custom_tools_enabled?
+    @assistant.account.feature_enabled?('custom_tools')
+  end
+
   def contact_attributes
     return nil unless @conversation&.contact
     return nil unless @assistant&.feature_contact_attributes

enterprise/app/services/captain/llm/system_prompts_service.rb

@@ -152,7 +152,7 @@ class Captain::Llm::SystemPromptsService
     # rubocop:enable Metrics/MethodLength
 
     # rubocop:disable Metrics/MethodLength
-    def assistant_response_generator(assistant_name, product_name, config = {}, contact: nil)
+    def assistant_response_generator(assistant_name, product_name, config = {}, contact: nil, custom_tools: [])
       assistant_citation_guidelines = if config['feature_citation']
                                         <<~CITATION_TEXT
                                           - Always include citations for any information provided, referencing the specific source (document only - skip if it was derived from a conversation).
@@ -187,7 +187,7 @@ class Captain::Llm::SystemPromptsService
         #{assistant_citation_guidelines}
 
         #{build_contact_context(contact)}[Task]
-        Start by introducing yourself. Then, ask the user to share their question. When they answer, call the search_documentation function. Give a helpful response based on the steps written below.
+        Start by introducing yourself. Then, ask the user to share their question. When they answer, use the most appropriate tool to find information. Give a helpful response based on the steps written below.
 
         - Provide the user with the steps required to complete the action one by one.
         - Do not return list numbers in the steps, just the plain text is enough.
@@ -203,6 +203,8 @@ class Captain::Llm::SystemPromptsService
         ```
         - If the answer is not provided in context sections, Respond to the customer and ask whether they want to talk to another support agent . If they ask to Chat with another agent, return `conversation_handoff' as the response in JSON response
         #{'- You MUST provide numbered citations at the appropriate places in the text.' if config['feature_citation']}
+
+        #{build_tools_section(custom_tools)}
       SYSTEM_PROMPT_MESSAGE
     end
 
@@ -291,6 +293,15 @@ class Captain::Llm::SystemPromptsService
 
     private
 
+    def build_tools_section(custom_tools)
+      tools_list = custom_tools.map { |t| "- #{t[:name]}: #{t[:description]}" }.join("\n")
+      <<~TOOLS.strip
+        [Available Tools]
+        - search_documentation: Search and retrieve documentation from knowledge base
+        #{tools_list}
+      TOOLS
+    end
+
     def build_contact_context(contact)
       return '' if contact.nil?
 

enterprise/app/services/captain/tools/custom_http_tool.rb

@@ -0,0 +1,47 @@
+# V1-compatible wrapper for custom HTTP tools.
+#
+# V2's HttpTool inherits from Agents::Tool which overrides execute(tool_context, **params),
+# making it incompatible with V1's RubyLLM pipeline that calls execute(**keyword_args).
+#
+# This class bridges the gap: it inherits from BaseTool (RubyLLM::Tool) for V1 compatibility
+# and delegates the actual HTTP execution to HttpTool#perform.
+class Captain::Tools::CustomHttpTool < Captain::Tools::BaseTool
+  # BaseTool prepends Instrumentation, but our execute() shadows it in the MRO.
+  # Re-prepend so Langfuse captures tool call input/output/timing.
+  prepend Captain::Tools::Instrumentation
+
+  attr_reader :custom_tool
+
+  def initialize(assistant, custom_tool, conversation: nil)
+    @custom_tool = custom_tool
+    @conversation = conversation
+    super(assistant)
+  end
+
+  def active?
+    @custom_tool.enabled?
+  end
+
+  def execute(**params)
+    http_tool = Captain::Tools::HttpTool.new(assistant, @custom_tool)
+    http_tool.perform(build_tool_context, **params)
+  end
+
+  private
+
+  def build_tool_context
+    state = { account_id: assistant.account_id, assistant_id: assistant.id }
+    add_conversation_state(state) if @conversation
+    OpenStruct.new(state: state)
+  end
+
+  def add_conversation_state(state)
+    state[:conversation] = { id: @conversation.id, display_id: @conversation.display_id }
+    state[:contact] = slice_record_attrs(@conversation.contact, :id, :email, :phone_number)
+    state[:contact_inbox] = slice_record_attrs(@conversation.contact_inbox, :id, :hmac_verified)
+  end
+
+  def slice_record_attrs(record, *keys)
+    record&.attributes&.symbolize_keys&.slice(*keys)
+  end
+end

enterprise/app/services/enterprise/billing/reconcile_plan_features_service.rb

@@ -17,7 +17,7 @@ class Enterprise::Billing::ReconcilePlanFeaturesService
     linear_integration
   ].freeze
 
-  BUSINESS_PLAN_FEATURES = %w[sla custom_roles csat_review_notes conversation_required_attributes advanced_assignment].freeze
+  BUSINESS_PLAN_FEATURES = %w[sla custom_roles csat_review_notes conversation_required_attributes advanced_assignment custom_tools].freeze
   ENTERPRISE_PLAN_FEATURES = %w[audit_logs disable_branding saml].freeze
   PREMIUM_PLAN_FEATURES = (STARTUP_PLAN_FEATURES + BUSINESS_PLAN_FEATURES + ENTERPRISE_PLAN_FEATURES).freeze