Claude Code Agent SDK Python TypeScript AI Agents

Agent SDK Quickstart: Build AI Agents in Python & TypeScript

Core Concept LearningAugust 18, 202611 min read

The Anthropic Agent SDK transforms Claude from a chat interface into a production agent that manages its own loop, handles tool calls, and persists state across sessions. In this guide, you'll go from installation to a running GitHub PR analyzer in 5 minutes—then deepen into streaming, tool design, and deployment.

Understanding how the SDK dispatches on tool responses, maintains session context, and gates tool execution is the foundation for every production agent you'll build. We'll trace one request end-to-end, show the failure points, and give you a deployment checklist that catches the top 3 gotchas before production.

Learning path

Follow these checkpoints in order — each builds on the last.

The Messages API is a stateless request-response contract. Your agent owns the loop: read response, call tools, append results, repeat.
A working agent: initialize client, set up tools, loop on messages, append tool results, exit on 'end_turn'.
Streaming makes responses feel instant but requires buffering to detect and handle tool calls. Always use get_final_message() to get the complete response.
Tool handlers wrap your business logic. Treat Claude's tool request as a contract: if the request is valid, return a result; if not, return an error—never crash.
Persistence is: serialize → store by ID → retrieve on resume. Use a database or cache, set a TTL, and checkpoint after tool calls.
Multi-tool agents use tool chaining: Claude calls tools in sequence, you append results, and Claude synthesizes. Keep tool outputs small and focused.
Production readiness: env-based config, bounded history, timeouts, error recovery, and cost tracking. Test all 5 in staging before go-live.

Messages API Fundamentals

The Agent SDK wraps the Anthropic Messages API—a simple contract: you send a list of messages, Claude sends back a single response object that may contain text, tool use, or an error. Tool use is not automatic; you read the response, call the tool in your own runtime, append the result to the message list, and send again.

The key insight: Claude does not have side effects. Your agent decides whether to accept tool outputs, retry, branch, or terminate. This is why the SDK is stateless by default and why session persistence requires you to store and restore the full message history.

Each request has a fixed context window, token limits, and token cost. Tools count toward the cost. Streaming reduces perceived latency but does not reduce actual token usage.

Quick reference

Messages are stateful—order matters. A reordered history changes Claude's behavior.
Tool use is explicit in the response; you handle the decision logic.
Token cost is fixed per request; streaming only distributes it over time.
Each session is independent; no memory shared between conversations.
Errors (invalid tools, rate limits, timeouts) are your responsibility to catch and retry.

Remember this

The Messages API is a stateless request-response contract. Your agent owns the loop: read response, call tools, append results, repeat.

Running Your First Agent in 5 Minutes

Install the SDK, create a simple agent that echoes back the user's input with tool support, and run it locally. This is the minimal working agent—a foundation for everything else.

The flow is: user input → Claude response → check for tool use → if tool, call it → append result → loop. When Claude stops emitting tool use (stop_reason is 'end_turn'), the agent conversation ends. Your agent always respects stop_reason and never overrides Claude's decision to stop.

Quick reference

Install: pip install anthropic (Python) or npm install @anthropic-ai/sdk (TypeScript).
Initialize a client with your API key from environment variables.
Create a system prompt that describes the agent's role and available tools.
Send the first user message and read the response in a loop.
Respect stop_reason='end_turn'—never force more tool calls.

Python Agent Loop

1import anthropic2import json3 4client = anthropic.Anthropic(api_key="sk-...")5model = "claude-3-5-sonnet-20241022"6 7tools = [8    {9        "name": "greet",10        "description": "Greet a user by name",11        "input_schema": {12            "type": "object",13            "properties": {14                "name": {"type": "string"}15            },16            "required": ["name"]17        }18    }19]20 21messages = [22    {23        "role": "user",24        "content": "Greet Alice and Bob"25    }26]27 28while True:29    response = client.messages.create(30        model=model,31        max_tokens=1024,32        system="You are a helpful assistant.",33        tools=tools,34        messages=messages35    )36 37    messages.append({38        "role": "assistant",39        "content": response.content40    })41 42    if response.stop_reason == "end_turn":43        break44 45    if response.stop_reason == "tool_use":46        tool_results = []47        for block in response.content:48            if block.type == "tool_use":49                result = f"Greeted {block.input['name']}"50                tool_results.append({51                    "type": "tool_result",52                    "tool_use_id": block.id,53                    "content": result54                })55 56        messages.append({57            "role": "user",58            "content": tool_results59        })60 61print("Agent finished.")

