Puzzle game hints: three-source arbitration with an external veto
Official cookbook recipe
- Industry
- Gaming & entertainment · Puzzle hints
- Source
- Official open-multi-agent cookbook
- Stage
- Runnable example
This is an official open-multi-agent cookbook example, maintained by YuanASI. It generates one hint for a point-and-click puzzle game: mechanics, lore and player-data agents each read one set of material and propose a hint, an arbiter agent compromises by the priority "safety > immersion > progress", and finally a separate safety agent checks the designer's rules and decides whether to let it through or veto it.
Scenario
A typical scenario: a player is stuck on a puzzle and the game has to offer a hint. The three sides often clash: the narrative team wants hints in a character's voice, only as metaphor; live-ops data shows that saying "look at the mirror" outright works best; and the designer has made the link between the piano and the mirror a mid-story twist, so no hint may point at it. Weighing these by hand, one case at a time, the compromise sentence can still give the solution away.
This example writes those three sides as mutually isolated agents and places the final ruling outside the generation step: the arbiter agent sees only the three structured outputs, never the raw material; the safety agent reads the designer's rules on its own and returns a binary veto, and on a veto swaps in a fallback hint that only describes the atmosphere and gives no direction.
How it works
| Roles | Task DAG | Tools | Model | Deployment |
|---|---|---|---|---|
| mechanic-agent | Layer 1: reads the save file extracted-game-state.json, outputs puzzle progress, writes no player-facing text | tools: [], empty tool registry | claude-sonnet-4-6 / anthropic | Local script, one run with npx tsx |
| lore-agent | Layer 1: reads Tier 1 and Tier 2 of lore-corpus.md, proposes a metaphorical hint in a character's voice | Same | claude-sonnet-4-6 / anthropic | Same |
| community-agent | Layer 1: reads community-aggregates.json, proposes a hint based on stuck rates and hint effectiveness | Same | claude-sonnet-4-6 / anthropic | Same |
| hint-arbiter | Layer 2: receives only the three structured outputs above, flags conflicts and writes a compromise hint | Same | claude-sonnet-4-6 / anthropic | Same |
| safety-agent | Layer 3: reads designer-constraints.json and the arbiter's draft, decides whether to veto | Same | claude-sonnet-4-6 / anthropic | Same |
The models in the table are the example repository's defaults; the actual choice is made per scenario at the design stage.
The example builds the five agents directly, without task orchestration: each set of material is injected as text into its own agent's prompt, tool registries are empty, and each agent sees only the material assigned to it. The three layer-1 agents run one after another with await in code; layers 2 and 3 start once the previous layer's structured results are in hand.
All five agents have a Zod outputSchema, maxTurns 1 and temperature 0.1. When framework-side validation fails, it asks once more with the error message attached (validateStructuredOutput in src/agent/agent.ts); the script's runTimed gives each layer-1 agent up to three attempts, and the arbiter and safety agents run once each, exiting with code 1 if no structured result comes back.
In the designer's rules, piano-mirror-combo has sensitivity high and allowed directionality zero; the protected link is "piano ↔ mirror", and revealing the relationship between the objects, pointing toward the mirror or giving away steps are all prohibited; the fallback on a veto is an atmospheric description plus a nudge to explore.
Result
Runnable artifacts and how to verify them:
Requires an API key. The script header lists ANTHROPIC_API_KEY and Node.js 20 or later as prerequisites, and the model can be overridden with the MODEL environment variable; run it with npx tsx packages/core/examples/cookbook/narrative-puzzle-hint-arbitration.ts.
The console prints each agent's duration and output tokens across the three stages, then the full arbiter draft and safety review as two JSON blocks, and finally the total input / output token counts.
The script runs 6 runtime assertions: the arbiter detects a conflict, the conflict list is non-empty, the lore agent does not judge whether a solution is right, the player-data agent does not give the full solution, the safety agent vetoes this compromise, and after the veto the fallback hint type contains atmospheric. If any fails, it prints Runtime assertion failed. and exits with code 1.
Tested on commit 2f1d0ff on 2026-09-23: all three layer-1 agents passed on the first attempt; the arbiter draft had conflict_detected true and listed 4 conflicts; the safety agent judged that "listen while you play" and "turn toward the song" in the compromise hint amounted to a directional hint toward the mirror, with veto_triggered true and the fallback hint type vague_atmospheric_description_with_exploration_nudge; all 6 assertions PASS, 8183 input / 8162 output tokens in total, exit code 0. This test run swapped the example's committed anthropic / claude-sonnet-4-6 for DeepSeek's deepseek-flash; the rest of the logic ran unchanged.
All four inputs are labelled MOCK: the save file, lore material, player data and designer rules are fictional and come from no real game; the output is model-generated text for demonstrating and verifying the flow.
Sources
How this relates to YuanASI
The material on this page is a cookbook example in the official open-multi-agent repository, maintained by YuanASI.
If you have a real content-generation process where several sources each propose output, an arbitration step finds the compromise, and a separate pre-publication veto applies your own rules, connected to your content library and operations data, the matching YuanASI service is Multi-Agent System Integration →
Related services
Last updated
Want to know how a workflow like this would land on your side?