Omniscio

OmniscioGuidesClaude Agent SDK

Claude Agent SDK: Claude Code's agent, in your app

Everything Claude Code does in a terminal — read files, run commands, edit code, recover from a failed step — is a loop over four kinds of event. The Agent SDK hands you that loop instead of the interface around it.

This page covers which of Anthropic's four ways to build an agent you want, the install, a first agent you can run in a few minutes, what carries over from your .claude/ folder, and the authentication rule that stops most first attempts.

Last checked against Anthropic's Claude Code documentation on November 18, 2026. By the Omniscio team. Updated .

What the SDK is

An agent is an application that completes a task by planning its own steps and calling tools that read files, run commands or edit code. The Agent SDK gives you the same tools, agent loop and context management that power Claude Code, programmable in Python and TypeScript.

What you get is not a thin wrapper over a chat endpoint. Anthropic lists the Claude Code capabilities available inside the SDK: built-in tools, hooks, subagents, MCP, permissions, sessions, skills and commands and memory loaded from .claude/ and ~/.claude/, and plugins loaded by local path.

The practical consequence: Claude executes tools directly instead of asking you to implement them.

Sources: the introduction and "Capabilities" in the Agent SDK overview, read November 18, 2026.

SDK, CLI, Client SDK or Managed Agents

Anthropic names four products that all put Claude to work, and they differ in who runs the agent:

Pick the row that matches how you want to build and run it.
You want toUse
Embed Claude Code's agent in your own Python or TypeScript application, in a process you operateAgent SDK
Do interactive development or one-off tasks from a terminalClaude Code CLI
Call the Claude API directly and write the tool loop yourselfClient SDK
Have Anthropic host the agent, configured through the Claude APIManaged Agents

The Agent SDK's own description of its row is the clearest test: a library that runs the Claude Code binary, with Claude Code's capabilities. If you find yourself writing the tool loop, you wanted the Client SDK. If you never want to think about the process, you wanted Managed Agents.

Source: "Compare the Agent SDK to other Claude tools" in the Agent SDK overview, read November 18, 2026.

Install it

You need Node.js 18.14 or later, or Python 3.10 or later, and an Anthropic account.

# TypeScript, new project
npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

# Python, with uv
uv init
uv add claude-agent-sdk

Two install details are worth knowing because they fail in ways that look like a code bug. The SDKs bundle a native Claude Code binary, so most installs need no separate Claude Code. The exceptions: a pip install that falls back to the Python source distribution, as on ARM64 Windows, bundles no binary and finds Claude Code on your PATH instead; and the TypeScript SDK ships its binary through npm optional dependencies, so an install that skips them, such as npm ci --omit=optional, gets none. The package is @anthropic-ai/claude-agent-sdk for TypeScript and claude-agent-sdk for Python.

Sources: "Prerequisites" and "Install the SDK" in the Agent SDK quickstart, read November 18, 2026.

The key, and the rule about sign-in

Get an API key from the Claude Console and set it in the shell that runs your agent:

export ANTHROPIC_API_KEY=your-api-key        # macOS, Linux
$env:ANTHROPIC_API_KEY = "your-api-key"      # Windows PowerShell

The SDK reads the key from the environment of the process that runs the agent. It does not load .env files, so if you keep the key in one, load it yourself before calling the SDK. A Not logged in or Invalid API key error usually means the variable is set in a different shell.

Here is the rule that catches product builders rather than script writers: unless previously approved, Anthropic does not allow third-party developers to offer claude.ai login or rate limits for their products, including agents built on the SDK. Use the API key: the restriction is on offering claude.ai login or rate limits inside your product, not on the SDK itself.

Sources: "Set your API key", its note, and the authentication note in the Agent SDK quickstart, read November 18, 2026.

A first agent

Anthropic's quickstart builds an agent that finds and fixes bugs in a file. The whole program is one call into an iterator:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")

asyncio.run(main())

Three parts carry all the meaning. query creates the agentic loop and returns an iterator, so you stream messages as Claude works. prompt is what you want done; Claude chooses the tools. options is the configuration — here allowedTools pre-approves Read, Edit and Glob, and permissionMode: "acceptEdits" auto-approves file changes.

