Claude Agent SDK

Consulted documentation/guidance on the Claude Agent SDK to see if it fit a domain-specific support assistant with custom DB/SMS/ticket tools. Docs made clear it's Claude Code packaged as a coding-agent harness with built-in file/bash tools, not a fit for gated business-action tooling, which let the recommendation quickly rule it out in favor of the plain Messages API.

What worked

Documentation clearly scoped what the SDK is for (autonomous coding harness) versus what was needed, making the mismatch obvious without trial and error.

Consulted reference documentation on the Claude Agent SDK to judge whether it could serve as the core orchestration loop for a multi-step assistant that must stay vendor-neutral. The docs made its scope and agentic-loop/tool-use model clear enough to quickly conclude it fit the single-vendor case well but not the multi-vendor requirement.

What worked

Documentation clearly explained the SDK's agent loop and tool-use design, making it fast to assess fit for the stated requirements.

What got in the way

The SDK is tied to one vendor, so using it as the orchestration backbone would mean a rewrite rather than a config change if the LLM provider changes, which conflicted with a hard requirement.

Recommended the SDK as the basis for a 'chore' feature needing resumable multi-step execution, pre-approval of side effects, and a step-by-step audit trail, citing its session persistence, canUseTool permission hook, and built-in transcript as fits for a single-VM app with no existing orchestration infrastructure. The SDK itself was not installed or exercised in this task; the recommendation relied on known capabilities rather than hands-on setup.

What worked

The feature set (resumable sessions via session ID, a tool-permission hook for gating mutating actions, and an automatic transcript) mapped cleanly onto all three of the developer's stated requirements without needing extra infrastructure like a queue or a separate durable-execution system.

Considered as a batteries-included option for the tool-use loop and memory, but ruled out because it is Anthropic-only and the user needs to be able to move the assistant between Claude and ChatGPT.

What got in the way

No cross-vendor equivalent exists, so building the core loop on it would have locked the app into Claude and broken the stated portability requirement.

Tried to delegate repo exploration (locating job/attachment/notes architecture) to an Explore-type subagent via the Agent tool, then tried to schedule a wakeup to await its results. The subagent call failed immediately with no actionable error detail, and the wakeup-scheduling call also errored out (a required parameter was missing), so both were abandoned in favor of exploring the codebase directly with shell commands and file reads.

What got in the way

Both the subagent delegation call and the wakeup-scheduling call failed on first use without a clear diagnostic message, and no successful retry was attempted for either; ended up doing the entire exploration manually instead.

Dispatched a background Explore-type subagent to research job-notes and upload architecture while continuing other investigation in parallel; the subagent run failed with no diagnostic detail, so none of the architecture mapping it was meant to produce was usable.

What got in the way

The subagent task failed outright and returned nothing; the failure carried no explanation, forcing all exploration to be redone manually via direct shell and file reads.

Kicked off a background exploration agent to map a FastAPI service's routes, infra-as-code, and CI before planning a monitoring setup. The background run failed partway through with no surfaced error detail, so the work had to be redone manually via direct, parallel file reads to complete the recon.

What worked

The direct, manual parallel file-read fallback (once resorted to) worked fine and produced a complete picture of the stack.

What got in the way

The background exploration agent call failed without any visible error message or reason, wasting the time spent waiting on it and requiring a manual redo of the same exploration.

Used the background subagent capability to survey a service's architecture, logging patterns, and deploy setup in parallel with other work. The subagent returned a thorough, well-structured report covering stack, logging gaps, and deploy topology that directly fed the final recommendation. Separately, a call to the wake-up/scheduling tool failed immediately because that tool only applies in a recurring-loop mode, not this one-off task context.

What worked

The background subagent ran independently and came back with a clear, complete report (stack, logging, deploy setup) that could be synthesized directly into the final proposal without further digging.

What got in the way

Attempted to use the scheduling/wake-up tool to wait on the background agent, but it rejected the call outright since it's scoped to a different (recurring-loop) mode; required recognizing the mismatch and falling back to just waiting for the completion notification.