The core building blocks that turn a prompt into an autonomous, tool‑using loop — and how Python and TypeScript expose them.
Claude Docs: Agent SDK overview.
Documentation reviewed: .
An agent query uses the same loop as Claude Code: read context, decide, act, observe — repeat until Claude finishes or a limit stops the run.
Claude Docs: Agent loop and message types. Diagram uses Python message type names.
Hooks sit inside the loop, not beside it — intercepting a call before it runs, or rewriting its result after, without touching the tool's own code.
Claude Docs: Hook decisions and output fields.
A skill packages instructions for a kind of task. Claude loads them when it invokes the skill; you can also request a skill by name.
Claude sees short descriptions of the skills available to this session. Full instructions load when a skill is invoked.
When a request matches, Claude invokes the Skill tool and loads the relevant instructions into the active context — e.g. a docx skill only when a Word file is due.
Several skills can combine in one task — a research skill to gather facts, then a document skill to format the result.
Claude Docs: Configure and invoke skills.
Read these checks in order. A call can be approved, blocked, or sent for a decision before it reaches the last step.
Can block, defer or edit a call. A hook’s approval still goes through deny and ask rules.
A matching deny rule blocks the call. The approval callback is skipped.
A match goes to the callback for a decision, or is denied in dontAsk mode.
May approve the call or apply extra checks. For example, acceptEdits approves eligible file edits.
An eligible match approves the call. Calls needing no approval also finish here.
canUseTool / can_use_tool decides remaining calls. In dontAsk, they are denied instead.
Claude Docs: Permission order and exceptions. Some protected actions always need extra checks.
Wrap your own function so Claude can call it like any built‑in — no separate process to run or manage.
Claude Docs: Custom tools in Python and TypeScript. Tool handlers run inside your application process.
A subagent works in its own context. The parent receives its returned result rather than the full working transcript, while the application can optionally observe intermediate activity.
Claude Docs: Subagent context and returned reports.
A session_id identifies a conversation. Its history is saved locally by default, so a later run can pick up where it left off. You can also mirror it to external storage.
Claude Docs: Continue, resume and fork sessions.
Connect local or remote MCP servers through stdio, SSE, or Streamable HTTP. Tool Search loads tool definitions when needed and is on by default where supported.
Claude Docs: MCP transports · Tool Search defaults and supported configurations.
Limit tool-use turns, set an estimated spending threshold, and choose how much reasoning Claude applies to each response.
Stops with error_max_turns. Keep earlier streamed messages: this error has no final result answer.
Stops when estimated spend reaches the threshold, checked after each response. That response and running subagents can push the total higher.
low to max — trades speed and token cost for reasoning depth. Available levels depend on the model.
Claude Docs: Limits and effort · Cost estimates. Option names here are TypeScript.
When context fills up, the runtime summarizes older conversation history and keeps recent exchanges so Claude can continue. Some older details can be lost.
Claude Docs: Compaction and persistent instructions.
Broadly the same agent runtime, exposed through different language idioms — with occasional differences in API shape and release timing.
ClaudeSDKClient auto‑tracks across callssnake_case, e.g. max_turns@tool decoratorquery() with continuation or resume optionscamelCase, e.g. maxTurnstool() helperClaude Docs: Python reference · TypeScript reference.
Every module exists to shape one thing: what happens inside the loop.
The pieces change what the loop can do — the loop is still the thing.
Claude Docs: Official Agent SDK overview. Each slide links to the details behind its explanation.