Can a Fresh Worker Resume Your Claude Agent?
Install the Claude Agent SDK in the Python worker image, then qualify hosted resume with paired warm and fresh runs of a read-only fixture. Record the recovered marker, completed tool calls, and time to recovery.
Make the Python image prove it can run the harness
Build the worker with a pinned `claude-agent-sdk` version and Python 3.10 or newer, then run a smoke query under the identity that will handle hosted requests. The Python package bundles the Claude Code CLI, so importing the package during an image build checks only part of startup. Give the worker a tiny synthetic text file in its job directory and ask the agent to read it and return the marker inside. Record elapsed time to the first harness event, the completed read count, and the returned marker. A process that imports successfully but produces no harness event fails the startup gate. Keep the same image, working directory layout, and fixture on both workers so drift in the release image stays visible.
GitHub - anthropics/claude-agent-sdk-python · GitHubTest transcript portability with a marker known only to the session
Start a session that reads a synthetic marker, then record the session identifier after the turn finishes. Resume twice from equivalent seeded sessions. Keep one run on the original worker and send the other to a fresh worker with empty local session state and a matching working directory. Ask for the marker without supplying it again. Count additional completed reads so a worker that reconstructs the answer by rereading the fixture is distinguishable from one that recovered the transcript. The session storage excerpt describes local JSONL and a SessionStore adapter. Verify the adapter interface for your installed SDK language and version before wiring it into the worker. A warm pass paired with a fresh failure gives you a focused test for transcript availability and lookup identity.
Persist sessions to external storage - Claude Code DocsVerify startup in the worker environment
The Python package requires Python 3.10 or later and bundles the Claude Code CLI. In a clean environment matching the hosted worker, run pip install claude-agent-sdk. Supply the credentials for your chosen Claude access path through the worker's secret configuration. Run a small SDK query in a temporary directory using a synthetic input and no external tool requirements.
Record whether installation succeeded, the SDK launched its bundled CLI, and the query returned a result. If package installation succeeds but the query fails before reaching Claude, check startup and credential errors separately. Repeat this smoke test whenever you change the worker image or the SDK version.
GitHub - anthropics/claude-agent-sdk-python · GitHubTest the boundary around a tool call
The SDK provides permission modes and rules for automatic decisions and a canUseTool callback for calls that still need approval. Decide which operations your task needs before adding tools. For a file summarizer, grant reads within the fixture directory and configure a deny rule for edits there. Give the worker access only to the files it needs for the test.
In an illustrative fixture, create a notes file containing three agenda items. Ask for a summary, then run a second request that attempts to edit the notes. Inspect the tool decision and compare the file before and after the second request. The test passes when the summary covers all three items and the attempted edit is denied with the original file intact.
Configure permissions - Claude Code DocsResume on a fresh worker
The SDK writes session transcripts to local JSONL files by default. If a later turn can land on a different worker, configure a SessionStore that mirrors the transcript to a shared backend and start the replacement worker from a matching working directory. Make any task files it needs available there as well.
For an illustrative test, give worker A a synthetic report draft and ask it to remember a unique review tag. Save the session ID, stop worker A, then resume that ID on worker B and ask for the tag without supplying it again. If context is missing, check that the store loaded the transcript for the requested session and that the working directory matches. Verify the report file separately.
Persist sessions to external storage - Claude Code DocsCheck the estimate against provider usage
The SDK computes its reported cost locally, so use that value as a run diagnostic and reconcile spend against provider billing. In illustrative arithmetic using hypothetical rates of $2 per million input tokens and $8 per million output tokens, a run with 12,000 input and 2,000 output tokens costs $0.024 plus $0.016, or $0.040 before any other charges.
For a production estimate, verify the published rates for the exact model and applicable cache, residency, or tool charges. Save the run's model, token categories, and SDK version alongside its estimate. If an isolated test batch differs from the corresponding billed usage, check whether the local price table reflects the model and billing rules that were actually applied.
Track cost and usage - Claude Code Docs