A platform for community discussion. Free, open, simple.
FEATURE: Add users tool for AI agents (#42302)
Natalie Tayce133db73057
diff --git a/plugins/discourse-ai/app/models/ai_agent.rb b/plugins/discourse-ai/app/models/ai_agent.rbindex 93c04eb5b7d..ec687059f3f 100644--- a/plugins/discourse-ai/app/models/ai_agent.rb+++ b/plugins/discourse-ai/app/models/ai_agent.rb@@ -299,7 +299,7 @@ class AiAgent < ActiveRecord::Baseendelseinner_name = inner_name.gsub("Tool", "")- inner_name = "List#{inner_name}" if %w[Categories Tags].include?(inner_name)+ inner_name = "List#{inner_name}" if %w[Categories Tags Users].include?(inner_name)klass ="DiscourseAi::Agents::Tools::#{inner_name}".safe_constantize ||diff --git a/plugins/discourse-ai/config/locales/server.en.yml b/plugins/discourse-ai/config/locales/server.en.ymlindex c6fbc0d58d2..270538ac195 100644--- a/plugins/discourse-ai/config/locales/server.en.yml+++ b/plugins/discourse-ai/config/locales/server.en.yml@@ -642,6 +642,7 @@ en:github_diff: "GitHub diff"random_picker: "Random Picker"categories: "List categories"+ users: "List users"flag_post: "Flag post"close_topic: "Close topic"suspend_user: "Suspend user"@@ -693,6 +694,7 @@ en:github_diff: "Retrieve a GitHub pull request or commit diff"random_picker: "Pick a random number or a random element of a list"categories: "List all publicly visible categories on the forum"+ users: "List users on the forum"flag_post: "Flag the current post for staff review"close_topic: "Close or open a topic"suspend_user: "Suspend (ban) a user, blocking them from logging in or posting"@@ -774,6 +776,9 @@ en:categories:one: "Found %{count} category"other: "Found %{count} categories"+ users:+ one: "Found %{count} user"+ other: "Found %{count} users"tags:one: "Found %{count} tag"other: "Found %{count} tags"diff --git a/plugins/discourse-ai/lib/agents/agent.rb b/plugins/discourse-ai/lib/agents/agent.rbindex 9e35c63d752..bde681d449b 100644--- a/plugins/discourse-ai/lib/agents/agent.rb+++ b/plugins/discourse-ai/lib/agents/agent.rb@@ -89,6 +89,7 @@ module DiscourseAidef all_available_toolstools = [Tools::ListCategories,+ Tools::ListUsers,Tools::Time,Tools::Search,Tools::Read,diff --git a/plugins/discourse-ai/lib/agents/tools/list_users.rb b/plugins/discourse-ai/lib/agents/tools/list_users.rbnew file mode 100644index 00000000000..e3c907fc0f2--- /dev/null+++ b/plugins/discourse-ai/lib/agents/tools/list_users.rb@@ -0,0 +1,89 @@+# frozen_string_literal: true++module DiscourseAi+ module Agents+ module Tools+ class ListUsers < Tool+ def self.signature+ {+ name: name,+ description:+ "Lists users on the current Discourse instance, optionally filtered by search term, groups, account status, and topic creation permission in a category.",+ parameters: [+ {+ name: "query",+ description: "Optional username or name search term.",+ type: "string",+ required: false,+ },+ {+ name: "groups",+ description:+ "Optional group names or IDs. When present, only users in at least one of these groups are returned.",+ type: "array",+ item_type: "string",+ required: false,+ },+ {+ name: "category_name",+ description:+ "Optional category name or slug. When present, only users who can create topics in that category are returned.",+ type: "string",+ required: false,+ },+ {+ name: "real",+ description:+ "Optional boolean. When true, only regular human users are returned; when false, only non-regular human user records such as anonymous shadow users are returned.",+ type: "boolean",+ required: false,+ },+ {+ name: "active",+ description: "Optional boolean filter for active or inactive users.",+ type: "boolean",+ required: false,+ },+ {+ name: "staged",+ description: "Optional boolean filter for staged or non-staged users.",+ type: "boolean",+ required: false,+ },+ {+ name: "suspended",+ description: "Optional boolean filter for suspended or non-suspended users.",+ type: "boolean",+ required: false,+ },+ {+ name: "limit",+ description: "Maximum number of users to return, capped at 100.",+ type: "integer",+ required: false,+ },+ ],+ }+ end++ def self.name+ "users"+ end++ def invoke+ result = DiscourseAi::Agents::UserFinder.new(parameters, guardian: guardian).call+ return error_response(result[:error]) if result[:error]++ @last_count = result[:users].length+ format_results(result[:users])+ end++ private++ def description_args+ { count: @last_count || 0 }+ end+ end+ end+ end+enddiff --git a/plugins/discourse-ai/lib/agents/user_finder.rb b/plugins/discourse-ai/lib/agents/user_finder.rbnew file mode 100644index 00000000000..cf3621fd9df--- /dev/null+++ b/plugins/discourse-ai/lib/agents/user_finder.rb@@ -0,0 +1,175 @@+# frozen_string_literal: true++module DiscourseAi+ module Agents+ class UserFinder+ DEFAULT_LIMIT = 50+ MAX_LIMIT = 100+ MAX_CATEGORY_PERMISSION_CANDIDATES = 500++ def initialize(params, guardian: Guardian.new)+ @params = params.is_a?(Hash) ? params.with_indifferent_access : {}+ @guardian = guardian+ end++ def call+ limit = parsed_limit+ return limit if limit[:error]++ groups = requested_groups+ return groups if groups[:error]++ category = requested_category+ return category if category[:error]++ users = User.human_users+ users = filter_by_status(users)+ users = filter_by_query(users)+ users = filter_by_groups(users, groups[:groups])+ users =+ users.order(:username_lower).limit(candidate_limit(limit[:limit], category[:category]))+ users = filter_by_category_permission(users, category[:category], limit[:limit])++ users = users.to_a+ real_user_ids = User.real.where(id: users.map(&:id)).pluck(:id).to_set++ { users: users.map { |user| serialize_user(user, real: real_user_ids.include?(user.id)) } }+ end++ private++ def parsed_limit+ limit = @params.fetch(:limit, DEFAULT_LIMIT).to_i+ return { error: "limit must be greater than 0" } if limit <= 0++ { limit: [limit, MAX_LIMIT].min }+ end++ def requested_groups+ group_identifiers = Array(@params[:groups]).flat_map { |group| group.to_s.split(",") }+ group_identifiers.map!(&:strip)+ group_identifiers.reject!(&:blank?)++ groups =+ group_identifiers.map do |identifier|+ if identifier.match?(/\A\d+\z/)+ Group.find_by(id: identifier.to_i)+ else+ Group.find_by(name: identifier) ||+ (Group[identifier.to_sym] if Group::AUTO_GROUPS.key?(identifier.to_sym))+ end+ end++ missing_groups =+ group_identifiers.zip(groups).filter_map { |identifier, group| identifier if group.nil? }++ return { error: "Group not found: #{missing_groups.join(", ")}" } if missing_groups.any?++ { groups: groups }+ end++ def requested_category+ category_id = @params[:category_id]+ category_name = @params[:category_name]+ return { category: nil } if category_id.blank? && category_name.blank?++ category = find_category(category_id.presence || category_name)+ return { error: "Category not found" } if category.nil?+ return { error: "Category not found" } if [email protected]_see_category?(category)++ { category: category }+ end++ def find_category(category_id_or_name)+ if category_id_or_name.is_a?(Integer) ||+ category_id_or_name.to_i.to_s == category_id_or_name.to_s+ Category.find_by(id: category_id_or_name.to_i)+ else+ Category+ .where(name: category_id_or_name)+ .or(Category.where(slug: category_id_or_name))+ .first+ end+ end++ def filter_by_query(users)+ query = @params[:query].to_s.strip+ return users if query.blank?++ query_like = "%#{ActiveRecord::Base.sanitize_sql_like(query.downcase)}%"+ users.where(+ "users.username_lower LIKE :query OR users.name ILIKE :query",+ query: query_like,+ )+ end++ def filter_by_status(users)+ if @params.key?(:active)+ users = users.where(active: ActiveModel::Type::Boolean.new.cast(@params[:active]))+ end++ if @params.key?(:staged)+ users = users.where(staged: ActiveModel::Type::Boolean.new.cast(@params[:staged]))+ end++ if @params.key?(:suspended)+ suspended = ActiveModel::Type::Boolean.new.cast(@params[:suspended])+ users = suspended ? users.suspended : users.not_suspended+ end++ if @params.key?(:real)+ users =+ if ActiveModel::Type::Boolean.new.cast(@params[:real])+ users.where(+ "NOT EXISTS(+ SELECT 1+ FROM anonymous_users a+ WHERE a.user_id = users.id+ )",+ )+ else+ users.where(+ "EXISTS(+ SELECT 1+ FROM anonymous_users a+ WHERE a.user_id = users.id+ )",+ )+ end+ end++ users+ end++ def filter_by_groups(users, groups)+ return users if groups.blank?++ users.joins(:group_users).where(group_users: { group_id: groups.map(&:id) }).distinct+ end++ def candidate_limit(limit, category)+ return limit if category.nil?++ [limit * 10, MAX_CATEGORY_PERMISSION_CANDIDATES].min+ end++ def filter_by_category_permission(users, category, limit)+ return users if category.nil?++ users.select { |user| Guardian.new(user).can_create?(Topic, category) }.first(limit)+ end++ def serialize_user(user, real:)+ {+ id: user.id,+ username: user.username,+ name: user.name,+ active: user.active,+ staged: user.staged,+ suspended: user.suspended?,+ real: real,+ }+ end+ end+ end+enddiff --git a/plugins/discourse-ai/spec/lib/agents/tools/list_users_spec.rb b/plugins/discourse-ai/spec/lib/agents/tools/list_users_spec.rbnew file mode 100644index 00000000000..45371ab3d68--- /dev/null+++ b/plugins/discourse-ai/spec/lib/agents/tools/list_users_spec.rb@@ -0,0 +1,125 @@+# frozen_string_literal: true++RSpec.describe DiscourseAi::Agents::Tools::ListUsers do+ fab!(:llm_model)+ let(:bot_user) { DiscourseAi::AiBot::EntryPoint.find_user_from_model(llm_model.name) }+ let(:llm) { DiscourseAi::Completions::Llm.proxy(llm_model) }++ before do+ enable_current_plugin+ SiteSetting.ai_bot_enabled = true+ end++ def column_value(row, result, column_name)+ row[result[:column_names].index(column_name)]+ end++ def usernames_from(result)+ username_column = result[:column_names].index("username")+ result[:rows].map { |row| row[username_column] }+ end++ def row_for(result, username)+ result[:rows].find { |row| column_value(row, result, "username") == username }+ end++ describe "#invoke" do+ it "lists users with safe account status fields" do+ eligible_user = Fabricate(:user, username: "seedable_alice")+ inactive_user = Fabricate(:inactive_user, username: "seedable_inactive")+ staged_user = Fabricate(:staged, username: "seedable_staged", active: true)+ suspended_user =+ Fabricate(:user, username: "seedable_suspended", suspended_till: 1.week.from_now)++ result =+ described_class.new({ query: "seedable", limit: 100 }, bot_user: bot_user, llm: llm).invoke+ usernames = usernames_from(result)++ expect(result[:column_names]).to contain_exactly(+ "id",+ "username",+ "name",+ "active",+ "staged",+ "suspended",+ "real",+ )+ expect(usernames).to include(+ eligible_user.username,+ inactive_user.username,+ staged_user.username,+ suspended_user.username,+ )+ expect(column_value(row_for(result, inactive_user.username), result, "active")).to eq(false)+ expect(column_value(row_for(result, staged_user.username), result, "staged")).to eq(true)+ expect(column_value(row_for(result, suspended_user.username), result, "suspended")).to eq(+ true,+ )+ end++ it "filters users by account status when requested" do+ eligible_user = Fabricate(:user, username: "filter_alice")+ inactive_user = Fabricate(:inactive_user, username: "filter_inactive")+ staged_user = Fabricate(:staged, username: "filter_staged", active: true)+ suspended_user =+ Fabricate(:user, username: "filter_suspended", suspended_till: 1.week.from_now)++ result =+ described_class.new(+ {+ query: "filter",+ real: true,+ active: true,+ staged: false,+ suspended: false,+ limit: 100,+ },+ bot_user: bot_user,+ llm: llm,+ ).invoke+ usernames = usernames_from(result)++ expect(usernames).to include(eligible_user.username)+ expect(usernames).not_to include(+ inactive_user.username,+ staged_user.username,+ suspended_user.username,+ )+ end++ it "filters users by group membership" do+ group = Fabricate(:group, name: "seeders")+ included_user = Fabricate(:user, username: "group_seed_in")+ excluded_user = Fabricate(:user, username: "group_seed_out")+ group.add(included_user)++ result =+ described_class.new(+ { query: "group_seed", groups: ["seeders"], limit: 20 },+ bot_user: bot_user,+ llm: llm,+ ).invoke++ expect(usernames_from(result)).to contain_exactly(included_user.username)+ expect(usernames_from(result)).not_to include(excluded_user.username)+ end++ it "filters users by topic creation permission in a category" do+ SiteSetting.create_topic_allowed_groups = Group::AUTO_GROUPS[:admins]++ category = Fabricate(:category)+ allowed_user = Fabricate(:admin, username: "cat_seed_admin")+ blocked_user = Fabricate(:user, username: "cat_seed_blocked")++ result =+ described_class.new(+ { query: "cat_seed", category_name: category.slug, limit: 20 },+ bot_user: bot_user,+ llm: llm,+ ).invoke++ expect(usernames_from(result)).to contain_exactly(allowed_user.username)+ expect(usernames_from(result)).not_to include(blocked_user.username)+ end+ end+enddiff --git a/plugins/discourse-ai/spec/models/ai_agent_spec.rb b/plugins/discourse-ai/spec/models/ai_agent_spec.rbindex b6cf9be275a..b4e9b11abbe 100644--- a/plugins/discourse-ai/spec/models/ai_agent_spec.rb+++ b/plugins/discourse-ai/spec/models/ai_agent_spec.rb@@ -240,6 +240,21 @@ RSpec.describe AiAgent doexpect(klass.allow_chat_direct_messages).to eq(true)end+ it "resolves the users tool shorthand" do+ agent =+ AiAgent.create!(+ name: "users_tool_agent",+ description: "test",+ system_prompt: "test",+ tools: ["Users"],+ allowed_group_ids: [],+ default_llm_id: llm_model.id,+ user_id: 1,+ )++ expect(agent.class_instance.new.tools).to contain_exactly(DiscourseAi::Agents::Tools::ListUsers)+ end+it "attaches mcp tool classes for assigned servers" doai_mcp_server = Fabricate(:ai_mcp_server, name: "Jira")agent =