Each iteration yields one message: Claude's reasoning, a tool call, a tool result, or the outcome. The SDK handles orchestration, tool execution, context management and retries, and the loop ends when Claude finishes or hits an error. Run it with npx tsx agent.ts in TypeScript, or uv run agent.py in Python.

The same agent in TypeScript uses camelCase options and for await:

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

for await (const message of query({
  prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits",
  },
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text)
      else if ("name" in block) console.log(`Tool: ${block.name}`)
    }
  } else if (message.type === "result") {
    console.log(`Done: ${message.subtype}`)
  }
}

If your project is CommonJS rather than ES modules, name the file agent.mts: tsx then treats it as an ES module, so top-level await works without converting the whole project.

Sources: "Build an agent that finds and fixes bugs" and "Run your agent" in the Agent SDK quickstart, read November 18, 2026.

Tools and permissions

The two options in that example are the two you will change first, and they are not the same kind of thing.

  • Allowed tools decide which tools the agent may use without asking. Anthropic's example names Read, Edit and Glob; a tool left out is not pre-approved.
  • Permission mode decides how approvals work in general. acceptEdits auto-approves file edits, and the SDK reference lists the other modes.

Everything else in the options object follows Claude Code: systemPrompt, mcpServers, and the rest of the agent-sdk reference's option list. For a headless job that should touch nothing, start by granting nothing and adding one tool at a time.

Sources: "The three parts of the code" and "Options" in the Agent SDK quickstart, read November 18, 2026.

What carries over from Claude Code

This is the reason to choose the Agent SDK over assembling your own tool loop: the project conventions you already wrote keep working.

Skills, commands and memory load automatically from the project's .claude/ directory and from ~/.claude/, exactly as they do in Claude Code. Plugins package skills, agents, hooks and MCP servers, and load by local path. Subagents, hooks, MCP servers and permissions are all configuration you have already met in the CLI.

Sessions carry context across exchanges and can be resumed or forked later, which is the same idea as --resume in the terminal.

Sources: "Capabilities" in the Agent SDK overview, read November 18, 2026.

Other languages, and other clouds

For a language other than Python or TypeScript, run the CLI as a subprocess with the -p flag and --output-format json. Anthropic calls that the same agent loop without the library, and it is what headless mode in Claude Code is.

For inference through your own cloud account, set one environment variable and configure that provider's credentials: CLAUDE_CODE_USE_BEDROCK=1 for Amazon Bedrock, CLAUDE_CODE_USE_ANTHROPIC_AWS=1 plus ANTHROPIC_AWS_WORKSPACE_ID for Claude Platform on AWS, CLAUDE_CODE_USE_VERTEX=1 for Google Cloud's Agent Platform, or CLAUDE_CODE_USE_FOUNDRY=1 for Microsoft Foundry.

One last distinction worth holding: the SDK runs in a process you operate, on your machine or your server. Hosting, sandboxes and sessions in Anthropic's cloud are Managed Agents, a different product with its own SDK and REST API.

Sources: the introduction and "Set your API key" in the Agent SDK overview and the quickstart, read November 18, 2026.

Where these answers come from

Common questions

Is the Agent SDK the same as calling the Claude API?

No. The SDK runs Claude Code's agent loop for you — tools, permissions, sessions, hooks. Calling the Claude API directly, or through the Client SDK, means writing that loop yourself or letting the Client SDK's beta tool runner drive it.

Do I need Claude Code installed separately?

Usually not: both SDKs bundle a native binary. The exceptions are a Python source install with no platform wheel, such as ARM64 Windows, and a TypeScript install that skipped optional dependencies.

Can my app let people sign in with claude.ai?

Not unless Anthropic has previously approved it. Third-party products may not offer claude.ai login or rate limits, so agents built on the SDK use API keys.

Can I use a language other than TypeScript or Python?

Yes — run the CLI as a subprocess with -p and --output-format json. Same agent loop, no library.