Skip to content

A platform for community discussion. Free, open, simple.

25.1 KB
Raw Blame
# frozen_string_literal: true

module DiscourseAi
  module Admin
    class AiAgentsController < ::Admin::AdminController
      InvalidSubagentIds = Class.new(StandardError)

      requires_plugin PLUGIN_NAME

      before_action :find_ai_agent, only: %i[edit update destroy create_user export]

      def index
        ai_agents =
          AiAgent
            .ordered
            .includes(:user, :uploads, :rag_document_sources, ai_agent_mcp_servers: :ai_mcp_server)
            .map { |agent| LocalizedAiAgentSerializer.new(agent, root: false) }

        tools =
          DiscourseAi::Agents::Agent.all_available_tools.map do |tool|
            AiToolSerializer.new(tool, root: false)
          end

        AiTool
          .where(enabled: true)
          .each do |tool|
            tools << {
              id: "custom-#{tool.id}",
              name:
                I18n.t(
                  "discourse_ai.tools.custom_name",
                  name: tool.name.capitalize,
                  tool_name: tool.tool_name,
                ),
              token_count:
                DiscourseAi::Tokenizer::OpenAiCl100kTokenizer.size(tool.signature.to_json),
            }
          end

        DiscourseAi::Completions::NativeTools.all.each do |native_tool|
          tools << {
            id: "#{DiscourseAi::Completions::NativeTools::PREFIX}#{native_tool.id}",
            name: native_tool.name,
            help: native_tool.help,
            native: true,
          }
        end

        llms = DiscourseAi::Configuration::LlmEnumerator.values_for_serialization
        mcp_servers =
          AiMcpServer
            .where(enabled: true)
            .order(:name)
            .map { |server| serialize_mcp_server(server) }

        sorted_tools = tools.sort_by { |t| t.try(:name) || t[:name] || "" }

        render json: {
                 ai_agents: ai_agents,
                 meta: {
                   tools: sorted_tools,
                   llms: llms,
                   mcp_servers: mcp_servers,
                   settings: {
                     rag_images_enabled: SiteSetting.ai_rag_images_enabled,
                   },
                 },
               }
      end

      def new
      end

      def edit
        render_ai_agent_resource(@ai_agent)
      end

      def create
        params = ai_agent_params
        mcp_server_ids = params.delete(:ai_mcp_server_ids)
        mcp_server_tool_names = params.delete(:mcp_server_tool_names) || {}
        ai_agent = AiAgent.new(params.except(:rag_uploads))

        if ai_agent.save
          ensure_ai_agent_user(ai_agent)
          if mcp_server_ids
            sync_mcp_server_assignments(ai_agent, mcp_server_ids, mcp_server_tool_names)
          end
          RagDocumentFragment.link_target_and_uploads(ai_agent, attached_upload_ids(ai_agent))
          log_ai_agent_creation(ai_agent)

          render_ai_agent_resource(ai_agent, status: :created)
        else
          render_json_error ai_agent
        end
      rescue InvalidSubagentIds => e
        render_json_error e.message, status: :unprocessable_entity
      end

      def create_user
        raise Discourse::InvalidAccess if !@ai_agent.supports_bot_user?

        user = @ai_agent.create_user!
        render json: BasicUserSerializer.new(user, root: "user")
      end

      def update
        params = ai_agent_params
        mcp_server_ids = params.delete(:ai_mcp_server_ids)
        mcp_server_tool_names = params.delete(:mcp_server_tool_names) || {}
        initial_attributes = @ai_agent.attributes.dup
        initial_spam_settings = AiModerationSetting.spam if params.key?(:default_llm_id)

        if @ai_agent.update(params.except(:rag_uploads))
          ensure_ai_agent_user(@ai_agent)
          if mcp_server_ids
            sync_mcp_server_assignments(@ai_agent, mcp_server_ids, mcp_server_tool_names)
          end
          RagDocumentFragment.update_target_uploads(@ai_agent, attached_upload_ids(@ai_agent))
          log_ai_agent_update(@ai_agent, initial_attributes)
          log_ai_spam_model_update(initial_spam_settings)

          render_ai_agent_resource(@ai_agent)
        else
          render_json_error @ai_agent
        end
      rescue InvalidSubagentIds => e
        render_json_error e.message, status: :unprocessable_entity
      end

      def destroy
        agent_details = {
          agent_id: @ai_agent.id,
          name: @ai_agent.name,
          description: @ai_agent.description,
        }

        if @ai_agent.destroy
          log_ai_agent_deletion(agent_details)
          head :no_content
        else
          render_json_error @ai_agent
        end
      end

      def export
        agent = AiAgent.find(params[:id])
        exporter = DiscourseAi::AgentExporter.new(agent: agent)

        response.headers[
          "Content-Disposition"
        ] = "attachment; filename=\"#{agent.name.parameterize}.json\""

        render json: exporter.export
      end

      def import
        name = params.dig(:agent, :name) || params.dig(:persona, :name)
        existing_agent = AiAgent.find_by(name: name) if name.present?
        force_update = ActiveModel::Type::Boolean.new.cast(params[:force])
        import_payload = params.to_unsafe_h.except("controller", "action", "format", "force")

        begin
          importer = DiscourseAi::AgentImporter.new(json: import_payload)
          initial_attributes = existing_agent&.attributes&.dup if force_update

          if existing_agent && force_update
            agent = importer.import!(overwrite: true)
            ensure_ai_agent_user(agent)
            log_ai_agent_update(agent, initial_attributes)
            render_ai_agent_resource(agent)
          else
            agent = importer.import!(overwrite: force_update)
            ensure_ai_agent_user(agent)
            log_ai_agent_creation(agent)
            render_ai_agent_resource(agent, status: :created)
          end
        rescue DiscourseAi::AgentImporter::ImportError => e
          render json: {
                   errors: [e.message],
                   conflicts: e.conflicts,
                 },
                 status: :unprocessable_entity
        rescue StandardError => e
          Rails.logger.error("AI Agent import failed: #{e.message}")
          render_json_error "Import failed: #{e.message}", status: :unprocessable_entity
        end
      end

      def stream_reply
        custom_tools = nil
        tool_results = nil
        resume_token = params[:resume_token].to_s

        begin
          custom_tools = stream_reply_custom_tools
          tool_results = stream_reply_tool_results
        rescue ArgumentError => e
          return render_json_error e.message
        end

        if resume_token.present?
          # This is a best-effort fast-fail check. The token can still expire between this
          # check and async execution, which is handled again inside the session loader.
          if !DiscourseAi::AiBot::StreamReplyCustomToolsSession.resume_state_exists?(resume_token)
            return render_json_error(I18n.t("discourse_ai.errors.invalid_stream_resume_token"))
          end

          if tool_results.blank?
            return render_json_error(I18n.t("discourse_ai.errors.no_tool_results_specified"))
          end

          hijack = request.env["rack.hijack"]
          io = hijack.call

          DiscourseAi::AiBot::ResponseHttpStreamer.queue_streamed_reply(
            io: io,
            agent: nil,
            llm_model: nil,
            user: nil,
            topic: nil,
            query: "",
            custom_instructions: "",
            current_user: current_user,
            resume_token: resume_token,
            tool_results: tool_results,
          )
          return
        end

        agent_name = params[:agent_name].presence
        agent_id = params[:agent_id].presence

        agent = AiAgent.find_by(name: agent_name) || AiAgent.find_by(id: agent_id)
        return render_json_error(I18n.t("discourse_ai.errors.agent_not_found")) if agent.nil?

        return render_json_error(I18n.t("discourse_ai.errors.agent_disabled")) if !agent.enabled

        if agent.default_llm.blank? && SiteSetting.ai_default_llm_model.blank?
          return render_json_error(I18n.t("discourse_ai.errors.no_default_llm"))
        end

        if params[:query].blank?
          return render_json_error(I18n.t("discourse_ai.errors.no_query_specified"))
        end

        return render_json_error(I18n.t("discourse_ai.errors.no_user_for_agent")) if !agent.user_id

        if !params[:username] && !params[:user_unique_id]
          return render_json_error(I18n.t("discourse_ai.errors.no_user_specified"))
        end

        user = nil

        if params[:username]
          user = User.find_by_username(params[:username])
          return render_json_error(I18n.t("discourse_ai.errors.user_not_found")) if user.nil?
        elsif params[:user_unique_id]
          user = stage_user
        end

        raise Discourse::NotFound if user.nil?

        topic_id = params[:topic_id].to_i
        topic = nil

        if topic_id > 0
          topic = Topic.find(topic_id)

          if topic.topic_allowed_users.where(user_id: user.id).empty?
            return render_json_error(I18n.t("discourse_ai.errors.user_not_allowed"))
          end
        end

        route =
          DiscourseAi::AiBot::ConversationRoute.resolve(
            authorization_user: current_user,
            modality: :streaming,
            agent_id: agent.id,
            selection_source: :snapshot,
            allow_general_fallback: false,
          )

        hijack = request.env["rack.hijack"]
        io = hijack.call

        DiscourseAi::AiBot::ResponseHttpStreamer.queue_streamed_reply(
          io: io,
          agent: route.agent_record,
          llm_model: route.model,
          user: user,
          topic: topic,
          query: params[:query].to_s,
          custom_instructions: params[:custom_instructions].to_s,
          current_user: current_user,
          custom_tools: custom_tools,
        )
      rescue DiscourseAi::AiBot::ConversationRoute::Error => error
        render_json_error error.message
      end

      private

      AI_STREAM_CONVERSATION_UNIQUE_ID = "ai-stream-conversation-unique-id"
      MAX_STREAM_REPLY_CUSTOM_TOOLS = 20
      MAX_STREAM_REPLY_TOOL_RESULTS = 20
      MAX_STREAM_REPLY_CUSTOM_TOOL_DEFINITION_BYTES = 10_000
      MAX_STREAM_REPLY_TOOL_RESULT_CONTENT_BYTES = 100 * 1024

      def stage_user
        unique_id = params[:user_unique_id].to_s
        field = UserCustomField.find_by(name: AI_STREAM_CONVERSATION_UNIQUE_ID, value: unique_id)

        if field
          field.user
        else
          preferred_username = params[:preferred_username]
          username = UserNameSuggester.suggest(preferred_username || unique_id)

          user =
            User.new(
              username: username,
              email: "#{SecureRandom.hex}@invalid.com",
              staged: true,
              active: false,
            )
          user.custom_fields[AI_STREAM_CONVERSATION_UNIQUE_ID] = unique_id
          user.save!
          user
        end
      end

      def stream_reply_custom_tools
        return [] if !params.key?(:custom_tools)

        raw_tools = params[:custom_tools]
        return [] if raw_tools.blank?

        if !raw_tools.is_a?(Array)
          raise ArgumentError,
                I18n.t(
                  "discourse_ai.errors.invalid_custom_tools",
                  details: I18n.t("discourse_ai.errors.expected_array"),
                )
        end

        if raw_tools.size > MAX_STREAM_REPLY_CUSTOM_TOOLS
          raise ArgumentError,
                I18n.t(
                  "discourse_ai.errors.too_many_custom_tools",
                  max: MAX_STREAM_REPLY_CUSTOM_TOOLS,
                )
        end

        parsed =
          raw_tools.map do |tool|
            hash = normalize_hash_param(tool, key: :custom_tools)
            parameters = hash["parameters"]
            hash["parameters"] = parameters.reject(&:blank?) if parameters.is_a?(Array)
            definition = nil
            begin
              definition =
                DiscourseAi::Completions::ToolDefinition.from_hash(hash.deep_symbolize_keys)
            rescue ArgumentError, NoMethodError => e
              raise ArgumentError,
                    I18n.t("discourse_ai.errors.invalid_custom_tools", details: e.message)
            end
            definition_hash = definition.to_h.stringify_keys
            if definition_hash.to_json.bytesize > MAX_STREAM_REPLY_CUSTOM_TOOL_DEFINITION_BYTES
              raise ArgumentError,
                    I18n.t(
                      "discourse_ai.errors.custom_tool_definition_too_large",
                      max: MAX_STREAM_REPLY_CUSTOM_TOOL_DEFINITION_BYTES,
                    )
            end
            definition_hash
          end

        names = parsed.map { |tool| tool["name"] }
        duplicate_names = names.tally.select { |_, count| count > 1 }.keys
        if duplicate_names.present?
          raise ArgumentError,
                I18n.t(
                  "discourse_ai.errors.duplicate_custom_tools",
                  names: duplicate_names.join(", "),
                )
        end

        parsed
      end

      def stream_reply_tool_results
        if params.key?(:tool_results) && params.key?(:tool_result)
          raise ArgumentError, I18n.t("discourse_ai.errors.ambiguous_tool_results")
        end

        raw_results = params.key?(:tool_results) ? params[:tool_results] : params[:tool_result]
        return [] if raw_results.blank?

        raw_results = [raw_results] if !raw_results.is_a?(Array)

        if raw_results.size > MAX_STREAM_REPLY_TOOL_RESULTS
          raise ArgumentError,
                I18n.t(
                  "discourse_ai.errors.too_many_tool_results",
                  max: MAX_STREAM_REPLY_TOOL_RESULTS,
                )
        end

        raw_results.map do |tool_result|
          hash = normalize_hash_param(tool_result, key: :tool_results)
          id = hash["tool_call_id"].presence || hash["id"].presence
          if id.blank?
            raise ArgumentError,
                  I18n.t("discourse_ai.errors.invalid_tool_results", details: "tool_call_id")
          end

          if !hash.key?("content")
            raise ArgumentError,
                  I18n.t("discourse_ai.errors.invalid_tool_results", details: "content")
          end

          content = hash["content"]
          if content.nil?
            raise ArgumentError,
                  I18n.t("discourse_ai.errors.invalid_tool_results", details: "content")
          end
          content_bytesize = content.is_a?(String) ? content.bytesize : content.to_json.bytesize

          if content_bytesize > MAX_STREAM_REPLY_TOOL_RESULT_CONTENT_BYTES
            raise ArgumentError,
                  I18n.t(
                    "discourse_ai.errors.tool_result_content_too_large",
                    max: MAX_STREAM_REPLY_TOOL_RESULT_CONTENT_BYTES,
                  )
          end

          { "tool_call_id" => id.to_s, "content" => content }
        rescue JSON::GeneratorError
          raise ArgumentError,
                I18n.t("discourse_ai.errors.invalid_tool_results", details: "content")
        end
      end

      def normalize_hash_param(raw, key:)
        hash = raw
        hash = hash.to_unsafe_h if hash.is_a?(ActionController::Parameters)

        if !hash.is_a?(Hash)
          raise ArgumentError,
                I18n.t(
                  "discourse_ai.errors.invalid_stream_param",
                  key: key,
                  details: I18n.t("discourse_ai.errors.expected_object"),
                )
        end

        hash.stringify_keys
      end

      def find_ai_agent
        @ai_agent = AiAgent.find(params[:id])
      end

      def attached_upload_ids(agent)
        manual_upload_ids = ai_agent_params[:rag_uploads].to_a.map { |upload| upload[:id] }
        source_upload_ids = agent.rag_document_sources.where.not(upload_id: nil).pluck(:upload_id)

        manual_upload_ids.concat(source_upload_ids).uniq
      end

      def ensure_ai_agent_user(agent)
        agent.ensure_user! if agent.needs_user?
      end

      def ai_agent_params
        payload = ai_agent_payload
        permitted =
          payload.permit(
            :name,
            :description,
            :enabled,
            :system_prompt,
            :priority,
            :top_p,
            :temperature,
            :thinking_effort,
            :default_llm_id,
            :user_id,
            :vision_enabled,
            :vision_max_pixels,
            :rag_chunk_tokens,
            :rag_chunk_overlap_tokens,
            :rag_conversation_chunks,
            :rag_llm_model_id,
            :allow_chat_channel_mentions,
            :allow_chat_direct_messages,
            :allow_topic_mentions,
            :allow_personal_messages,
            :show_thinking,
            :forced_tool_count,
            :force_default_llm,
            :max_turn_tokens,
            :compression_threshold,
            :require_approval,
            allowed_group_ids: [],
            mcp_server_ids: [],
            rag_uploads: [:id],
            rag_document_sources_attributes: %i[id url refresh_interval_hours _destroy],
          )

        if payload[:mcp_server_ids].is_a?(Array)
          permitted[:ai_mcp_server_ids] = payload[:mcp_server_ids].filter_map(&:presence).map(
            &:to_i
          )
          permitted.delete(:mcp_server_ids)
        end

        if payload.key?(:subagent_ids)
          permitted[:subagent_ids] = normalize_subagent_ids(payload[:subagent_ids])
        end

        permitted[:mcp_server_tool_names] = normalize_mcp_server_tool_names(
          payload[:mcp_server_tool_names],
          permitted[:ai_mcp_server_ids],
        )

        if tools = payload[:tools]
          permitted[:tools] = permit_tools(tools)
        end

        if response_format = payload[:response_format]
          permitted[:response_format] = permit_response_format(response_format)
        end

        if examples = payload[:examples]
          permitted[:examples] = permit_examples(examples)
        end

        permitted
      end

      def ai_agent_payload
        payload = params[:ai_agent]
        raise ActionController::ParameterMissing.new(:ai_agent) if payload.blank?

        if payload.is_a?(ActionController::Parameters)
          payload
        else
          ActionController::Parameters.new(payload)
        end
      end

      def render_ai_agent_resource(agent, status: :ok)
        serialized = LocalizedAiAgentSerializer.new(agent, root: false)
        render json: { ai_agent: serialized }, status: status
      end

      def permit_tools(tools)
        return [] if !tools.is_a?(Array)

        tools.filter_map do |tool, options, force_tool|
          break nil if !tool.is_a?(String)
          options&.permit! if options && options.is_a?(ActionController::Parameters)

          # this is simpler from a storage perspective, 1 way to store tools
          [tool, options, !!force_tool]
        end
      end

      def permit_response_format(response_format)
        return [] if !response_format.is_a?(Array)

        response_format.map do |element|
          if element && element.is_a?(ActionController::Parameters)
            element.permit!
          else
            false
          end
        end
      end

      def permit_examples(examples)
        return [] if !examples.is_a?(Array)

        examples.map { |example_arr| example_arr.take(2).map(&:to_s) }
      end

      def normalize_subagent_ids(raw_ids)
        unless raw_ids.is_a?(Array)
          raise InvalidSubagentIds, I18n.t("discourse_ai.ai_bot.agents.invalid_subagent_ids")
        end

        raw_ids
          .map do |id|
            valid_id = id.is_a?(Integer) || id.is_a?(String) && id.match?(/\A-?\d+\z/)
            unless valid_id
              raise InvalidSubagentIds, I18n.t("discourse_ai.ai_bot.agents.invalid_subagent_ids")
            end

            id.is_a?(Integer) ? id : Integer(id, 10)
          end
          .uniq
      end

      def normalize_mcp_server_tool_names(raw_tool_names, allowed_server_ids)
        return {} if !raw_tool_names.respond_to?(:to_unsafe_h) && !raw_tool_names.is_a?(Hash)

        allowed_ids = Array(allowed_server_ids).map(&:to_i).to_set
        raw_hash =
          if raw_tool_names.respond_to?(:to_unsafe_h)
            raw_tool_names.to_unsafe_h
          else
            raw_tool_names
          end

        raw_hash.each_with_object({}) do |(server_id, tool_names), hash|
          normalized_server_id = server_id.to_i
          next if !allowed_ids.include?(normalized_server_id)
          next if !tool_names.is_a?(Array)

          normalized_tool_names = tool_names.filter_map { |name| name.to_s.presence }.uniq
          next if normalized_tool_names.blank?

          hash[normalized_server_id.to_s] = normalized_tool_names
        end
      end

      def sync_mcp_server_assignments(ai_agent, submitted_server_ids, mcp_server_tool_names)
        submitted_server_ids = Array(submitted_server_ids).map(&:to_i)
        preserved_disabled_server_ids =
          hidden_disabled_mcp_server_ids(ai_agent, submitted_server_ids)
        ai_agent.ai_mcp_server_ids = (submitted_server_ids + preserved_disabled_server_ids).uniq

        ai_agent.ai_agent_mcp_servers.each do |assignment|
          next if preserved_disabled_server_ids.include?(assignment.ai_mcp_server_id)

          assignment.update!(
            selected_tool_names: mcp_server_tool_names[assignment.ai_mcp_server_id.to_s],
          )
        end

        ai_agent.bump_cache
      end

      def hidden_disabled_mcp_server_ids(ai_agent, submitted_server_ids)
        ai_agent
          .ai_agent_mcp_servers
          .includes(:ai_mcp_server)
          .filter_map do |assignment|
            next if submitted_server_ids.include?(assignment.ai_mcp_server_id)
            next if assignment.ai_mcp_server&.enabled?

            assignment.ai_mcp_server_id
          end
      end

      def serialize_mcp_server(server)
        {
          id: server.id,
          name: server.name,
          tool_count: server.tool_count,
          token_count: server.token_count,
          last_health_status: server.last_health_status,
          last_checked_at: server.last_checked_at,
          tools: server.tools_for_serialization,
        }
      end

      def ai_agent_logger_fields
        {
          name: {
          },
          description: {
          },
          enabled: {
          },
          priority: {
          },
          system_prompt: {
            type: :large_text,
          },
          default_llm_id: {
          },
          temperature: {
          },
          top_p: {
          },
          user_id: {
          },
          vision_enabled: {
          },
          vision_max_pixels: {
          },
          rag_chunk_tokens: {
          },
          rag_chunk_overlap_tokens: {
          },
          rag_conversation_chunks: {
          },
          rag_llm_model_id: {
          },
          allow_chat_channel_mentions: {
          },
          allow_chat_direct_messages: {
          },
          allow_topic_mentions: {
          },
          allow_personal_messages: {
          },
          show_thinking: {
            type: :large_text,
          },
          forced_tool_count: {
          },
          force_default_llm: {
          },
          max_turn_tokens: {
          },
          compression_threshold: {
          },
          require_approval: {
          },
          subagent_ids: {
          },
          # JSON fields
          json_fields: %i[tools response_format examples allowed_group_ids ai_mcp_server_ids],
        }
      end

      def log_ai_agent_creation(ai_agent)
        logger = DiscourseAi::Utils::AiStaffActionLogger.new(current_user)
        entity_details = { agent_id: ai_agent.id, subject: ai_agent.name }
        entity_details[:tools_count] = (ai_agent.tools || []).size

        logger.log_creation("agent", ai_agent, ai_agent_logger_fields, entity_details)
      end

      def log_ai_agent_update(ai_agent, initial_attributes)
        logger = DiscourseAi::Utils::AiStaffActionLogger.new(current_user)
        entity_details = { agent_id: ai_agent.id, subject: ai_agent.name }
        entity_details[:tools_count] = ai_agent.tools.size if ai_agent.tools.present?

        logger.log_update(
          "agent",
          ai_agent,
          initial_attributes,
          ai_agent_logger_fields,
          entity_details,
        )
      end

      def log_ai_spam_model_update(settings)
        return if settings.blank? || settings.ai_agent_id != @ai_agent.id

        previous_model_id = settings.llm_model_id
        settings.reload
        return if settings.llm_model_id == previous_model_id

        previous_model_name =
          LlmModel.find_by(id: previous_model_id)&.display_name || previous_model_id
        logger = DiscourseAi::Utils::AiStaffActionLogger.new(current_user)
        logger.log_custom(
          "update_ai_spam_settings",
          subject: I18n.t("discourse_ai.spam_detection.logging_subject"),
          llm_model_id: "#{previous_model_name} → #{settings.llm_model.display_name}",
        )
      end

      def log_ai_agent_deletion(agent_details)
        logger = DiscourseAi::Utils::AiStaffActionLogger.new(current_user)
        agent_details[:subject] = agent_details[:name]

        logger.log_deletion("agent", agent_details)
      end
    end
  end
end