Reproduce a cloudflare/agents GitHub issue by scaffolding a minimal Agents/Worker project and deploying it to a temporary Cloudflare account, then report findings back on the issue.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Reproduce a cloudflare/agents GitHub issue by scaffolding a minimal Agents/Worker project and deploying it to a temporary Cloudflare account, then report findings back on the issue.
The current user message contains an <agent-think-run> envelope with
repository, issue, instruction, requested-by, and (when available)
trigger-comment-id.
Use those values exactly. Never infer or substitute another target from examples,
workspace contents, GitHub searches, or concurrent issues. If the envelope or a
required field is absent, stop without cloning/editing/posting and return a
structured skipped result. When trigger-comment-id is present, your first
container action is the liveness reaction:
gh api repos/<repository>/issues/comments/<trigger-comment-id>/reactions \
-f content=rocket
Reproduce the bug end-to-end and post your findings as an issue comment.
The instruction is the free-form text the user typed after @agent-think (it
may be empty). Treat it as an extra hint from the triggering user
— e.g. additional reproduction steps, a specific version, or a pointer to the
suspect area. Let it guide your reproduction, but the issue itself remains the
source of truth.
All gh, git, npm, curl, and wrangler commands must run on the
container backend (bash({ command, backend: "container" })) — the shell
backend has no real binaries or network. gh is already authenticated as the
app; use it directly (no token handling).
0. Clone the repo
Clone the target repo directly under /workspace using its repository name
( → ):
any "To Reproduce" steps, code snippets, versions, or stack traces.
Decide if it is reproducible at all. If it is a feature request, a question,
a pure-docs issue, or has no concrete runnable behavior, stop here: return
skipped: true, reproduced: false, and a summary explaining why. Still post
a short, polite comment saying the repro-agent skipped it and why; begin it with
Requested by @<requestedBy> when the run envelope has a requester.
2. Understand the relevant code
With the repo cloned at $REPO_DIR, read the relevant parts of
packages/agents, packages/think, or the closest focused example under
examples/ to understand the area the issue touches. Match the user's versions
where it matters.
3. Scaffold a minimal reproduction
Work in a scratch dir under /workspace, never touch the checkout. The
read/write/edit tools use the Workspace VFS, and container bash uses its mounted
view. Put long logs in /temp, which is outside the VFS mount and only visible
through container bash.
Build the smallest project that can exhibit the bug — but every repro
ships a minimal Vite frontend (next section) so a maintainer can click the
deployed link and watch the issue happen in a UI. Keep the backend tight:
only the agent/worker code the bug needs, no auth, nothing unrelated. For
Think-related bugs, lift the relevant backend logic from the closest focused
example into the project shape below, keeping an explicit Worker entry and
Wrangler bindings — the shape itself is non-negotiable.
If the bug needs extras (@cloudflare/think, worker_loaders for the execute
tool, ai/KV bindings, …), add them to package.json, wrangler.jsonc, and
Env on top of the base recipe. Use today's compatibility_date
(date +%Y-%m-%d) unless the issue pins a version where the date matters.
Minimal frontend (required)
Every repro deploy MUST ship a minimal Vite + React page at the Worker's root URL so a human can open the deployed link, click a trigger button, and watch the failing behavior in visible output (status line / log area showing expected vs. actual). House style: one flat project, @cloudflare/vite-plugin (runs src/server.ts in workerd during dev, emits client + worker builds), agents SDK routing, Workers Assets with SPA fallback.
Steps
In $REPRO_DIR, create the 7 files below.
mkdir -p /temp && npm install > /temp/install.log 2>&1; tail -15 /temp/install.log (pin agents to the exact version under test if the bug is version-specific). Always redirect noisy commands to a container-local /temp file like this — streaming megabytes of live output through the session can kill it.
Sanity-check the build before deploying: npx vite build (catches config errors cheaply; do NOT run vite dev — it blocks waiting for a browser).
Deploy per the Deploy step below (vite build first is mandatory; the build writes dist/ plus a .wrangler/deploy/config.json redirect that wrangler deploy follows).
After deploy, confirm the root URL serves the page (the Verify step) and include the URL + click instructions in your report (the Report back step).
package.json
{"name":"<APP_NAME>","type":"module","private":true,"scripts":{"start":"vite dev","deploy":"vite build && wrangler deploy --temporary"},"dependencies":{"agents":"<VERSION_UNDER_TEST e.g. ^0.16.2>","react":"^19.2.7","react-dom":"^19.2.7"},"devDependencies":{"@cloudflare/vite-plugin":"^1.40.2","@cloudflare/workers-types":"^4.20260612.1","@types/node":"^25.9.3","@types/react":"^19.2.17","@types/react-dom":"^19.2.3","@vitejs/plugin-react":"^6.0.2","typescript":"^6.0.3","vite":"^8.0.16","wrangler":"^4.100.0"}}
vite.config.ts — add agents() from "agents/vite" FIRST in the plugin list only if the server uses @callable() decorators (rolldown/oxc can't transform them without it).
{"name":"<APP_NAME>","main":"src/server.ts",// TS source; the Vite plugin builds it"compatibility_date":"2026-06-11","compatibility_flags":["nodejs_compat"],// required by agents SDK"assets":{// NO "directory" key: @cloudflare/vite-plugin supplies the client build output"not_found_handling":"single-page-application","run_worker_first":["/agents/*"]// + any extra Worker routes the repro adds},"durable_objects":{"bindings":[{"name":"<AGENT_CLASS>","class_name":"<AGENT_CLASS>"}]},"migrations":[{"tag":"v1","new_sqlite_classes":["<AGENT_CLASS>"]}]}
tsconfig.json
{"extends":"agents/tsconfig"}
Rules (violating any of these breaks the deploy)
Never set assets.directory and never run plain wrangler dev/wrangler deploy without vite build first — the Vite plugin owns the client output and generated config.
run_worker_first is an allowlist: paths not listed get the SPA fallback (index.html), so agent HTTP/WS routes under /agents/* (and any custom Worker paths) must be listed.
Keep DO name == class_name; the client's agent: id is its kebab-case (routeAgentRequest serves /agents/<kebab-binding>/<instance>, HTTP + WebSocket).
migrations must use new_sqlite_classes (Agents require SQLite-backed DOs); "type": "module" in package.json is required.
Hand-written type Env is fine; npx wrangler types env.d.ts --include-runtime false regenerates it after binding changes.
If the bug needs extra bindings (ai, KV, etc.), add them to wrangler.jsonc and Env — everything else stays as above.
4. Deploy to a temporary Cloudflare account
The shell has no Cloudflare credentials, so use the temporary-account flow
(requires wrangler >= 4.102.0). vite build must run first — it produces the
client assets and the deploy-config redirect wrangler follows:
npm run deploy # = vite build && wrangler deploy --temporary
This creates/reuses a temporary preview account and deploys to a
*.workers.dev URL. Capture the live https://...workers.dev URL from the
output → liveUrl. Ignore the claim URL the deploy prints — it never goes in
a report.
If the build/deploy itself fails in a way that is the bug, that is a valid
reproduction — record the exact error. If it fails for an unrelated reason, fix
the scaffold and retry (do not change SDK source).
5. Verify the reproduction
Actually exercise the deployed worker and confirm the reported symptom. First
check the frontend is up, then hit the buggy path the same way the UI's
trigger button does:
curl -sS -i "<liveUrl>/" | head -5 # 200 + HTML = frontend serving
curl -sS -i "<liveUrl>/agents/<kebab-binding>/demo<path-that-triggers-the-bug>"
Compare against the expected behavior. Only set reproduced: true if you
observed the bug (wrong output, error, crash, etc.). If it behaves correctly,
set reproduced: false and explain — the issue may be fixed, version-specific,
or need more detail. Either way the deployed page must demo the behavior a
human should look at.
6. Push the repro to a branch
Publish the repro project as an orphan branch on the target repo so anyone
(human or agent) can pull exactly what you built and run it:
Never do this inside $REPO_DIR — the clone must stay intact for the
root-cause hypothesis and any follow-up PR work. Publish from a scratch dir:
The scratch git init publishes an orphan branch with no base-repo
history; the checkout IS the runnable repro
(git clone -b repro/issue-<issueNumber> ... && npm install && npm run deploy).
One canonical branch per issue: re-runs force-push the same
repro/issue-<issueNumber> branch.
Capture https://github.com/<repo>/tree/repro/issue-<issueNumber> as
reproBranchUrl. If the push is rejected (branch protection), say so in the
report and continue — the branch is best-effort, the report is not.
7. Report back on the issue
Post a comment with gh. Build the body in a file to keep formatting clean:
Requested by @<requestedBy> near the top, using the exact sanitized
requested-by mention from the run envelope (omit only when it is unknown).
Verdict: reproduced / could not reproduce / skipped, with one-line reason.
Live URL plus one line of click instructions ("open it, press Trigger
bug, watch the log") — the page is the demo. Phrase it exactly like:
"Repro URL (expires after 60 mins): ".
Repro branch: the reproBranchUrl link — "pull this branch to run the
repro yourself". This is what other agents check out to build on your work.
Minimal repro: the key files (wrangler.jsonc + the agent/worker source) in fenced code blocks, or a short git-style listing.
What you observed vs. expected, including relevant curl output / errors.
Root-cause hypothesis if you have one (point at the suspect file/line in packages/).