TypeScript Agent Loop

1import Anthropic from "@anthropic-ai/sdk";2 3const client = new Anthropic({4  apiKey: process.env.ANTHROPIC_API_KEY,5});6 7const model = "claude-3-5-sonnet-20241022";8 9const tools: Anthropic.Tool[] = [10  {11    name: "greet",12    description: "Greet a user by name",13    input_schema: {14      type: "object",15      properties: {16        name: { type: "string" },17      },18      required: ["name"],19    },20  },21];22 23const messages: Anthropic.Messages.MessageParam[] = [24  {25    role: "user",26    content: "Greet Alice and Bob",27  },28];29 30async function runAgent() {31  while (true) {32    const response = await client.messages.create({33      model,34      max_tokens: 1024,35      system: "You are a helpful assistant.",36      tools,37      messages,38    });39 40    messages.push({41      role: "assistant",42      content: response.content,43    });44 45    if (response.stop_reason === "end_turn") {46      break;47    }48 49    if (response.stop_reason === "tool_use") {50      const toolResults: Anthropic.Messages.ToolResultBlockParam[] = [];51      for (const block of response.content) {52        if (block.type === "tool_use") {53          const result = `Greeted ${block.input.name}`;54          toolResults.push({55            type: "tool_result",56            tool_use_id: block.id,57            content: result,58          });59        }60      }61      messages.push({62        role: "user",63        content: toolResults,64      });65    }66  }67  console.log("Agent finished.");68}69 70runAgent();

Remember this

A working agent: initialize client, set up tools, loop on messages, append tool results, exit on 'end_turn'.

Streaming Responses in Real-Time

Streaming distributes token emission over time, so the user sees Claude's response character-by-character instead of waiting for the full response. Streaming does not reduce token cost, but it feels faster and unblocks UI updates.

With streaming, tool use detection is the same: you collect events, assemble the response, check for tool_use blocks, and handle them. The difference is that text appears before you know if a tool follows. Streaming is compatible with tool calling but requires event aggregation.

Quick reference

Use stream=True in Python or stream: true in TypeScript.
Collect events in a buffer; do not assume the stream order.
Assemble the full response before checking for tool_use.
Streaming works with tool calling; tools execute after the stream ends.
Error handling: stream events can include error indicators; always validate the final response.

Non-Streaming

1response = client.messages.create(2    model=model,3    max_tokens=1024,4    messages=messages5)6print(response.content)

Streaming with Tool Support

1with client.messages.stream(2    model=model,3    max_tokens=1024,4    tools=tools,5    messages=messages6) as stream:7    full_response = stream.get_final_message()8 9messages.append({10    "role": "assistant",11    "content": full_response.content12})13 14if full_response.stop_reason == "tool_use":15    tool_results = []16    for block in full_response.content:17        if block.type == "tool_use":18            result = execute_tool(block.name, block.input)19            tool_results.append({20                "type": "tool_result",21                "tool_use_id": block.id,22                "content": result23            })24    messages.append({25        "role": "user",26        "content": tool_results27    })

Remember this

Streaming makes responses feel instant but requires buffering to detect and handle tool calls. Always use get_final_message() to get the complete response.

Adding Custom Tools to Your Agent

Tools are how agents interact with the outside world: databases, APIs, file systems, or custom business logic. You define the tool contract (name, description, input schema), implement the handler, and ensure that tool outputs are valid JSON strings.

The key mechanism: Claude generates a tool_use block with the tool name and input. You match the name, call your handler, validate the output, and append it to messages. Claude cannot retry a failed tool call; you retry in your code and send the result back.

Tool names and descriptions must be clear and specific. If Claude picks the wrong tool, improve the description. If the input schema is ambiguous, Claude may call with missing fields; add defaults or catch the error.

Quick reference

Define tools in an array with name, description, and JSON Schema for input_schema.
Tool output must be a string (JSON-serializable for structured results).
Match tool_use.name exactly; use a dict lookup for robustness.
Always wrap tool execution in try-catch; errors become tool_result content.
Tool descriptions are hints to Claude; specific descriptions = better tool selection.

Simple Tool

1tools = [2    {3        "name": "fetch_user",4        "description": "Fetch user details by ID",5        "input_schema": {6            "type": "object",7            "properties": {8                "user_id": {"type": "integer"}9            },10            "required": ["user_id"]11        }12    }13]

