Sample proposal: record a Strands agent run and replay it offline (no provider call)

Aperta
#304 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
30/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
ai-infra-agents, python
Ambito
ai, testing

Direzione di ricerca

This is a proposal for a new sample under python/, not a code change, so first confirm with maintainers per CONTRIBUTING §3 that the sample is wanted. If accepted, follow .github/templates/use-cases/structure.md and the README template: one agent.py with callback_handler=None, plus a README with the record/replay commands, the shown output, and the Limits section. Done means the sample runs and its README states the egress and determinism caveats.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Proposal

I'd like to contribute a sample under python/ showing how to record a Strands agent run and replay it offline — the run happens again with no model provider contacted and no API key needed — so a failed session becomes something a colleague can re-run, and a recorded run can guard changes in CI.

Opening this first per CONTRIBUTING §3 rather than sending the PR unannounced. Happy to drop it if it isn't a fit.

Why it might be useful here

The awkward part of testing an agent is that real calls cost money, need a key, and don't answer the same way twice — so agent samples tend to stop at "here's how to run it" and don't show how to pin a run down. A recorded run gives a sample the missing half.

The capture happens outside the process: the agent is launched as a child with its model-provider origin redirected for that process only. Nothing is installed into the agent and no callback handler is registered, so the sample code is ordinary Strands code — which matters for a sample, since an instrumented variant would teach the wrong thing.

Verified, not proposed

I ran this against the SDK before writing the issue:

$ orca record generic-openai -- python agent.py
info recorded run=run_... events=6 exit=0

# provider process killed, nothing upstream to reach
$ orca replay last
info replaying exchanges=1 egress=blocked
info replay.done reused=1/1 exact=1 divergences=0 unmatched=0 exit=0

exact=1 means the replayed request matched the recording byte for byte — system prompt, message assembly and tool schemas all reproduced. The agent's own event loop and tool dispatch run for real; only the model's answer comes from the trace.

One Strands-specific detail the sample would state: pass callback_handler=None, otherwise the streaming callback output makes it look as though the capture instrumented the agent when it didn't.

Shape

Following .github/templates/use-cases/structure.md and the README template: one agent.py, a README with the record/replay commands and the output above, and an explicit Limits section:

  • egress=blocked is model-provider egress, not network isolation — replay re-executes the recorded tool calls for real, so a tool that fetches a URL or writes to a store does it again. Not a sandbox.
  • A matching replay is not a determinism result — the model isn't re-asked; its recorded answers are served back.
  • A trace holds whatever the run held; review before sharing.
Disclosure

I maintain the tool used (OrcaReplay, Apache-2.0), so treat this as a vendor-authored sample and weigh it accordingly. I've also posted the SDK test result in sdk-python#4265 and a catalog entry in harness-sdk#4305 — saying so up front so it's visible that this is the third touchpoint with the org, not a coincidence. If a sample is one too many, I'd rather hear that now than after the PR.

While testing I also hit RuntimeError: generator didn't stop after athrow() on interpreter shutdown, reported in the discussion above.

Lingua principale
Python
Stelle
897
Fork
450
Merge medio
1g 9h
PR unite (30g)
9

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di strands-agents/samples

Tutte le issue di strands-agents/samples

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.