Anthropic Python SDK Reference
Overview
The Anthropic Python SDK (anthropic) provides access to the Claude API from Python applications. It is the official SDK maintained by Anthropic, built on httpx with full type annotations, async support, streaming, and automatic retries.
- Package:
anthropic on PyPI - Version: 0.84.0 (as of last fetch)
- Python: 3.9+
- License: MIT
- Repo: https://github.com/anthropics/anthropic-sdk-python
- Docs: https://platform.claude.com/docs/en/api/sdks/python
Dependencies
httpx (>=0.25.0, <1)pydantic (>=1.9.0, <3)typing-extensions (>=4.10, <5)anyio (>=3.5.0, <5)jiter (>=0.4.0, <1)
Installation
bash
# Standard install
pip install anthropic
# With MCP helpers (Python 3.10+)
pip install anthropic[mcp]
# With Bedrock support
pip install anthropic[bedrock]
# With Vertex AI support
pip install anthropic[vertex]
Client Initialization
Sync Client
python
import anthropic
# Uses ANTHROPIC_API_KEY env var by default
client = anthropic.Anthropic()
# Explicit API key
client = anthropic.Anthropic(api_key="sk-ant-...")
# With custom settings
client = anthropic.Anthropic(
api_key="sk-ant-...",
base_url="https://custom-endpoint.example.com", # or ANTHROPIC_BASE_URL env var
timeout=60.0, # request timeout in seconds (default: 600)
max_retries=3, # retry count (default: 2)
default_headers={"X-Custom": "value"},
default_query={"param": "value"},
)
Async Client
python
import anthropic
client = anthropic.AsyncAnthropic()
# Same constructor parameters as sync client
Cloud Provider Clients
python
# AWS Bedrock
from anthropic import AnthropicBedrock
client = AnthropicBedrock()
# Google Vertex AI
from anthropic import AnthropicVertex
client = AnthropicVertex()
Environment Variables
| Variable | Purpose | |
|---|
ANTHROPIC_API_KEY | API key (required unless passed explicitly) | |
ANTHROPIC_BASE_URL | Custom API base URL | |
ANTHROPIC_LOG | Set to debug for verbose logging | |
Messages API (Core)
Basic Message
python
message = client.messages.create(
model="claude-opus-4-6",
max_tokens=1024,
messages=[
{"role": "user", "content": "Hello, Claude"}
],
)
print(message.content) # list of ContentBlock
print(message.content[0].text) # first text block
Multi-turn Conversation
python
message = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
system="You are a helpful assistant.",
messages=[
{"role": "user", "content": "What is Python?"},
{"role": "assistant", "content": "Python is a programming language..."},
{"role": "user", "content": "What are its main features?"},
],
)
Message Response Object
python
message.id # "msg_..."
message.type # "message"
message.role # "assistant"
message.content # list[ContentBlock] - TextBlock, ToolUseBlock, ThinkingBlock
message.model # model used
message.stop_reason # "end_turn", "max_tokens", "tool_use", "stop_sequence"
message.usage # Usage object
message.usage.input_tokens
message.usage.output_tokens
Streaming
Stream Helper (Recommended)
python
# Sync
with client.messages.stream(
max_tokens=1024,
messages=[{"role": "user", "content": "Say hello!"}],
model="claude-sonnet-4-5-20250929",
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
# Get the accumulated final message
final = stream.get_final_message()
Async Stream Helper
python
async with client.messages.stream(
max_tokens=1024,
messages=[{"role": "user", "content": "Say hello!"}],
model="claude-sonnet-4-5-20250929",
) as stream:
async for text in stream.text_stream:
print(text, end="", flush=True)
accumulated = await stream.get_final_message()
Stream Events
python
with client.messages.stream(...) as stream:
for event in stream:
if event.type == "text":
print(event.text) # delta text
print(event.snapshot) # accumulated text so far
elif event.type == "input_json":
print(event.partial_json) # tool input delta
print(event.snapshot) # accumulated JSON string
elif event.type == "content_block_stop":
print(event.content_block) # full ContentBlock
elif event.type == "message_stop":
print(event.message) # full Message
Stream Methods
stream.text_stream - iterator over text deltas onlystream.get_final_message() - blocks until done, returns accumulated Messagestream.get_final_text() - blocks until done, returns concatenated textstream.close() - cancel the stream earlystream.until_done() - blocks until stream consumed
Raw Stream (Lower-Level)
python
# Returns iterable of raw SSE events, uses less memory
stream = client.messages.create(
...,
stream=True,
)
for event in stream:
# RawMessageStartEvent, RawContentBlockDeltaEvent, etc.
print(event)
Tool Use (Function Calling)
Manual Tool Definition
python
from anthropic.types import ToolParam, MessageParam
tools: list[ToolParam] = [
{
"name": "get_weather",
"description": "Get the current weather in a city",
"input_schema": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
},
"required": ["city"],
},
}
]
message = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "What is the weather in SF?"}],
)
# Check for tool use
for block in message.content:
if block.type == "tool_use":
print(block.name) # "get_weather"
print(block.input) # {"city": "SF"}
print(block.id) # tool use ID for result
Returning Tool Results
python
# After getting tool_use, call your function, then send result back
messages = [
{"role": "user", "content": "What is the weather in SF?"},
{"role": "assistant", "content": message.content}, # contains tool_use block
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": tool_block.id,
"content": [{"type": "text", "text": "The weather is 73f"}],
}
],
},
]
response = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
tools=tools,
messages=messages,
)
@beta_tool Decorator (Automatic Schema)
python
from anthropic import beta_tool
@beta_tool
def sum(left: int, right: int) -> str:
"""Adds two integers together.
Args:
left (int): The first integer to add.
right (int): The second integer to add.
Returns:
int: The sum of left and right integers.
"""
return str(left + right)
# Use as dict for manual API calls
message = client.beta.messages.create(
tools=[sum.to_dict()],
max_tokens=1024,
model="claude-sonnet-4-5-20250929",
messages=[{"role": "user", "content": "What is 2 + 2?"}],
)
Tool Runner (Auto-Execution)
python
runner = client.beta.messages.tool_runner(
max_tokens=1024,
model="claude-sonnet-4-5-20250929",
tools=[sum],
messages=[{"role": "user", "content": "What is 9 + 10?"}],
)
for message in runner:
print(message) # handles tool calls automatically
ToolError
python
from anthropic.lib.tools import ToolError
@beta_tool
def my_tool(url: str) -> str:
"""Does something."""
if not valid(url):
raise ToolError(f"Invalid URL: {url}")
# ToolError can also include content blocks (images, etc.)
raise ToolError([
{"type": "text", "text": "Error details"},
{"type": "image", "source": {"type": "base64", "data": img_data, "media_type": "image/png"}},
])
Web Search (Server-Side Tool)
python
message = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
messages=[{"role": "user", "content": "What's the weather in New York?"}],
tools=[
{
"name": "web_search",
"type": "web_search_20250305",
}
],
)
# Access search usage
if message.usage.server_tool_use:
print(f"Web search requests: {message.usage.server_tool_use.web_search_requests}")
Vision (Image Input)
Base64 Image
python
import base64
from pathlib import Path
image_data = base64.standard_b64encode(Path("image.png").read_bytes()).decode("utf-8")
message = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "What's in this image?"},
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": image_data,
},
},
],
}
],
)
URL Image
python
message = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Describe this image"},
{
"type": "image",
"source": {
"type": "url",
"url": "https://example.com/image.jpg",
},
},
],
}
],
)
Supported formats: image/jpeg, image/png, image/gif, image/webp
Extended Thinking
python
response = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=3200,
thinking={"type": "enabled", "budget_tokens": 1600},
messages=[{"role": "user", "content": "Solve this complex problem..."}],
)
for block in response.content:
if block.type == "thinking":
print(f"Thinking: {block.thinking}")
elif block.type == "text":
print(f"Response: {block.text}")
Structured Outputs (Pydantic Parsing)
python
import pydantic
import anthropic
class Order(pydantic.BaseModel):
product_name: str
price: float
quantity: int
client = anthropic.Anthropic()
parsed_message = client.messages.parse(
model="claude-sonnet-4-5",
messages=[{"role": "user", "content": "Extract: 2 packs of Green Tea at $5.50 each"}],
max_tokens=1024,
output_format=Order,
)
print(parsed_message.parsed_output) # Order(product_name='Green Tea', price=5.5, quantity=2)
Prompt Caching
python
message = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
system=[
{
"type": "text",
"text": "Very long system prompt here...",
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": "Question about the system prompt"}],
)
# Check cache usage
print(message.usage.cache_creation_input_tokens)
print(message.usage.cache_read_input_tokens)
Message Batches API
Create a Batch