Skip to content

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.rb
index 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::Base
end
else
inner_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.yml
index 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.rb
index 9e35c63d752..bde681d449b 100644
--- a/plugins/discourse-ai/lib/agents/agent.rb
+++ b/plugins/discourse-ai/lib/agents/agent.rb
@@ -89,6 +89,7 @@ module DiscourseAi
def all_available_tools
tools = [
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.rb
new file mode 100644
index 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
+end
diff --git a/plugins/discourse-ai/lib/agents/user_finder.rb b/plugins/discourse-ai/lib/agents/user_finder.rb
new file mode 100644
index 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
+end
diff --git a/plugins/discourse-ai/spec/lib/agents/tools/list_users_spec.rb b/plugins/discourse-ai/spec/lib/agents/tools/list_users_spec.rb
new file mode 100644
index 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
+end
diff --git a/plugins/discourse-ai/spec/models/ai_agent_spec.rb b/plugins/discourse-ai/spec/models/ai_agent_spec.rb
index 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 do
expect(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" do
ai_mcp_server = Fabricate(:ai_mcp_server, name: "Jira")
agent =