Claude Agent SDK [Full Workshop] — Thariq Shihipar, Anthropic

The progression Shihipar describes begins with individual language-model features, moves through structured workflows, and arrives at agents that build their own context and choose their own trajectories. A workflow can accept tightly defined inputs and produce tightly defined outputs, while an agent can interpret a natural-language request and decide which intermediate actions are necessary. The distinction is not absolute: an issue-triage workflow may still need an agent to clone a repository, start a Docker container, investigate a failure, and return a structured result. 1:35

The Claude Agent SDK is built on top of Claude Code because teams building agents repeatedly needed the same surrounding infrastructure. That infrastructure includes the model, a tool-running loop, agent and tool prompts, filesystem access, skills, sub-agents, web search, compacting, hooks, and memory. Shihipar presents the SDK as a packaged harness that absorbs these recurring implementation concerns so application developers can concentrate on domain-specific search, actions, and verification. 3:56

The architectural commitment is substantial: this style of agent needs Bash and a filesystem, so it runs locally or in a container rather than behaving like an ordinary stateless model request. Shihipar acknowledges the resulting sandbox, hosting, and performance overhead. His argument is that these inconveniences purchase a more capable execution environment, not that every deployment becomes simpler or that every problem requires the SDK. 8:36

The central claim is that Bash is a general-purpose composition layer. Instead of defining a separate model-facing tool for every search, lint, execution, or transformation task, an agent can discover existing commands, invoke package-manager scripts, save intermediate results, generate reusable scripts, and operate software such as FFmpeg or LibreOffice. The filesystem makes those intermediate artifacts inspectable and reusable, turning context engineering into a question of tools, files, scripts, and state rather than prompt text alone. 5:06

A ride-sharing expense example makes the mechanism concrete. An email search alone might return a large collection of messages that the model must interpret directly; with Bash, the agent can save results, search for prices, add them, retain line numbers, and inspect whether each extracted value actually corresponds to a relevant charge. The same pattern extends to joining inbox and contact information or using FFmpeg and JQ to process a recorded meeting. The improvement comes from external computation, composability, and the ability to check intermediate work. 17:08

Shihipar distinguishes three execution options. Structured tools are reliable, controlled, and suitable for atomic or irreversible actions such as writing a file with approval or sending an email, but large tool inventories consume context and compose poorly. Bash lowers upfront context requirements and supports reusable commands, but discovering a command through its help interface introduces latency. Code generation supports dynamic scripts, API composition, data analysis, and flexible logic, but execution may require linting or compilation and is generally slower. Choosing among them is a system-design decision, not a universal rule. 25:12

Shihipar proposes a practical three-part loop: gather context, take action, and verify the work. For a coding agent, gathering context might mean searching a repository; for an email agent, it means locating relevant messages. The model should generally discover useful information through the interfaces it has been given instead of receiving a static bundle that developers assume contains everything it needs. Planning can be inserted between context gathering and action, but it introduces additional latency and is not necessary for every task. 21:41

The quality of the verification surface strongly influences whether a problem is suitable for an agent. Code offers relatively strong checks because it can be linted, compiled, and executed, while research is harder to verify and may depend partly on source citations. Shihipar recommends deterministic checks wherever possible, including rejecting a file write when the agent has not first read that file. Verification should also appear throughout execution, not merely at the end: limits, validation errors, and intermediate checks can give the model actionable feedback and redirect its next attempt. 23:03

Hooks provide another way to introduce deterministic behavior or update context during the agent loop. A hook might validate a spreadsheet after an operation, insert changes a user made while the agent was working, or reject a final response that failed to consult the required data or generate a required script. These mechanisms are particularly useful when the model appears to know an answer already and might otherwise respond from existing knowledge rather than inspect the application’s authoritative inputs. 1:47:05

The framework should remain a guide rather than a rigid mandatory sequence. Shihipar describes expressing the desired behavior in a system prompt while allowing the agent to decide which steps actually apply. A read-only spreadsheet question, for example, does not need the same write-oriented verification as a modification. His recurring operational advice is to read agent transcripts repeatedly, identify why the model chose a particular path, and adjust prompts, interfaces, checks, or available tools accordingly. 21:41

A spreadsheet illustrates why context gathering requires more than attaching a generic search tool. Finding revenue for a particular year is a multidimensional retrieval problem: headers alone do not identify the correct intersection of metric and year. Possible interfaces include familiar spreadsheet ranges, SQL queries, XML-oriented access, or command-line processing. Shihipar highlights translating a CSV-like source into an interface the model already understands, such as SQLite and SQL, as an example of making an unfamiliar business problem more compatible with existing model capabilities. 53:43

