Add Claude Managed Agents integration guide#193
Conversation
Guide for running Anthropic Claude Managed Agents with tool execution inside Sprites via a self-hosted environment: create the environment, generate the environment key, spawn a Sprite per session (runner as a supervised service), run an always-on poller (or webhook) worker, and start a session. Adds the page to the Integrations sidebar group. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Preview Deployment
Commit: |
Lighthouse Results
|
E2E Test Results✅ Tests success Ran against: https://pr-193-superfly-sprites-docs.fly.dev |
Two-variant header art toggled by theme via a .light-only/.dark-only CSS utility in custom.css. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
|
||
| You need: | ||
|
|
||
| - A **Sprites API token** (`org/projectNumber/tokenId/secret`). Export it as `SPRITES_API_KEY`. |
There was a problem hiding this comment.
SPRITES_API_KEY / org/projectNumber/tokenId/secret don't match the rest of the docs or the client.
Two things here.
Env var: every other page and both SDKs use SPRITE_TOKEN (see reference/configuration.mdx). SPRITES_API_KEY doesn't appear anywhere else in the docs. Suggest SPRITE_TOKEN here and at line 73 (os.environ['SPRITE_TOKEN']).
Format: the client's own validator expects org-slug/org-id/token-id/token-value (client/commands/auth_setup.go). The 4-segment shape is right, but the second segment is the org ID, not a "projectNumber."
Suggested:
- A **Sprites API token** (`org-slug/org-id/token-id/token-value`). Export it as `SPRITE_TOKEN`.
|
Could you do a pass to remove the em dashes on this page (there are 6), reworking them into commas, colons, parentheses, or separate sentences? Trying to keep our prose em-dash-free for consistency. |
| await client.beta.environments.work.worker( | ||
| environment_key=key, workdir="/workspace", unrestricted_paths=True | ||
| ).handle_item() |
There was a problem hiding this comment.
This worker(...).handle_item() call doesn't match the documented SDK signature. Can we confirm it runs as written?
Anthropic's self-hosted-sandboxes docs document this as:
worker(workdir="/workspace").handle_item(
work_id=…, environment_id=…, session_id=…, environment_key=…
)So environment_key goes on handle_item, unrestricted_paths isn't a documented param, and handle_item takes the work/session/env IDs explicitly. Here handle_item() is called with no arguments, so it can only work if it auto-reads ANTHROPIC_WORK_ID/SESSION_ID/ENVIRONMENT_ID/KEY from the environment (which the service does source). That's plausible, since ant beta:worker run reads exactly those, but it isn't shown for the SDK in Anthropic's published docs.
Since this is presented as copy-pasteable ("one call is the whole worker"), could we either (a) match the documented signature by passing the IDs explicitly from the sourced env vars, or (b) pin the SDK version and note that it relies on env-var autoconfiguration? Whatever the cookbook actually ships should be the source of truth.
| # Service supervises the runner and self-stops when it exits. | ||
| cmd = (f"set -a; . /root/runner.env; set +a; python3 {RUNNER_PATH}; " | ||
| "sprite-env services stop agent-runner >/dev/null 2>&1 || true") | ||
| c.put(f"/v1/sprites/{name}/services/agent-runner", |
There was a problem hiding this comment.
Create Service omits needs, which the API reference marks required. Same with workingDir on the fs/write calls (lines 103, 122). Likely fine in practice (empty default, absolute paths), but worth confirming these don't 400. If needs is required:
json={"cmd": "bash", "args": ["-lc", cmd], "needs": []}
| environment_id=env_id, environment_key=key, | ||
| reclaim_older_than_ms=2000, auto_stop=False, | ||
| ): | ||
| if work.data.type == "session": |
There was a problem hiding this comment.
Confirm "session" is the actual work-item discriminator. Anthropic's own poller example doesn't filter, it spawns for every claimed item. If work.data.type isn't literally "session", this silently drops every item and no Sprite launches. Verify against BetaSelfHostedWork, or drop the filter to match the reference.
|
|
||
| ## 3. Spawn a Sprite per session | ||
|
|
||
| The worker creates a Sprite, uploads Anthropic's provider-agnostic runner, installs the SDK, and starts the runner. Run the runner as a Sprite [service](/concepts/services), not a detached `nohup` process: a Sprite reaps an exec's process tree when the request connection closes, so a backgrounded process would not survive. A service is supervised and outlives the request, and it self-stops on exit so the one-shot worker is not restarted. |
There was a problem hiding this comment.
Can we source the "reaps an exec's process tree when the request connection closes" claim? It's the justification for using a service over nohup, and the design is correct, but I can't find it stated in any docs page. A link or a one-line confirmation from sprite-env behavior would make it airtight.
| }]) | ||
| ``` | ||
|
|
||
| The file the agent writes lands in `/workspace` inside the Sprite, which persists for the Sprite's lifetime. |
There was a problem hiding this comment.
Nice and clear that files land in /workspace. One small thing that might help readers coming from Anthropic's docs: their harness usually directs final deliverables to /mnt/session/outputs (you mount a host dir there to grab them). /workspace works great here thanks to unrestricted_paths=True, so maybe just a sentence noting that /workspace is this guide's convention? Totally optional.
kcmartin
left a comment
kcmartin
left a comment
There was a problem hiding this comment.
Thanks for putting together this guide! Left some comments and suggestions.
|
|
||
| ## 3. Spawn a Sprite per session | ||
|
|
||
| The worker creates a Sprite, uploads Anthropic's provider-agnostic runner, installs the SDK, and starts the runner. Run the runner as a Sprite [service](/concepts/services), not a detached `nohup` process: a Sprite reaps an exec's process tree when the request connection closes, so a backgrounded process would not survive. A service is supervised and outlives the request, and it self-stops on exit so the one-shot worker is not restarted. |
There was a problem hiding this comment.
nit: A lot of repetition of "run/runner" here
An animated SVG React island: a 2x2 grid read as a clockwise loop (Platform enqueues -> worker claims -> worker launches a Sprite -> tool calls round-trip), with tinted zone bands making the trust boundary explicit. Built with motion.dev; adapts to light/dark and degrades to a static image under prefers-reduced-motion. Also restructure the guide's headings into H2 sections with H3 sub-steps. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Use SPRITE_TOKEN and the correct token format (org-slug/org-id/ token-id/token-value), matching the rest of the docs - Add required schema fields: workingDir on fs/write, needs on service create - Document where handle_item() gets its IDs (ANTHROPIC_* env vars; confirmed against anthropic SDK 0.115.0 and the cookbook runners) - Confirm "session" work-data discriminator against the SDK and annotate the filter - Drop the undocumented exec-reaping claim; justify the service via documented supervision behavior, and deduplicate "run/runner" - Note /workspace is this guide's convention vs Anthropic's /mnt/session/outputs default Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Rework them into parentheses, commas, colons, and code-comment parens to keep the prose em-dash-free per review feedback. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Lighthouse flagged the page at 3.8 MiB, 2.8 MiB of which was the two header PNGs (2172px intrinsic, served to a ~736px column). Convert both to 1472px WebP (95 + 66 KiB) and add width/height so the images no longer shift layout. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adversarial review against the cookbook (anthropics/claude-cookbooks PR 751), the anthropic SDK source, and the Sprites API reference surfaced four defects: - Correct the inverted unrestricted_paths explanation: the workdir is what permits /workspace (Anthropic's system default working directory, not this guide's convention); the flag is what allows paths outside it, such as /mnt/session/outputs - Add the cookbook's error handling to spawn() (create-status guard, raise_for_status on writes/service, exec exit-frame check) and a per-item try/except in the poller so one bad item cannot kill the worker - Restore the cookbook's find_live() guard so redelivered work for a live session no-ops instead of re-provisioning a mid-session Sprite - Replace the impossible checkpoint pre-bake advice: checkpoints restore only into the same Sprite, so cutting install cost means reusing prepared Sprites, not baking a fresh-per-session one Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Warn that a service does not hold a Sprite active: a quiet runner hits the ~30s idle window mid-session, so register a Task for the session's duration (per concepts/lifecycle and keeping-sprites-running) - Stop asserting a duplicate-name status code the API reference contradicts; keep the cookbook's tolerated-status guard - Scope the intro claim to code, filesystem, and network egress (tool inputs and outputs flow to Anthropic), and align the diagram aria-label with its visible caption - Reframe the poller comment: the filter skips non-session work items such as platform health checks, not "the only type today" - Drop em dashes from diagram code comments Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The cookbook's runner service now holds the Sprite active during a session (register a Task, heartbeat it, delete on exit); mirror that in the spawn() snippet and turn the idle-window warning into an explanation of what the task in the command is for. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Guide:
- List the Claude API key as a prerequisite (stays off the Sprite)
- Add the runner's logging bootstrap so failures surface in the
service log, matching the cookbook's full runner
- Correct the env-file rationale (file instead of service args) and
delete the file right after sourcing so the key never persists
- Add a Clean up section: paused Sprites keep accruing storage, so
reap claude-agent-* Sprites after session end via DELETE
/v1/sprites/{name}, copying out /workspace first
Diagram:
- Replace context-stroke arrowheads (unsupported in Safari) with
clay/violet themed markers
- Gate animation on client mount so SSR emits the complete static
diagram with no hydration mismatch under prefers-reduced-motion
- Raise small label sizes for phone-width legibility and shorten the
boundary caption to keep clear of the claims arrow
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
In a real session the agent wrote its deliverable to an absolute path outside the workdir (permitted by unrestricted_paths), so state the durable-disk guarantee and make /workspace the relative-path default rather than a promise. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The hero images sit on flat black (dark) / near-white (light) rectangles that seam against the page background. Screen erases the dark variant's true-black background; multiply plus a hair of brightness (to clip the light variant's #fefefe up to pure white) erases the light one. Full effect requires lifting Starlight's .main-pane isolation, which ships separately; until then these rules are inert no-ops. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A proper alpha export makes the blend-mode approach unnecessary: one image floats on any backdrop in both themes, so the dark/light variants, the dark-only/light-only utility, and the hero-art blend rules all go. Also makes the .main-pane isolation lift (#197) moot. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Six symptom/cause/fix rows drawn from live testing of this stack: unclaimed work, in-Sprite install or key failures, the service log location, expected self-stop terminal states, idle-pause stalls with the Tasks API check, and harmless duplicate deliveries. Closes the guide's one coverage gap against the other provider guides. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…/sprites-docs into add-claude-managed-agents-guide
Four Tabs blocks (spawn, poller, run commands, start a session) with syncKey so one language pick follows the reader down the page. The TypeScript worker is condensed from a live-verified implementation with identical semantics: find-live-or-spawn dedup, tolerated create statuses, workingDir on fs writes, the task-heartbeat service chain, env file written-sourced-deleted, and a poller with lease reclaim, session filtering, per-item error handling, and graceful shutdown. It uploads the same inline Python runner, so both tabs are fully self-contained. Also: per-runtime prerequisites bullet, a note in the checkpoint Callout that a bundled Node runner (the TS SDK's EnvironmentWorker has full parity) removes the pip install and roughly halves cold start (about 10s versus 16s send-to-first-tool in our tests), and a generalized SDK-install row in Troubleshooting. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ents-guide # Conflicts: # src/styles/custom.css
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2 participants
Adds an integration guide for running Claude Managed Agents with tool execution inside Sprites, via a self-hosted environment.
The guide covers the full flow: create the self-hosted environment, generate the environment key, spawn a Sprite per session (the runner runs as a supervised service — a Sprite reaps an exec's process tree when the request closes, so a detached process wouldn't survive), run an always-on poller (or webhook) worker, and start a session. The environment key is the runner's only credential; the org API key never reaches the Sprite.
Grounded in a verified end-to-end implementation; mirrors the existing Cloudflare/Daytona/E2B/Vercel guides. Added to the Integrations sidebar group.
Verified with
pnpm build(page renders, 36 → 37 pages) andpnpm lint(clean).