What Is the Claude Agent SDK

What the Claude Agent SDK actually is

Claude Code is a coding agent. You type a prompt, it picks up tools, runs them in a loop, and returns an answer. Behind that behavior is what Anthropic calls an agent harness: a structured engine that manages tool calls, context, and responses until the job is done.

The Claude Agent SDK gives you programmatic access to that same engine.

Everything Claude Code can do — read files, write files, run shell commands, search the web, spin up sub-agents — you can do from code. Not just for coding tasks. For any agent you want to build: a personal assistant, a business automation, a client-facing workflow tool, a custom operator intelligence layer.

That is the core idea. Anthropic built a powerful agentic harness for Claude Code. The SDK exposes it as a software development kit so operators and developers can deploy that same power in their own products.

> The constraint has shifted. You no longer need to build an agent engine from scratch. The infrastructure is already built. The question is what you wire it to and what problem you point it at.

The query function: the core building block

Everything in the Claude Agent SDK runs through a single function called query. This is the entry point for every agent you build.

The query function takes two things: a prompt and an options object. The prompt is what you want the agent to do. The options object is where you configure behavior — which model to use, which tools to allow, what permission mode to run in, whether to carry a session ID from a previous conversation.

When you call query, it emits messages in a loop. Each message represents something the agent did: initialized the session, used a tool, generated a text block, returned a final result. You process those messages inside a for await loop and decide what to do with each one.

Here is the minimal structure:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query("What files are in this directory?", {
  model: "claude-sonnet-4-5",
  allowedTools: ["read"],
  permissionMode: "bypassPermissions",
  dangerouslyAllowBypassPermissions: true,
})) {
  if (message.type === "assistant" && message.content[0]?.type === "text") {
    console.log(message.content[0].text);
  }
}

This does the same thing you would do interactively in Claude Code, but from a TypeScript file you can deploy anywhere.

Why the loop matters. The agent does not return a single response. It streams a sequence of messages: system initialization, tool calls, tool results, thinking blocks, the final result. The loop gives you visibility into every step and lets you handle each message type differently depending on your use case.

What you can build with it

The SDK is not limited to coding agents. That framing is a side effect of Claude Code being the most visible example. Here is how the SDK actually maps to operator use cases.

Personal assistant agents. Give the agent a system prompt that describes your working context, a memory file with client information, and tools to search the web or read documents. Deploy it to a messaging service. You now have an agent you can reach from anywhere — laptop, phone, Slack — that knows your practice and can act on your behalf.

Business automation agents. Wire the agent to your internal APIs through custom tools. The agent can pull data, process it, and write structured outputs to files or databases. An agent that checks five client dashboards and compiles a Monday morning brief is straightforward to build with this pattern.

Workflow orchestration. Chain agents together using sub-agents. One agent plans the work. Another executes it. Another writes the output to a document. Each sub-agent runs in its own context window, so the parent agent stays clean and the whole workflow scales without hitting context limits.

Client-facing tools. Deploy an agent behind an HTTP endpoint or a Slack bot. Clients message it, it processes requests, it returns structured responses. The same engine that powers Claude Code — with the same tools, the same model intelligence — running in your product.

> The practical shift for operators. Building agents used to require significant engineering overhead. The SDK reduces the implementation surface to configuration: which model, which tools, which permission mode, which system prompt. The hard part is identifying the right workflow to automate, not the infrastructure to run it.

How it compares to Claude Code

Claude Code and the Claude Agent SDK share the same underlying engine. Every tool Claude Code has access to — including sub-agents, web search, file operations, task management, plan mode — is available in the SDK.

The difference is the interface.

Claude Code is interactive. You type, it responds, you review. It is designed for a human in the loop at every step.

The SDK is programmatic. You define behavior in code, deploy it, and it runs autonomously. The human in the loop is optional — or replaced by an approval callback, a permission mode, or a hook that intercepts specific tool calls.

For operators, this distinction matters. Claude Code is excellent for your own daily workflows. The SDK is what you use when you want those workflows to run without you — triggered by an event, deployed to production, serving multiple people at once.

> You could build a Claude Code clone with the SDK. Every feature Claude Code has — sessions, memory, custom commands, plan mode, sub-agents — is accessible through the SDK's tool set and configuration options. This is not a coincidence. It is the same engine, exposed differently.

What you need to get started

The SDK is a TypeScript package. You will need Node.js and either npm or Bun installed. Bun is the recommended runtime for most SDK development because it is fast and requires minimal configuration.

Install the package:

bun add @anthropic-ai/claude-agent-sdk

For local development, you can use your Claude.ai subscription. For deployed agents running in cloud environments, you will need an Anthropic API key from console.anthropic.com. This is the main setup difference between interactive development and production deployment.

The rest — models, tools, permission modes, hooks, sub-agents, memory — is all configuration. The foundation is the same query function regardless of what you build.

---

Author: FractionalSkill