Tool Execution Handler

1def execute_tool(name: str, input_dict: dict) -> str:2    if name == "fetch_user":3        user_id = input_dict.get("user_id")4        try:5            user = db.query(f"SELECT * FROM users WHERE id = {user_id}")6            return json.dumps({7                "user_id": user.id,8                "name": user.name,9                "email": user.email10            })11        except Exception as e:12            return json.dumps({"error": str(e)})13    else:14        return json.dumps({"error": "Unknown tool"})

Remember this

Tool handlers wrap your business logic. Treat Claude's tool request as a contract: if the request is valid, return a result; if not, return an error—never crash.

Session Persistence Patterns

A session is the full message history from start to finish. To resume an agent, you restore the history, append a new user message, and loop again. Persistence requires storing messages in a database or cache—not just in memory.

The pattern: serialize messages to JSON, store by session ID, retrieve on resume. Sessions are independent; they don't share context. If you need cross-session memory, you maintain a separate knowledge store and include relevant facts in the system prompt or a new message.

For long-running agents, checkpoint the message history after each tool call. This lets you resume from the last tool result, not the last message. It's also a recovery point if the agent fails mid-execution.

Quick reference

Serialize messages with json.dumps() or JSON.stringify().
Store by session ID in Redis, PostgreSQL, or S3.
On resume, retrieve the full message history and continue.
Session expiration: set a TTL or archive after N days.
Checkpoints: save after tool execution for recovery.

In-Memory (Session Lost)

1messages = []2# ... run agent ...3# Process ends, messages are garbage collected.

Persistent (Resume Capable)

1import json2import redis3 4r = redis.Redis(host="localhost", port=6379)5 6def save_session(session_id: str, messages: list):7    r.set(f"session:{session_id}", json.dumps(messages))8    r.expire(f"session:{session_id}", 86400)  # 24h TTL9 10def load_session(session_id: str) -> list:11    data = r.get(f"session:{session_id}")12    return json.loads(data) if data else []13 14session_id = "user-123-session-1"15messages = load_session(session_id)16 17# ... run agent ...18save_session(session_id, messages)

Remember this

Persistence is: serialize → store by ID → retrieve on resume. Use a database or cache, set a TTL, and checkpoint after tool calls.

Real Example: GitHub PR Analyzer Agent

Put it all together: build an agent that analyzes a GitHub pull request by fetching the PR, diff, comments, and commits, then outputs a summary.

The agent has two tools: fetch_pr (gets PR metadata and diff) and fetch_comments (gets review comments). The system prompt tells Claude to analyze code quality, suggest improvements, and flag issues. After both tools return, Claude synthesizes the analysis and stops.

This example shows error handling (invalid PR ID), tool chaining (fetch PR, then comments), and how Claude naturally decides which tools to call and in what order. It's the pattern for any multi-tool agent.

Quick reference

Define clear tool descriptions so Claude knows when to use each.
Fetch data from real APIs; parse JSON responses carefully.
If a tool fails, let Claude see the error and decide next steps.
Include metadata (PR author, labels, draft status) to give Claude context.
Stop criteria: when Claude has enough info and emits 'end_turn'.

Simplified Agent Definition

1import anthropic2import requests3import json4 5client = anthropic.Anthropic()6 7tools = [8    {9        "name": "fetch_pr",10        "description": "Fetch PR details, files changed, and diff",11        "input_schema": {12            "type": "object",13            "properties": {14                "repo": {"type": "string"},15                "pr_number": {"type": "integer"}16            },17            "required": ["repo", "pr_number"]18        }19    },20    {21        "name": "fetch_comments",22        "description": "Fetch all review comments on the PR",23        "input_schema": {24            "type": "object",25            "properties": {26                "repo": {"type": "string"},27                "pr_number": {"type": "integer"}28            },29            "required": ["repo", "pr_number"]30        }31    }32]33 34def execute_tool(name: str, input_dict: dict) -> str:35    if name == "fetch_pr":36        repo = input_dict["repo"]37        pr_num = input_dict["pr_number"]38        url = f"https://api.github.com/repos/{repo}/pulls/{pr_num}"39        resp = requests.get(url, headers={"Authorization": f"token {GITHUB_TOKEN}"})40        if resp.status_code == 404:41            return json.dumps({"error": "PR not found"})42        data = resp.json()43        return json.dumps({44            "title": data["title"],45            "author": data["user"]["login"],46            "files_changed": data["changed_files"],47            "additions": data["additions"],48            "deletions": data["deletions"]49        })50    elif name == "fetch_comments":51        repo = input_dict["repo"]52        pr_num = input_dict["pr_number"]53        url = f"https://api.github.com/repos/{repo}/pulls/{pr_num}/comments"54        resp = requests.get(url, headers={"Authorization": f"token {GITHUB_TOKEN}"})55        comments = resp.json()56        return json.dumps([57            {"body": c["body"], "author": c["user"]["login"]}58            for c in comments[:5]59        ])

