TokenMix Research Lab · 2026-04-25

Claude Agent SDK Quickstart 2026: Python, TypeScript, MCP

Claude Agent SDK Quickstart 2026: Python, TypeScript, MCP

Last Updated: 2026-04-30
Author: TokenMix Research Lab
Data checked: 2026-04-30

Claude Agent SDK is the fastest way to run Claude Code-style agents from Python or TypeScript.

The SDK gives you the agent loop, built-in tools, context management, permissions, hooks, subagents, MCP, and sessions that power Claude Code. The official Agent SDK overview says it can read files, run commands, search the web, edit code, and more. The quickstart path is direct: install claude-agent-sdk or @anthropic-ai/claude-agent-sdk, set ANTHROPIC_API_KEY, choose allowed tools, and stream messages from query().

Table of Contents

Quick Verdict

Question Answer
Best first API query()
Best Python package claude-agent-sdk
Best TypeScript package @anthropic-ai/claude-agent-sdk
Best first tool set Read, Glob, Grep
When to allow Edit After you are ready to review file changes
When to allow Bash Only for known commands or sandboxed work
When to use MCP When the agent needs external systems
When to use TokenMix.ai For broader API cost/routing strategy outside the core Agent SDK path

Install Checklist

Step Python TypeScript
Install SDK pip install claude-agent-sdk npm install @anthropic-ai/claude-agent-sdk
Runtime Python 3.10+ for hosted SDK use Node.js 18+ for hosted SDK use
Auth ANTHROPIC_API_KEY ANTHROPIC_API_KEY
First API query() query()
Long session ClaudeSDKClient Session helpers / query flow
Tools allowed_tools inside ClaudeAgentOptions allowedTools inside options
Permission mode permission_mode permissionMode

Set the key:

export ANTHROPIC_API_KEY=your-api-key

Windows PowerShell:

$env:ANTHROPIC_API_KEY="your-api-key"

Python Quickstart

Start read-only. That is the safest first run.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Find all TODO comments and summarize them.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
        ),
    ):
        print(message)

asyncio.run(main())

Then allow edits only when you are ready:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Review utils.py for bugs that can crash. Fix safe issues.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        print(message)

asyncio.run(main())
Python pattern Use it when
query() One-off task, CI review, simple automation
ClaudeSDKClient Multi-turn session, interrupt support, manual connection lifecycle
ClaudeAgentOptions You need tools, permissions, MCP, hooks, session behavior
allowed_tools You want a hard allowlist

For migration details, see Claude Agent SDK 2026: Migration From Claude Code SDK Guide.

TypeScript Quickstart

TypeScript uses camelCase option names.

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

for await (const message of query({
  prompt: "Find all TODO comments and summarize them.",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
  },
})) {
  console.log(message);
}

Edit-capable example:

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

for await (const message of query({
  prompt: "Review utils.ts for crash bugs and fix safe issues.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits",
  },
})) {
  console.log(message);
}
TypeScript item Use case
query() Main streaming agent entry point
tool() Define custom tools
createSdkMcpServer() Build SDK-backed MCP tools
AgentDefinition Define subagents
Hook types Add policy and audit behavior

Built-In Tools

The SDK exposes Claude Code-style tools. Start narrow, then expand.

Tool What it does Default risk
Read Read file contents Low
Glob Find files by pattern Low
Grep Search file contents Low
Edit Modify existing files Medium
Write Create files Medium
Bash Run commands, tests, scripts, git High
WebSearch Search current web information Medium
WebFetch Fetch and parse pages Medium
AskUserQuestion Ask for structured user input Low
Agent Call subagents Medium

If an agent only needs code review, do not allow Edit or Bash. If it only needs a dependency summary, Read, Glob, and Grep are enough.

Permissions Matrix

Mode / control Best for Risk
Read-only tool allowlist First run, audit, code review Low
acceptEdits Controlled file changes Medium
Bash with explicit command policy Test and lint automation Medium to high
Broad Bash Sandboxed experiments only High
Hooks before tool use Security and policy gates Low overhead
Session resume Long tasks Context and storage management needed

