Skip to content

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

FEATURE: Add review queue tools for AI agents (#38928)

Rafael dos Santos Silva93ed2ad08e18
diff --git a/plugins/discourse-ai/config/locales/server.en.yml b/plugins/discourse-ai/config/locales/server.en.yml
index 9ab25d752e3..e3f3a27b471 100644
--- a/plugins/discourse-ai/config/locales/server.en.yml
+++ b/plugins/discourse-ai/config/locales/server.en.yml
@@ -566,6 +566,8 @@ en:
set_slow_mode: "Set slow mode"
move_posts: "Move posts"
grant_badge: "Grant badge"
+ list_reviewables: "List review queue"
+ perform_reviewable_action: "Review queue action"
assign: "Assign topic"
mark_as_solved: "Mark as solved"
search: "Search"
@@ -609,6 +611,8 @@ en:
set_slow_mode: "Enable or disable slow mode on a topic"
move_posts: "Move posts to a new or existing topic"
grant_badge: "Grant a badge to a user"
+ list_reviewables: "List pending review queue items with optional filtering"
+ perform_reviewable_action: "Perform an action on a review queue item"
assign: "Assign or unassign a topic to a user or group"
mark_as_solved: "Mark or unmark a post as the accepted solution"
search: "Search all public topics on the forum"
@@ -652,6 +656,8 @@ en:
set_slow_mode: "Setting slow mode on topic %{topic_id} (%{slow_mode_seconds}s)"
move_posts: "Moving posts %{post_ids} from topic %{topic_id}"
grant_badge: "Granting badge '%{badge_name}' to %{username}"
+ list_reviewables: "Listing review queue items (type: %{type})"
+ perform_reviewable_action: "Performing %{action} on reviewable %{reviewable_id}"
assign: "Assigning topic %{topic_id} (assigned: %{assigned})"
mark_as_solved: "Marking post %{post_id} as solved (solved: %{solved})"
read: "Reading: <a href='%{url}'>%{title}</a>"
@@ -808,6 +814,26 @@ en:
action_failed: "Failed to update the solved status."
success: "Solved status updated successfully."
+ list_reviewables:
+ errors:
+ not_allowed: "You are not allowed to view the review queue"
+ invalid_type: "Invalid reviewable type"
+ invalid_status: "Invalid status. Must be one of: pending, approved, rejected, ignored, deleted, reviewed, all."
+ empty: "No review queue items found matching the given filters"
+ found:
+ one: "Found %{count} review queue item"
+ other: "Found %{count} review queue items"
+
+ perform_reviewable_action:
+ errors:
+ not_allowed: "You are not allowed to access the review queue"
+ not_found: "Review queue item not found"
+ no_reason: "A reason is required to perform an action on a review queue item"
+ invalid_action: "Invalid action '%{action}'. Available actions: %{available}"
+ conflict: "This review queue item was updated by someone else. Please try again"
+ action_failed: "Failed to perform the action"
+ success: "Successfully performed '%{action}' on review queue item %{reviewable_id}"
+
reviewables:
ai_tool_action:
title: "AI Tool Action"
diff --git a/plugins/discourse-ai/lib/agents/agent.rb b/plugins/discourse-ai/lib/agents/agent.rb
index 3ebabe70ba9..aea6de12d2d 100644
--- a/plugins/discourse-ai/lib/agents/agent.rb
+++ b/plugins/discourse-ai/lib/agents/agent.rb
@@ -133,6 +133,8 @@ module DiscourseAi
Tools::SetSlowMode,
Tools::MovePosts,
Tools::GrantBadge,
+ Tools::ListReviewables,
+ Tools::PerformReviewableAction,
Tools::DbSchema,
Tools::SearchSettings,
Tools::SettingContext,
diff --git a/plugins/discourse-ai/lib/agents/tools/list_reviewables.rb b/plugins/discourse-ai/lib/agents/tools/list_reviewables.rb
new file mode 100644
index 00000000000..46abe2412b2
--- /dev/null
+++ b/plugins/discourse-ai/lib/agents/tools/list_reviewables.rb
@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module DiscourseAi
+ module Agents
+ module Tools
+ class ListReviewables < Tool
+ MAX_RESULTS = 20
+
+ def self.signature
+ {
+ name: name,
+ description:
+ "Lists pending review queue items. Can filter by reviewable type and age. Returns a summary of each item including its ID, type, score, creation date, target details, and available actions.",
+ parameters: [
+ {
+ name: "type",
+ description:
+ "Filter by reviewable type: ReviewableFlaggedPost, ReviewableQueuedPost, ReviewableUser, ReviewablePost. Leave blank for all types.",
+ type: "string",
+ },
+ {
+ name: "min_hours_old",
+ description:
+ "Only return items that have been in the queue for at least this many hours",
+ type: "integer",
+ },
+ {
+ name: "max_hours_old",
+ description:
+ "Only return items that have been in the queue for at most this many hours",
+ type: "integer",
+ },
+ { name: "category_id", description: "Filter by category ID", type: "integer" },
+ {
+ name: "status",
+ description:
+ "Filter by status: pending (default), approved, rejected, ignored, deleted",
+ type: "string",
+ },
+ ],
+ }
+ end
+
+ def self.name
+ "list_reviewables"
+ end
+
+ def self.requires_approval?
+ false
+ end
+
+ def invoke
+ if !guardian.can_see_review_queue?
+ return(
+ error_response(I18n.t("discourse_ai.ai_bot.list_reviewables.errors.not_allowed"))
+ )
+ end
+
+ status = (parameters[:status] || "pending").to_sym
+ allowed_statuses = Reviewable.statuses.symbolize_keys.keys + %i[reviewed all]
+ if !allowed_statuses.include?(status)
+ return(
+ error_response(I18n.t("discourse_ai.ai_bot.list_reviewables.errors.invalid_status"))
+ )
+ end
+
+ filters = { status: status, limit: MAX_RESULTS }
+
+ if parameters[:type].present?
+ unless Reviewable.valid_type?(parameters[:type])
+ return(
+ error_response(I18n.t("discourse_ai.ai_bot.list_reviewables.errors.invalid_type"))
+ )
+ end
+ filters[:type] = parameters[:type]
+ end
+
+ filters[:category_id] = parameters[:category_id] if parameters[:category_id].present?
+
+ if parameters[:min_hours_old].present?
+ filters[:to_date] = parameters[:min_hours_old].to_i.hours.ago
+ end
+
+ if parameters[:max_hours_old].present?
+ filters[:from_date] = parameters[:max_hours_old].to_i.hours.ago
+ end
+
+ reviewables = Reviewable.list_for(guardian.user, **filters).to_a
+
+ if reviewables.empty?
+ return(
+ {
+ status: "success",
+ message: I18n.t("discourse_ai.ai_bot.list_reviewables.empty"),
+ reviewables: [],
+ }
+ )
+ end
+
+ rows = reviewables.map { |r| serialize_reviewable(r) }
+
+ {
+ status: "success",
+ message: I18n.t("discourse_ai.ai_bot.list_reviewables.found", count: rows.size),
+ reviewables: rows,
+ }
+ end
+
+ def description_args
+ { type: parameters[:type] || "all", count: 0 }
+ end
+
+ private
+
+ def serialize_reviewable(reviewable)
+ result = {
+ id: reviewable.id,
+ type: reviewable.type,
+ status: reviewable.status,
+ score: reviewable.score.to_f.round(1),
+ created_at: reviewable.created_at.iso8601,
+ hours_old: ((::Time.zone.now - reviewable.created_at) / 1.hour).round(1),
+ category_id: reviewable.category_id,
+ topic_id: reviewable.topic_id,
+ }
+
+ if reviewable.target_created_by
+ result[:target_created_by] = reviewable.target_created_by.username
+ end
+
+ result[:created_by] = reviewable.created_by.username if reviewable.created_by
+
+ result[:available_actions] = available_action_ids(reviewable)
+
+ case reviewable
+ when ReviewableFlaggedPost
+ serialize_flagged_post(result, reviewable)
+ when ReviewableQueuedPost
+ serialize_queued_post(result, reviewable)
+ when ReviewableUser
+ serialize_user(result, reviewable)
+ when ReviewablePost
+ serialize_post(result, reviewable)
+ end
+
+ result[:scores] = reviewable.reviewable_scores.map do |score|
+ {
+ reason: score.reason,
+ score: score.score.to_f.round(1),
+ status: score.status,
+ user: score.user&.username,
+ }
+ end
+
+ result
+ end
+
+ def available_action_ids(reviewable)
+ actions = reviewable.actions_for(guardian)
+ actions.bundles.flat_map { |bundle| bundle.actions.map { |a| a.server_action } }
+ end
+
+ def serialize_flagged_post(result, reviewable)
+ post = reviewable.post
+ return unless post
+
+ result[:post_id] = post.id
+ result[:post_number] = post.post_number
+ result[:post_excerpt] = post.excerpt(300, strip_links: true, text_entities: true)
+ result[:topic_title] = post.topic&.title
+ end
+
+ def serialize_queued_post(result, reviewable)
+ payload = reviewable.payload || {}
+ result[:queued_title] = payload["title"]
+ result[:queued_raw_excerpt] = payload["raw"].to_s.truncate(300)
+ result[:queued_tags] = payload["tags"]
+ end
+
+ def serialize_user(result, reviewable)
+ target = reviewable.target
+ return unless target
+
+ result[:username] = target.username
+ result[:user_id] = target.id
+ end
+
+ def serialize_post(result, reviewable)
+ post = reviewable.target
+ return unless post.is_a?(Post)
+
+ result[:post_id] = post.id
+ result[:post_number] = post.post_number
+ result[:post_excerpt] = post.excerpt(300, strip_links: true, text_entities: true)
+ result[:topic_title] = post.topic&.title
+ end
+ end
+ end
+ end
+end
diff --git a/plugins/discourse-ai/lib/agents/tools/perform_reviewable_action.rb b/plugins/discourse-ai/lib/agents/tools/perform_reviewable_action.rb
new file mode 100644
index 00000000000..10fac26cbee
--- /dev/null
+++ b/plugins/discourse-ai/lib/agents/tools/perform_reviewable_action.rb
@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module DiscourseAi
+ module Agents
+ module Tools
+ class PerformReviewableAction < Tool
+ def self.signature
+ {
+ name: name,
+ description:
+ "Performs an action on a review queue item. Use list_reviewables first to discover available actions for each item. Common actions include: agree_and_keep, agree_and_hide, disagree, ignore_and_do_nothing, delete_and_agree, approve_post, reject_post, approve_user, delete_user.",
+ parameters: [
+ {
+ name: "reviewable_id",
+ description: "The ID of the reviewable item to act on",
+ type: "integer",
+ required: true,
+ },
+ {
+ name: "action_id",
+ description:
+ "The action to perform (e.g. agree_and_keep, agree_and_hide, disagree, ignore_and_do_nothing, delete_and_agree, approve_post, reject_post, approve_user, delete_user)",
+ type: "string",
+ required: true,
+ },
+ {
+ name: "reason",
+ description: "Short explanation of why this action is being taken",
+ type: "string",
+ required: true,
+ },
+ ],
+ }
+ end
+
+ def self.name
+ "perform_reviewable_action"
+ end
+
+ def self.requires_approval?
+ false
+ end
+
+ def invoke
+ if !guardian.can_see_review_queue?
+ return(
+ error_response(
+ I18n.t("discourse_ai.ai_bot.perform_reviewable_action.errors.not_allowed"),
+ )
+ )
+ end
+
+ if reason.blank?
+ return(
+ error_response(
+ I18n.t("discourse_ai.ai_bot.perform_reviewable_action.errors.no_reason"),
+ )
+ )
+ end
+
+ reviewable = Reviewable.viewable_by(guardian.user).find_by(id: parameters[:reviewable_id])
+ if !reviewable
+ return(
+ error_response(
+ I18n.t("discourse_ai.ai_bot.perform_reviewable_action.errors.not_found"),
+ )
+ )
+ end
+
+ action_id = parameters[:action_id].to_s.to_sym
+ available_actions = reviewable.actions_for(guardian)
+ valid_action_ids =
+ available_actions.bundles.flat_map do |bundle|
+ bundle.actions.map { |a| a.server_action.to_sym }
+ end
+
+ if !valid_action_ids.include?(action_id)
+ return(
+ error_response(
+ I18n.t(
+ "discourse_ai.ai_bot.perform_reviewable_action.errors.invalid_action",
+ action: action_id,
+ available: valid_action_ids.join(", "),
+ ),
+ )
+ )
+ end
+
+ reviewable.reviewable_notes.create!(user: acting_user, content: reason)
+
+ begin
+ result =
+ reviewable.perform(
+ acting_user,
+ action_id,
+ version: reviewable.version,
+ guardian: guardian,
+ )
+ rescue Reviewable::InvalidAction
+ return(
+ error_response(
+ I18n.t(
+ "discourse_ai.ai_bot.perform_reviewable_action.errors.invalid_action",
+ action: action_id,
+ available: valid_action_ids.join(", "),
+ ),
+ )
+ )
+ rescue Reviewable::UpdateConflict
+ return(
+ error_response(
+ I18n.t("discourse_ai.ai_bot.perform_reviewable_action.errors.conflict"),
+ )
+ )
+ end
+
+ if result.success?
+ {
+ status: "success",
+ message:
+ I18n.t(
+ "discourse_ai.ai_bot.perform_reviewable_action.success",
+ action: action_id,
+ reviewable_id: reviewable.id,
+ ),
+ }
+ else
+ error_response(
+ result.errors&.full_messages&.join(", ").presence ||
+ I18n.t("discourse_ai.ai_bot.perform_reviewable_action.errors.action_failed"),
+ )
+ end
+ end
+
+ def description_args
+ { reviewable_id: parameters[:reviewable_id], action: parameters[:action_id] }
+ end
+ end
+ end
+ end
+end
diff --git a/plugins/discourse-ai/spec/lib/agents/tools/list_reviewables_spec.rb b/plugins/discourse-ai/spec/lib/agents/tools/list_reviewables_spec.rb
new file mode 100644
index 00000000000..8008a37983f
--- /dev/null
+++ b/plugins/discourse-ai/spec/lib/agents/tools/list_reviewables_spec.rb
@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+RSpec.describe DiscourseAi::Agents::Tools::ListReviewables 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) }
+ fab!(:admin)
+
+ before do
+ enable_current_plugin
+ SiteSetting.ai_bot_enabled = true
+ end
+
+ def tool(params = nil, user: admin, **kwargs)
+ params ||= kwargs
+ ctx = DiscourseAi::Agents::BotContext.new(user: user)
+ described_class.new(params, bot_user: bot_user, llm: llm, context: ctx)
+ end
+
+ it "returns an error when user cannot see review queue" do
+ regular_user = Fabricate(:user, trust_level: TrustLevel[0])
+ result = tool({}, user: regular_user).invoke
+
+ expect(result[:status]).to eq("error")
+ expect(result[:error]).to include("not allowed")
+ end
+
+ it "returns empty result when no reviewables exist" do
+ result = tool({}).invoke
+
+ expect(result[:status]).to eq("success")
+ expect(result[:reviewables]).to eq([])
+ end
+
+ context "with pending reviewables" do
+ fab!(:post)
+ fab!(:flagged_reviewable) do
+ ReviewableFlaggedPost.needs_review!(
+ target: post,
+ created_by: Discourse.system_user,
+ reviewable_by_moderator: true,
+ )
+ end
+
+ it "lists pending reviewables" do
+ result = tool({}).invoke
+
+ expect(result[:status]).to eq("success")
+ expect(result[:reviewables].size).to eq(1)
+
+ item = result[:reviewables].first
+ expect(item[:id]).to eq(flagged_reviewable.id)
+ expect(item[:type]).to eq("ReviewableFlaggedPost")
+ expect(item[:status]).to eq("pending")
+ expect(item[:post_id]).to eq(post.id)
+ end
+
+ it "filters by type" do
+ result = tool(type: "ReviewableUser").invoke
+
+ expect(result[:status]).to eq("success")
+ expect(result[:reviewables]).to be_empty
+ end
+
+ it "returns error for invalid type" do
+ result = tool(type: "InvalidType").invoke
+
+ expect(result[:status]).to eq("error")
+ expect(result[:error]).to include("Invalid")
+ end
+
+ it "returns error for invalid status" do
+ result = tool(status: "bogus").invoke
+
+ expect(result[:status]).to eq("error")
+ expect(result[:error]).to include("Invalid status")
+ end
+
+ it "filters by min_hours_old" do
+ flagged_reviewable.update!(created_at: 5.hours.ago)
+
+ result = tool(min_hours_old: 3).invoke
+ expect(result[:reviewables].size).to eq(1)
+
+ result = tool(min_hours_old: 10).invoke
+ expect(result[:reviewables]).to be_empty
+ end
+
+ it "filters by max_hours_old" do
+ flagged_reviewable.update!(created_at: 5.hours.ago)
+
+ result = tool(max_hours_old: 10).invoke
+ expect(result[:reviewables].size).to eq(1)
+
+ result = tool(max_hours_old: 3).invoke
+ expect(result[:reviewables]).to be_empty
+ end
+
+ it "includes available actions" do
+ result = tool({}).invoke
+
+ item = result[:reviewables].first
+ expect(item[:available_actions]).to be_present
+ expect(item[:available_actions]).to include("agree_and_hide")
+ end
+
+ it "includes score details" do
+ flagged_reviewable.add_score(
+ Discourse.system_user,
+ ReviewableScore.types[:needs_approval],
+ reason: "test reason",
+ force_review: true,
+ )
+
+ result = tool({}).invoke
+
+ item = result[:reviewables].first
+ expect(item[:scores]).to be_present
+ expect(item[:scores].first[:user]).to eq("system")
+ end
+ end
+end
diff --git a/plugins/discourse-ai/spec/lib/agents/tools/perform_reviewable_action_spec.rb b/plugins/discourse-ai/spec/lib/agents/tools/perform_reviewable_action_spec.rb
new file mode 100644
index 00000000000..1727fea3e28
--- /dev/null
+++ b/plugins/discourse-ai/spec/lib/agents/tools/perform_reviewable_action_spec.rb
@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+RSpec.describe DiscourseAi::Agents::Tools::PerformReviewableAction 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) }
+ fab!(:admin)
+
+ before do
+ enable_current_plugin
+ SiteSetting.ai_bot_enabled = true
+ end
+
+ def tool(params = nil, user: admin, **kwargs)
+ params ||= kwargs
+ ctx = DiscourseAi::Agents::BotContext.new(user: user)
+ described_class.new(params, bot_user: bot_user, llm: llm, context: ctx)
+ end
+
+ it "returns an error when user cannot see review queue" do
+ regular_user = Fabricate(:user, trust_level: TrustLevel[0])
+ result =
+ tool(
+ { reviewable_id: 1, action_id: "agree_and_keep", reason: "test" },
+ user: regular_user,
+ ).invoke
+
+ expect(result[:status]).to eq("error")
+ expect(result[:error]).to include("not allowed")
+ end
+
+ it "returns an error when reason is blank" do
+ result = tool(reviewable_id: 1, action_id: "agree_and_keep", reason: " ").invoke
+
+ expect(result[:status]).to eq("error")
+ expect(result[:error]).to include("reason")
+ end
+
+ it "returns an error when reviewable is not found" do
+ result = tool(reviewable_id: -1, action_id: "agree_and_keep", reason: "test").invoke
+
+ expect(result[:status]).to eq("error")
+ expect(result[:error]).to include("not found")
+ end
+
+ context "with a flagged post" do
+ fab!(:post)
+ fab!(:flagged_reviewable) do
+ ReviewableFlaggedPost.needs_review!(
+ target: post,
+ created_by: Discourse.system_user,
+ reviewable_by_moderator: true,
+ )
+ end
+
+ it "returns an error for invalid action" do
+ result =
+ tool(
+ reviewable_id: flagged_reviewable.id,
+ action_id: "nonexistent_action",
+ reason: "test",
+ ).invoke
+
+ expect(result[:status]).to eq("error")
+ expect(result[:error]).to include("Invalid action")
+ end
+
+ it "successfully performs agree_and_keep" do
+ result =
+ tool(
+ reviewable_id: flagged_reviewable.id,
+ action_id: "agree_and_keep",
+ reason: "Confirmed violation",
+ ).invoke
+
+ expect(result[:status]).to eq("success")
+ expect(flagged_reviewable.reload.status).to eq("approved")
+ end
+
+ it "persists the reason as a reviewable note" do
+ tool(
+ reviewable_id: flagged_reviewable.id,
+ action_id: "agree_and_keep",
+ reason: "AI determined this violates policy",
+ ).invoke
+
+ note = flagged_reviewable.reviewable_notes.last
+ expect(note).to be_present
+ expect(note.content).to eq("AI determined this violates policy")
+ end
+
+ it "successfully performs agree_and_hide" do
+ PostActionCreator.inappropriate(Fabricate(:user, refresh_auto_groups: true), post)
+
+ result =
+ tool(
+ reviewable_id: flagged_reviewable.id,
+ action_id: "agree_and_hide",
+ reason: "Hiding inappropriate content",
+ ).invoke
+
+ expect(result[:status]).to eq("success")
+ expect(flagged_reviewable.reload.status).to eq("approved")
+ expect(post.reload.hidden).to eq(true)
+ end
+
+ it "successfully performs disagree" do
+ result =
+ tool(
+ reviewable_id: flagged_reviewable.id,
+ action_id: "disagree",
+ reason: "Post is fine",
+ ).invoke
+
+ expect(result[:status]).to eq("success")
+ expect(flagged_reviewable.reload.status).to eq("rejected")
+ end
+
+ it "successfully performs ignore" do
+ result =
+ tool(
+ reviewable_id: flagged_reviewable.id,
+ action_id: "ignore_and_do_nothing",
+ reason: "Not sure, deferring",
+ ).invoke
+
+ expect(result[:status]).to eq("success")
+ expect(flagged_reviewable.reload.status).to eq("ignored")
+ end
+ end
+
+ context "with a queued post" do
+ fab!(:queued_reviewable) do
+ Fabricate(
+ :reviewable_queued_post_topic,
+ created_by: Fabricate(:user),
+ status: Reviewable.statuses[:pending],
+ )
+ end
+
+ it "successfully approves a queued post" do
+ result =
+ tool(
+ reviewable_id: queued_reviewable.id,
+ action_id: "approve_post",
+ reason: "Looks good",
+ ).invoke
+
+ expect(result[:status]).to eq("success")
+ expect(queued_reviewable.reload.status).to eq("approved")
+ end
+ end
+end