Agent Loop

1messages = [2    {3        "role": "user",4        "content": "Analyze this GitHub PR: anthropics-ui/claude-ui PR #42"5    }6]7 8system_prompt = """You are a code review assistant. When given a PR:91. Fetch the PR details (files, stats).102. Fetch review comments.113. Synthesize a summary: code quality, risks, and suggestions.12Keep analysis concise and actionable."""13 14while True:15    response = client.messages.create(16        model="claude-3-5-sonnet-20241022",17        max_tokens=2048,18        system=system_prompt,19        tools=tools,20        messages=messages21    )22 23    messages.append({"role": "assistant", "content": response.content})24 25    if response.stop_reason == "end_turn":26        break27 28    tool_results = []29    for block in response.content:30        if block.type == "tool_use":31            result = execute_tool(block.name, block.input)32            tool_results.append({33                "type": "tool_result",34                "tool_use_id": block.id,35                "content": result36            })37 38    messages.append({"role": "user", "content": tool_results})39 40# Extract final text response41for block in messages[-1]["content"]:42    if hasattr(block, "text"):43        print(block.text)

Remember this

Multi-tool agents use tool chaining: Claude calls tools in sequence, you append results, and Claude synthesizes. Keep tool outputs small and focused.

Deployment Checklist

Before running your agent in production, verify these 5 items. Most outages come from missing API keys, unbounded message history, and no timeout handling.

1. API key: use environment variables, never hardcode. 2. Message history size: add a hard limit (e.g., max 100 messages or 50k tokens). If the agent runs too long, truncate old messages or create a new session. 3. Tool timeout: wrap tool calls in a timeout handler (e.g., 30 seconds). If the tool hangs, return an error to Claude. 4. Error recovery: catch rate limits (429), timeouts (408), and invalid responses (500). Retry with exponential backoff or fail gracefully. 5. Cost visibility: log token usage per request. Set a hard limit (e.g., stop if cumulative cost exceeds $1).

Quick reference

Use export ANTHROPIC_API_KEY=sk-... or .env files; never commit keys.
Implement a message history limit: if len(messages) > 100, remove the oldest user-assistant pair.
Wrap tool calls: try/except with a timeout (Python: signal.alarm(), TypeScript: Promise.race()).
Retry logic: exponential backoff (2s, 4s, 8s) up to 3 retries; then fail with context.
Log usage: response.usage.input_tokens + response.usage.output_tokens per request; track cumulative cost.

Remember this

Production readiness: env-based config, bounded history, timeouts, error recovery, and cost tracking. Test all 5 in staging before go-live.

Key takeaway

You now have a working agent that calls tools, persists state, and handles errors. The next level is adding tool validation (Claude is sometimes wrong), multi-modal inputs (images in the PR), and orchestration (multiple agents, each specialized). For those patterns, read the worktrees guide and dynamic workflows guide. Start with a simple agent, measure token usage and latency in production, then add complexity only when needed.

Polo Khan

Lead Author & Systems Architect

Software engineer and distributed systems architect specializing in backend scalability, cloud-native infrastructure, databases, and AI engineering workflows. Author and maintainer of Core Concept Learning.

Human-Engineered & Fact-CheckedOriginal Visual DiagramsEditorial Standards →Send Feedback

Agent SDK Claude Code

Claude Agent SDK Guide: Building Autonomous AI Coding Agents

Jul 31, 2026 · 5 min read

When developers migrate from prototyping with raw LLM API calls to embedding autonomous agent workflows into production …

Read

Agent SDK Claude Code

Agent SDK vs Messages API, Tool Runner, Claude Code, Managed Agents

Jul 31, 2026 · 13 min read

A team building an internal tool that reviews pull requests, runs the test suite, and posts a summary comment reaches fo…

Read

Model Context Protocol AI Agents