agent-swarm.devagent-swarm.dev
Guides

Reviewing a supplier ingredient specification change with AI agents

Agent Swarm can assemble a source-linked packet on a supplier's changed ingredient specification for people to verify and decide.

Agent Swarm can help purchasing and food-safety teams prepare a source-linked packet for human review when a supplier changes an ingredient specification, while staff verify ingredient and allergen information and decide every action. Configured steps collect the new specification and the last approved version, compare them field by field, find the recipe records that use the ingredient, and put one packet in front of a named food-safety owner. What the workflow takes off the team is the assembly: finding one ingredient's approved specification and the recipe records that depend on it.

The scope is one specification change for one ingredient with food-safety implications, reviewed before any recipe, label or menu is touched. Three neighbouring jobs have their own guides: periodic supplier performance for one supplier and one period, pre-onboarding security evidence, and listing differences across sales channels.

When another tool fits better

Two established options cover this ground.

Purpose-built food-safety, specification-management or PLM and recipe software that already holds the approved specifications. If the company keeps its specifications and recipes there, and suppliers submit changes through its portal, that product is doing the job, with the version history and the approval trail. Agent Swarm ships no specification template, no allergen database, no label tool and no supplier portal.

A qualified food-safety person's own review, when the question is small. For a single supplier, or any allergen question, a person qualified to judge it reads the two documents and decides. An expert review that fits in a sitting does not need a workflow; routing it through one adds a step without evidence.

Agent Swarm fits a different shape: the documents are apart and several teams hold a piece of them. The last approved specification lives in a document store, the new version arrives as an attachment, and the recipes that use the ingredient sit in an ERP or a spreadsheet. Assembling the pieces is the work. Choosing an AI operating model sets out that split.

An illustrative workflow

This is an illustrative design, not a built-in food feature, not an integration and not a customer result. The supplier and the ingredient in the example are invented, and every comparison rule and source connection is custom configuration your team builds and tests, through script connections with credentials taken from the credential broker.

1. The food-safety owner writes the comparison rules first. Before anything is collected, the owner states which fields must be present: the ingredient name, the supplier's product code, the component list with quantities, the allergen declaration, the country of origin, the version and its date, and who approved it. The owner also writes what counts as a change worth stopping on, for example a component quantity moving past a stated tolerance, or an allergen declaration changing at all. The rules belong in the workflow's governance record, so the next review starts from the same version.

2. Collection runs as a deterministic step. A swarm-script step collects the new specification and the last approved version and emits JSON, so the same inputs produce the same records and no model chooses which document to open. In the example, a fictional supplier, Cardamom Row, revises the specification of its seasoning blend: the salt quantity becomes a range and the allergen statement moves to a different section. Reports from multiple sources documents that collection-first pattern.

3. The comparison runs in code. The script compares the two documents field by field against the written rules and surfaces the source date of each version and the fields missing from either version. Code does the comparison, not the agent, so the result stays repeatable when someone asks why a field was flagged.

4. A deterministic step finds the recipe records that use the ingredient. The lookup matches the ingredient's name and the supplier product code against the recipe records the swarm may read, and returns each record's identifier and revision date. A record it cannot read is named.

5. An agent writes the packet. The agent turns the checked JSON and the source documents into one document: what changed, which field each line rests on, which fields are missing, and which recipes use the ingredient. Every line carries its source and the date behind it.

6. The packet is stored as a file and linked from the gate message. It lives as a file the owner can keep; the gate message carries a summary and the link. The human-in-the-loop gate pauses the workflow, names the food-safety owner and a backup, carries a timeout and a fallback, and resumes only on a human response. It never proceeds on silence. If the specification is incomplete, the owner can request a corrected version and the next run starts from it.

What the packet flags

Five conditions are worth naming in the rules.

  • A required field left blank. An allergen declaration or a country of origin field with no value, in the new version or the one it replaces. The packet names the field, the document and the owner who can request it.
  • An ambiguous change. A component renamed without a note, a fixed value replaced by a range, or a "may contain" statement that moved section. The packet shows both versions and does not decide what the change means.
  • A date or version conflict. The version on the specification does not match the one the supplier's email cites, or the new document is dated before the one it replaces. Both are shown with their dates.
  • A source older than the freshness window. The last approved specification predates the window the owner set, or a recipe extract has not refreshed. The packet reports the document date.
  • A recipe record the swarm could not read. A recipe that matches the ingredient but sits in a system the workflow cannot reach, or in a format it cannot parse. The packet names the record and who can supply it.

Each is shown with both sources and left unresolved. A packet that picks one version over another hides the disagreement the review exists to settle.

What stays human-owned

Five decisions stay with people in every version of this workflow.

  • Verifying the ingredient and allergen information. Whether a declaration is complete and correct is a judgement a qualified person makes against the specification.
  • Determining the food-safety risk. Whether a change matters, and what it means for the product, is a food-safety decision, not a comparison result.
  • Any recipe, label or menu change. Reformatting, reformulating, relabelling or withdrawing a product is a decision people make and record.
  • Contacting the supplier. Any question about a field, a version or a corrected document goes through the person who owns the relationship.
  • Authorizing every change and every communication. Approval is a person's act with a name on it, at the gate and in the record.

An agent cannot establish food safety, cannot guarantee allergen accuracy, cannot approve a label and does not replace qualified food-safety review. It has no path to message the supplier or change a recipe. The pattern is the one the HITL guide states: gate the irreversible step and let the reversible ones run. Collecting documents and writing the packet are reversible. Approving a reformulation is not.

Limitations

An incomplete specification stays incomplete. Where the supplier has not supplied a field, the packet names the gap and the owner who can get the document. It does not infer a value from a previous version.

Ambiguous changes are reported, not interpreted. A renamed component or a range replacing a fixed value is shown as a difference; whether it is a reformulation, a clerical correction or a labelling question belongs to the food-safety owner.

The packet only covers the systems the swarm may read. Where the archive or the recipe records sit behind an unconnected system, the packet says so and names who can grant access. It does not ask someone to paste a document into a chat.

Access control has a limit. RBAC is on by default and restricts requests made with user tokens. Operator-key calls and agent calls are not affected, so the role model is not the only control on what a workflow can read.

Review checklist

  • Sources and freshness. Name each source, the document version and date, the freshness window, and the extraction dates covered.
  • Access scope. Write down which systems the workflow may read, who granted that access and when it is reviewed.
  • Missing fields. Confirm the packet names each gap and an owner rather than filling it.
  • Review ownership. Name the food-safety owner and a backup, and say who reads the packet before the gate.
  • Approval. State who decides, what the timeout is and what happens when nobody answers. Silence is never approval.
  • Rules. Keep the comparison rules next to the run, so a later packet can be read against them.

Building blocks

Each piece below ships in agent-swarm and is documented. Pointing them at an ingredient specification change is the illustrative part.

  • HITL gates: the blocking human-in-the-loop node, the approve and reject branches, the timeout and fallback, and the gate message.
  • Reports from multiple sources: deterministic swarm-script and script-run collection that emits JSON, then an agent that synthesizes it.
  • Script connections: register an OpenAPI, GraphQL or MCP API once and call it from a script with a typed client.
  • Scripts credential broker: how scripts authenticate outbound calls without the raw secret in source, arguments or logs.
  • AI operations governance: a named owner per workflow, RBAC roles, approval thresholds and source-of-truth rules.
  • Choosing an AI operating model: how to choose between a spreadsheet, a specification product and a shared agent platform.

On this page