Creating Jasmine Tools

Objetivo

Padronizar a criação de ferramentas no escopo Captain::Tools para garantir compatibilidade com Agents::Tool, RubyLLM e o sistema de injeção de dependência da Jasmine.

Caminhos Padrão

• Local principal: enterprise/lib/captain/tools/
• Alternativo (se service-heavy): enterprise/app/services/captain/tools/

Template Base

module Captain
  module Tools
    class NomeDaSuaTool < Captain::Tools::BasePublicTool
      # Definir tool_name se for diferente do nome da classe (Opcional)
      # def name
      #   'nome_da_tool'
      # end

      def description
        'Descrição curta e objetiva do que a ferramenta faz. Isso é visível para a IA.'
      end

      # Definição de Parâmetros (DSL da gem Agents)
      param :parametro_um, type: 'string', desc: 'Descrição do parâmetro', required: true
      param :parametro_dois, type: 'integer', desc: 'Descrição do parâmetro opcional', required: false

      # Método principal de execução
      # tool_context: Objeto de contexto (pode conter estado da conversa)
      # kwargs: Argumentos passados pela IA já normalizados
      def perform(tool_context, **kwargs)
        # 1. Logging Inicial Padronizado
        Rails.logger.info "[#{self.class.name}] Iniciando execução. Params: #{kwargs.inspect}"

        # 2. Resolução de Dependências (Conversa/Contato)
        # O BasePublicTool já tenta popular @conversation e @user no initialize,
        # mas podemos garantir reload ou fallback aqui.
        ensure_context!(tool_context)

        return "Erro: Conversa não identificada." unless @conversation

        # 3. Lógica da Ferramenta
        parametro_um = kwargs[:parametro_um]

        result = executa_logica(parametro_um)

        # 4. Retorno
        # Sempre retornar String ou Hash serializável (JSON friendly)
        result
      rescue StandardError => e
        handle_error(e)
      end

      private

      def ensure_context!(tool_context)
        # Se @conversation não veio no initialize, tenta extrair do contexto
        if @conversation.nil? && tool_context.present?
             state = resolve_context(tool_context)
             @conversation = find_conversation(state)
        end
      end

      def executa_logica(dado)
        # Implementação...
        "Sucesso: #{dado}"
      end

      def handle_error(exception)
        Rails.logger.error "[#{self.class.name}] Erro: #{exception.message}"
        Rails.logger.error exception.backtrace.first(5).join("\n")
        "Ocorreu um erro técnico ao processar sua solicitação: #{exception.message}"
      end
    end
  end
end