microsoft / microsoft/Agent-Framework-Samples

Sample proposal: reliable multi-agent handoffs with checkpoints and safe retries

Open
#115 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Jupyter Notebook
Stars
378
Forks
147
PR merge metrics
No merged PRs in 30d

Description

Why

The repository already demonstrates multi-agent routing, concurrent workflows, MCP, and tracing. A useful production-oriented addition would cover a harder failure mode: a worker completes an external action, but its response is lost. A coordinator that treats this as an ordinary failure can retry the handoff and duplicate the action.

Proposed sample

Add a small, provider-neutral multi-agent workflow (under 07.Workflow, or another maintainer-preferred location) with a coordinator, two competing workers, a mock destination, and a reliability-sidecar boundary:

  1. The coordinator derives a stable workflow/action key and writes a shared checkpoint before handoff.
  2. Two workers race to claim the same duplicate-sensitive action; atomic admission allows only one to execute it.
  3. The sample injects a timeout after the mock destination records the result but before the worker returns.
  4. Recovery treats the result as ambiguous, reads back the destination, records evidence, and resumes without replaying the action.
  5. A verifier advances the checkpoint only after evidence is present and reports the proof scope honestly.

The output/tests should show:

  • two contenders, one admitted execution, and one destination record;
  • restart/resume from a durable checkpoint;
  • no automatic retry of an ambiguous result;
  • a retry only after an explicit known-failure policy; and
  • the distinction between caller-reported evidence and independently verified proof.

Portability

The sample could define a minimal ReliabilityBackend protocol (claim/admit, checkpoint, transition, status) with a deterministic local adapter for tests. A remote MCP adapter would be optional, so the pattern is not tied to a vendor. Agent Enhancer Utilities is one free, no-auth reference implementation, but the sample would remain runnable without it and document the semantics rather than a product.

No real email, ticket, payment, or other external side effect is needed; a counted mock sink makes the invariant testable.

If this fits the samples roadmap, I can prepare a focused PR after guidance on preferred language (Python, .NET, or both) and placement. I will not open one before maintainer confirmation.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the existing samples under 07.Workflow and the repository's multi-agent routing, concurrent workflow, MCP, and tracing examples. Confirm the preferred language and placement with maintainers before implementation. Done means the sample and tests demonstrate single admission, durable resume, ambiguous-result handling without replay, explicit known-failure retry, and the stated evidence distinction.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend-api-design, distributed-systems, testing
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.