Good first policy:

ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],
)

Good second policy:

ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Grep"],
    permission_mode="acceptEdits",
)

MCP Quickstart Pattern

Use MCP when the agent needs capabilities outside files and shell commands.

MCP use case Example
Browser testing Playwright MCP
Issue tracking Linear or GitHub MCP
Internal docs Search/documentation MCP
Database work Read-only database MCP
Product analytics Warehouse or API MCP

Example shape:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Open example.com and summarize the homepage.",
        options=ClaudeAgentOptions(
            mcp_servers={
                "playwright": {
                    "command": "npx",
                    "args": ["@playwright/mcp@latest"],
                }
            }
        ),
    ):
        print(message)

asyncio.run(main())

For more context on MCP and gateways, read LLM API Gateway 2026 and OpenAI-Compatible API Guide 2026.

Hooks And Audit Logs

Hooks make the SDK production-ready. Use them to inspect tool calls, block risky paths, and write audit logs.

Hook use Why it matters
Log file edits Know what changed and when
Block .env reads Reduce secret exposure
Restrict Bash Prevent destructive commands
Track usage Avoid runaway cost
Record session ID Debug long workflows
Add human approval Keep high-risk actions reviewed

Do not log raw prompts or tool inputs if they may contain secrets. Treat hook logs as production data.

Deployment Options

Path Best for Notes
Direct Anthropic API Default SDK setup Use ANTHROPIC_API_KEY
Amazon Bedrock AWS-governed environments Use documented Bedrock env flag and credentials
Google Vertex AI GCP-governed environments Use documented Vertex env flag and credentials
Microsoft Foundry Azure-governed environments Use documented Foundry env flag and credentials
TokenMix.ai Multi-provider API routing outside Agent SDK core Use for application API routing, cost comparison, fallback

Anthropic's docs also state that third-party developers should not offer claude.ai login or rate limits for products built on Agent SDK unless previously approved. Use API-key or approved enterprise/cloud authentication paths.

Cost And Routing Notes

The Agent SDK can loop, run tools, and spawn subagents. That means cost control matters.

Cost driver Control
Long prompts Use focused context and files
Broad file reads Start with Glob/Grep, then read specific files
Bash/test loops Add max-turn or command policy
Subagents Use only when decomposition is worth it
Web tools Cache repeated research
Model choice Pick the cheapest model that still succeeds

For price planning, use Claude API Cost, Claude Alternatives, and LLM API Pricing Comparison.

FAQ

What is Claude Agent SDK?

Claude Agent SDK is Anthropic's SDK for building Claude Code-style agents in Python and TypeScript. It includes the agent loop, built-in tools, sessions, permissions, hooks, MCP, and subagents.

What should I install for Python?

Install claude-agent-sdk with pip install claude-agent-sdk. Use from claude_agent_sdk import query, ClaudeAgentOptions.

What should I install for TypeScript?

Install @anthropic-ai/claude-agent-sdk with npm. Import query from @anthropic-ai/claude-agent-sdk.

Should I start with Edit and Bash enabled?

No. Start with Read, Glob, and Grep. Add Edit and Bash after you have review, tests, and policy controls.

Does the SDK support MCP?

Yes. The SDK supports MCP server configuration so agents can connect to external tools such as browsers, databases, and APIs.

Can I use my Claude Pro login in an SDK product?

Do not assume that. Anthropic says third-party developers cannot offer claude.ai login or rate limits for Agent SDK products unless previously approved.

Is Agent SDK better than Claude Code CLI?

It depends. Use Claude Code CLI for daily interactive development. Use Agent SDK when you are building an app, workflow, CI agent, or production automation.

Where does TokenMix.ai fit?

Use TokenMix.ai for model price comparison, OpenAI-compatible API routing, and fallback outside the core Agent SDK path. Keep Agent SDK authentication on documented Claude paths unless your gateway is tested for compatibility.

Related Articles

Sources