agent-swarm.devagent-swarm.dev
Guides

Preparing marketplace moderation appeals for human review with AI agents

Agent Swarm gathers the permitted records, the dated policy and the original decision for a listing appeal, and a person decides.

Agent Swarm can be configured to gather the permitted records, the dated policy that was in force and the original decision behind a marketplace moderation appeal, then draft a source-linked case packet for the reviewer who will rule on it. A named person makes that decision and records it. The setup is assembled from documented parts, not from a built-in moderation or appeals feature: nothing in the product ships as a case management system, an appeals queue or a decision engine.

The scope is one case: a seller appealing a listing moderation decision that has already happened. A catalog attribute error, a conflict between two help articles, a support ticket that needs engineering, a supplier security review, an inventory exception and feedback synthesis are separate handoffs with separate owners.

When a specialist moderation platform or manual review fits better

Most marketplaces should start with a cheaper answer, and for many it is the right one.

Low appeal volume. If a reviewer can open the listing and the decision record in three screens and settle the case, that is the process. Adding agents would put a document between the reviewer and the two tabs they already have.

A trust and safety platform that already holds the case. Moderation vendors keep the case history, the policy versions, the reviewer queue and the audit trail in one place, with the routing rules and escalation ladders that appeals work needs. When that system is where the evidence lives, its queue is the place to decide.

Categories with legal or regulatory handling. Illegal content, material involving minors and law enforcement requests belong to specialist tooling and to counsel. An agent drafting a packet in that space adds a failure mode without adding judgement.

Agent Swarm fits when the evidence sits across systems the platform does not join: the listing snapshot in the catalog service and the decision in the moderation tool, with the appeal message and the policy text in other stores. Assembling those into one packet, with a link on every fact, is the work. The decision stays with a person. Choosing an AI operating model sets out that split.

An illustrative workflow

What follows is an illustration of how the documented pieces fit together. It is not a customer run and not a measured result. Adapting it needs permissions, configuration and probably a custom integration for at least one of your systems.

  1. An appeal opens a case. A seller appeals a listing decision that already exists. The appeal arrives through whatever channel you run, and something has to tie it to the original decision. Without that link there is no case, only a message.
  2. Deterministic steps gather only the permitted records. Configured collection steps pull the listing as it was decided, the original decision with its reason code, the seller's appeal text and the policy version in force on the decision date, with that version's own date. These are swarm-script steps and they emit JSON, so no model is asked to fetch the records or to do the date arithmetic. Reports from multiple sources documents that split between deterministic collection and synthesis.
  3. An agent drafts the case packet. Each fact carries a link to the record it came from. The packet holds the relevant evidence, the items that are missing and who could supply them, and the open questions the reviewer has to answer.
  4. A named reviewer decides. Uphold, reverse or escalate, with the reason recorded against the case. The packet is input to that decision, never a substitute for it.
  5. A person approves anything that reaches the seller. A human-in-the-loop gate pauses the workflow, posts to Slack and resumes only when a person responds, with a summary and a link to the full packet. Nothing is sent to the seller on its own.

A fictional example

Rivet & Row is invented for this example. It is a used-equipment marketplace, and nothing below reports a real case or a measured result.

A seller lists a used bench grinder. The listing is removed under the marketplace's prohibited-claims policy, and the seller appeals, saying the wording the moderator quoted had been changed before the removal.

The packet shows four things. The decision date is 14 May. The policy in force on that date is version 3, dated 2 February. Version 4, dated 20 May, changed the rule and post-dates the decision. The listing snapshot stored at decision time differs from the version the seller points to: a sentence about the machine's certification was edited out of the description, and the packet holds both versions side by side. And one item is missing, because the edit timestamp is not in the records the workflow is permitted to read, so the packet cannot say when the wording changed.

The packet names that gap as a question for the reviewer: was the wording the moderator saw the wording that was live on the decision date, and if not, does version 3 still govern? The reviewer decides, records the reason and the governing policy version, and the case closes on a person's ruling.

What the packet has to handle

Access limits. RBAC gates requests made with user tokens; operator-key calls and agent calls are not affected, so RBAC decides which people can open or approve a case, not what an agent can read. What bounds an agent is the credentials its collection steps hold. Script connections register each system once, as a connection or a credential binding, scoped global (the default), agent or repo, so scope the appeal sources to the agent that drafts packets. The credential broker substitutes the secret only for allowlisted hosts, so no raw key sits in script source or arguments. The AI operations governance guide covers the policy your company still writes.

Sensitive content. Appeal evidence can include images that are themselves the violation, or personal data about the seller or a buyer. Link to the record instead of copying it into the packet, redact what the packet displays and restrict who can open it at all. The packet carries links to the source records rather than copies, and every completed or failed task output is indexed into memory automatically, so the indexed output holds references. Memory is agent-scoped or swarm-scoped: shared memory is visible to every agent, and agent-scoped memory is visible to its owner and searchable by the lead, as Memory sets out. Keep images and personal data out of the task output and out of anything stored with swarm scope.

Retention. A packet holds a moderation decision and personal data, so it inherits whatever retention your policy sets. The policy is yours to write and yours to enforce. A workflow that keeps packets and logs indefinitely is a liability, not an archive.

Policy versions in conflict. Show both dated versions and say which was in force on the decision date. Do not have the agent pick one. Which version governs is a question about your own rules, and the reviewer or counsel answers it.

Uncertain evidence. Mark it uncertain and say what is missing. A packet that resolves a gap by inference is worse than one that names it, because months later nobody can tell the two apart.

Escalation outside the reviewer's remit. When a packet flags a category the reviewer is not cleared for, route it to a senior reviewer or to legal. That routing rule belongs in the workflow, not in one reviewer's memory.

A route for correction. The seller or the reviewer can flag a fact in the packet as wrong. The correction is recorded with who made it and when, and the packet version that was actually reviewed stays retrievable.

What the agent never does

  • It does not decide to remove or reinstate content. That decision belongs to the reviewer who signs it.
  • It does not guarantee fairness or consistency across cases. A packet makes the evidence visible; it does not make two reviewers agree.
  • It does not give legal advice, and it does not label a listing or a case as lawful.
  • It does not send an outcome to the seller without a person's approval. There is no path from packet to seller that skips the gate.

On this page