Agent Failure Recipes

From understanding the failure to keeping the test

Agent Explainer makes failure mechanisms visible. Agent Failure Recipes takes the next step: small pieces of executable code that you can inspect, run locally, and adapt to your own test suite.

Start in the browser. Run a broken implementation, select an event to inspect the state, then apply the repair from the same starting conditions. Download the evidence or copy the Vitest example. The browser, CLI, and tests execute the same recipe functions.

Three failures worth testing

• The action happened twice. A ticket commits, but its response is lost. Retrying without an operation key creates a duplicate. The repair reuses one key with a service that supports idempotency. The test counts committed tickets.
• “Accepted” is not “done”. A report request is accepted before its output exists. The repair checks the authoritative job status and artifact within a deadline, including failure and cancellation handling.
• The retry makes it worse. Immediate retries exhaust the attempt budget while the service is still rate limited. The repair respects Retry-After and bounds both attempts and elapsed time.

For the engineering reasoning behind the first two repairs, read the Fieldbook guides on duplicate actions and verifying completion.

Run it locally

Requires Node.js 24 or later and npm. No model API keys or account setup.

git clone https://github.com/swapupg/agent-failure-recipes.git
cd agent-failure-recipes
npm ci
npm run check
npm run recipes

The teaching suite expects the broken implementation to reproduce its bug. To see an intentionally failing command, run node dist/cli.js duplicate-action --variant broken; it exits with code 1. The repaired variant must satisfy the state assertion.

The repository includes an importable library, a CLI, copyable Vitest examples, and a browser workbench. The v0.1.0 release includes the tested package and checksums. It is not published to the npm registry.

What the result establishes

These are deterministic test fixtures, not model benchmarks. They do not call a live model or create tickets on external services. A passing recipe establishes one invariant under one controlled fault.

The fixture stores are in memory. They do not prove production persistence, permissions, or multi-worker correctness. Idempotency requires server support and atomic storage. Real job adapters need request-level timeouts and artifact verification. Production retry policies need safe operations, independent jitter, and budgets across layers.

The initial release passed unit and integration tests, browser journeys, and checks against its deployed artifact. That verification does not establish adoption, learning outcomes, or the reliability of a different system. The project remains a public beta.

Make it your own

Use the adaptation guide to replace a fixture with a disposable test service while preserving the injected fault and independent assertion. Run the test against the broken implementation before accepting the repair.

The code is MIT licensed, with no runtime dependencies or telemetry. Contributions can improve an explanation, strengthen a regression test, fix accessibility, or propose a small new recipe through the contribution guide.