Claude Agent SDK Guides

What Is the Claude Agent SDK

The same engine that powers Claude Code, accessible from code. Build personal assistant agents, business automations, and client-facing tools using the query function at the core of every Claude agent.

Sub-Agents in the Claude Agent SDK

How to delegate tasks to independent AI workers that run in parallel with their own context windows. Build planner-writer agent chains and multi-client research workflows that finish in a fraction of the time.

Tool Hooks in the Claude Agent SDK

Intercept tool calls before and after they execute. Block sensitive file edits, build audit logs, and add guardrails that hold up in production without limiting what the agent can do for legitimate work.

Built-in Tools in the Claude Agent SDK

The complete built-in tool set: file operations, bash, web search, sub-agents, task management, and plan mode. How to allow-list, block, and control which tools your agent can access.

Lifecycle Hooks in the Claude Agent SDK

Hook into session start, user prompt submit, and sub-agent stop events. Build a memory injection system that loads context automatically at the start of every session.

Setting Up and Installing the Claude Agent SDK

Initialize a Bun project, install the SDK, and write your first working agent in under 10 minutes. Covers streaming input mode, the query loop, and what each option actually does.

Building Custom Tools for the Claude Agent SDK

Create tools that call external APIs, define their input schemas with Zod, package them into in-process MCP servers, and give your agent capabilities no built-in tool provides.

Permission Modes in the Claude Agent SDK

Five modes that control how the agent handles tool calls: default, acceptEdits, bypassPermissions, plan, and dontAsk. When to use each and how tool lists interact with permission modes.

Deploying a Claude Agent SDK Agent to Railway

Package your Slack agent in Docker, configure persistent volumes so sessions survive redeploys, push to GitHub, and get your agent running 24/7 in the cloud with Railway.

Project Setup and the Agent Chat Function

Build the foundational agentChat function that every interface layer — Slack, terminal, API — calls the same way. Covers project structure, streaming input mode, and session ID handling.

The Query Function: Two Modes Explained

Single message mode vs streaming input mode. Why the async generator unlocks hooks, session resumption, and multi-turn conversations that plain string prompts cannot.

System Prompts in the Claude Agent SDK

Three ways to write system prompts: plain string, the Claude Code preset, and the preset with a custom append. How the invisible base prompt works and what your prompt actually controls.

What Are Hooks in the Claude Agent SDK

Hooks run functions at specific points in agent execution. Understand tool hooks vs lifecycle hooks, how matchers work, and where hooks fit in the tool evaluation order.

Multi-turn Conversations and the Interactive Agent

Build an interactive terminal agent with a conversation loop, session memory across turns, and a thinking indicator. The session ID pattern that makes follow-up questions work.

Model Selection in the Claude Agent SDK

Haiku for development, Sonnet for production, Opus for maximum capability. How to set a fallback model and why switching models mid-session via hooks is possible.

Session Management in the Claude Agent SDK

Resume sessions, fork conversations from specific messages, and list session history. The session ID patterns that power multi-turn agents and persistent conversation tools.

Settings Sources in the Claude Agent SDK

How to load project CLAUDE.md files, skills, and settings.json hooks into your agent. The three source layers and why most SDK agents only need the project source.

The canUseTool Callback

Programmatic control over every tool call. Allow, deny, modify inputs, and log tool usage with fine-grained precision that permission modes alone cannot provide.

Structured Outputs in the Claude Agent SDK

Get typed, schema-validated objects back instead of text. Define a Zod schema, configure outputFormat, and build data extraction pipelines that feed directly into your workflows.

Connecting the Claude Agent SDK to Slack

Create a Slack app, configure bot scopes and socket mode, install Slack Bolt, and wire up channel mentions and DMs. The full integration from app creation to first response.

Connecting External MCP Servers to the Agent SDK

Give your agent a browser, a Notion workspace, or a GitHub integration by connecting external MCP servers. Faster than building custom tools for integrations that already exist.

Polishing the Slack Experience

Strip mention tags, convert standard markdown to Slack formatting, and add a thinking indicator. Three improvements that turn a working integration into one people actually want to use.

Safety Limits: maxTurns and maxBudgetUsd

Cap how many turns an agent can run and how much it can spend per session. Two options that prevent infinite loops and runaway costs in any deployed agent.

Message Types in the Claude Agent SDK

The system, assistant, and result message types that every agent run produces. What each contains, when it fires, and how to use them for session tracking, cost logging, and error detection.

Session Persistence with SQLite and Bun

Map Slack threads to Agent SDK session IDs using Bun's native SQLite. Build a session store with get, set, and delete methods that gives your Slack agent conversation memory.

Skills in the Claude Agent SDK

Give your agent reusable prompt modules it loads on demand. Build a meeting notes skill, enable it with the skill tool and settingSources, and create a library that scales across every agent you deploy.

Production Hardening Your Slack Agent

Add thread context injection, thread locking for concurrent messages, and spending caps. The three steps that separate a demo deployment from one your team can rely on.

Session Transcripts for Debugging Agent Workflows

Find, read, and analyze the JSONL transcript files the SDK writes for every session. How to use a coding agent to parse transcripts and diagnose unexpected behavior in production agents.