Search quality can also improve through preprocessing and annotation. An application might transform its source into a queryable representation or have another agent add descriptions and metadata before the main agent searches it. The best interface is domain-dependent, so Shihipar recommends trying multiple approaches against representative tests rather than assuming the first retrieval design is sufficient. Read and write interfaces can often share the same underlying abstractions, whether those abstractions are spreadsheet ranges, SQL, or XML. 57:25

Large datasets expose the limits of simply expanding the prompt. Shihipar explicitly notes that accuracy becomes harder to maintain as spreadsheets or codebases grow and advises against loading an entire spreadsheet into context. Instead, an agent can inspect a small initial view, search for relevant terms, navigate between sheets, and maintain a scratchpad or notes. Long tool outputs can likewise be written to files while the tool returns only the resulting path, allowing later search, processing, and rechecking without flooding the conversation. 29:45

Sub-agents offer another context-management strategy: delegate an extensive search or independent sheet summaries to separate workers and return only the useful result to the main agent. Shihipar also describes clearing coding-session context when the relevant state can be reconstructed from files and a git diff, while acknowledging that designing equivalent resets or summaries for less technical spreadsheet users is harder. For very large codebases, he identifies tradeoffs in bespoke semantic search and points instead to useful project instructions, an appropriate starting directory, hooks, and verification. 1:06:13

Granting an agent Bash and filesystem access creates a genuine security problem, so Shihipar describes a layered defense rather than reliance on a single safeguard. The layers include model alignment, harness-level prompting and permissions, analysis of Bash commands through an AST parser, and sandbox restrictions on network and filesystem operations. Isolating an agent from personal machines or environments containing production secrets adds another boundary. The stated goal is to reduce what a compromised or misdirected agent can actually access or exfiltrate. 12:40

Database access illustrates the tradeoff between strict control and flexible exploration. A narrowly defined tool can expose only approved inputs and outputs when sensitive information must remain hidden, but that structure also limits dynamic querying. Bash or generated code can support iterative SQL development because the model can run a query, inspect an error, and revise it, provided access is guarded appropriately. Shihipar suggests scoped or temporary API keys, backend enforcement, and, where appropriate, proxies that insert credentials without exposing them directly to the agent. 44:13

Safety also depends on whether an action is reversible. Code is comparatively forgiving because version history and checkpoints can restore earlier states, whereas a mistaken interaction in a shopping flow can leave the interface in a more complicated state that requires additional corrective actions. For a spreadsheet or similar product, Shihipar recommends considering checkpoints and restoration mechanisms so users, and potentially agents, can recover from destructive mistakes. He also notes that coordinating parallel Bash-based sub-agents introduces practical concerns such as race conditions. 1:10:36

Independent verification can supplement these controls, but Shihipar ranks deterministic checks ahead of model-based review whenever the rules are clear. When a separate reviewing agent is useful, he recommends giving it a fresh context rather than copying the original agent’s full history, reducing the chance that the verifier inherits the assumptions or errors it is supposed to challenge. This preserves the distinction between a hard enforcement boundary and a probabilistic second opinion. 1:07:52

The workshop’s prototyping approach starts with Claude Code, a real API, a few helper scripts or libraries, and project-level instructions. Shihipar argues that an effective agent should remain relatively small even though finding the right domain abstraction may be difficult. Rather than first constructing an elaborate orchestration layer, developers can observe how the model searches, invokes APIs, writes scripts, and fails, then concentrate their effort on domain-specific retrieval, guardrails, and verification. 1:23:33

The demonstration uses the Poke API and a generated TypeScript library that exposes operations for Pokémon, species, abilities, moves, and related resources. Shihipar contrasts this filesystem-and-code-generation approach with a separate implementation using the regular messages or completion API and individually defined tools. He logs tool calls to inspect execution and uses bun while prototyping because it lets him work with TypeScript without separately managing a TypeScript-to-JavaScript compilation step. 1:25:40

The live example also demonstrates the limitations of an unpolished agent. When asked about generation-two water Pokémon, the model initially appears to rely partly on existing knowledge and does not consistently use the prebuilt API, prompting Shihipar to identify the project instructions as an area for improvement. A later request about building around Venusaur uses a text dataset associated with Smogon; the agent searches references to Venusaur, identifies related Pokémon, teammates, and counters, and generates a script to analyze the material. The lesson is not that the initial prototype is flawless, but that observing its actual behavior reveals where better instructions, preprocessing, or verification are needed. 1:34:25

To move from a successful prototype toward an application, Shihipar describes retaining the useful instructions and helper scripts while adding a relatively small SDK entry point. Deployment can either remain local or run inside a hosted sandbox; a customized user interface can also be served from a development server inside that sandbox and refreshed as the agent edits code. He leaves several questions explicitly open, including cross-agent reuse, per-user container architecture, and the best long-term organization of skills. He also cautions that agents can be expensive and that monetization and expected usage patterns should influence product design from the beginning. 32:54