Choosing Between Anthropic() and AsyncAnthropic() in Production Code

The anthropic package ships two client classes with an identical method surface: Anthropic() and AsyncAnthropic().

The right choice depends entirely on how your program handles concurrency, not on which one is "better."

Summary

Anthropic() is a blocking client - calling client.messages.create(...) pauses the current thread until a response arrives.

AsyncAnthropic() is a non-blocking client built on asyncio - calling await client.messages.create(...) yields control back to the event loop while the request is in flight.

Both expose the same parameters, the same response types, and the same error classes, so switching between them later is mostly mechanical.

The decision that matters is whether your application already runs on an event loop (an async web framework, an async job queue) or runs as a straight-line script, because that decision was effectively made for you before you ever picked a Claude client.

Getting this wrong doesn't break correctness, it costs throughput: a sync client called from inside an async framework blocks the whole event loop, and an async client used in a single-threaded script adds ceremony with no benefit.

Recipe

import anthropic
 
# Script, notebook, CLI tool, batch job
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
 
# FastAPI, aiohttp, or any asyncio-based service
async_client = anthropic.AsyncAnthropic()
response = await async_client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)

When to reach for Anthropic():

• One-off scripts, notebooks, and CLI tools that make requests sequentially.
• Batch or ETL jobs that process items one at a time and don't need overlap between requests.
• Any codebase built on a synchronous web framework (Flask or Django without async views).

When to reach for AsyncAnthropic():

• Web services built on an async framework, most commonly FastAPI, that already run on an event loop.
• Workloads that fan out many Claude calls concurrently (summarizing 50 documents at once, for example).
• Any code that needs to call Claude while also awaiting other I/O (a database query, another API call) without blocking either.

Working Example

This example shows the same summarization endpoint written two ways: as a synchronous script and as a FastAPI route using the async client, so the contrast is direct.

# sync_script.py - a standalone batch job
import anthropic
 
client = anthropic.Anthropic()
 
def summarize(text: str) -> str:
    message = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=300,
        system="Summarize the input in one sentence.",
        messages=[{"role": "user", "content": text}],
    )
    return message.content[0].text
 
if __name__ == "__main__":
    documents = ["First document text...", "Second document text..."]
    for doc in documents:
        print(summarize(doc))

# fastapi_service.py - an async web service
from fastapi import FastAPI
from pydantic import BaseModel
import anthropic
 
app = FastAPI()
client = anthropic.AsyncAnthropic()
 
class SummarizeRequest(BaseModel):
    text: str
 
@app.post("/summarize")
async def summarize(req: SummarizeRequest):
    message = await client.messages.create(
        model="claude-sonnet-5",
        max_tokens=300,
        system="Summarize the input in one sentence.",
        messages=[{"role": "user", "content": req.text}],
    )
    return {"summary": message.content[0].text}

What this demonstrates:

• Both versions call the same method (messages.create) with the same parameters; only async/await and the client class differ.
• The FastAPI route awaits the Claude call, so the event loop can serve other incoming requests while this one waits on the network.
• Both clients are constructed once at module scope and reused across calls, not recreated per request.
• The batch script has no concurrent requests to overlap, so the sync client adds no cost there.

Deep Dive

How It Works

• Python's asyncio event loop runs one coroutine at a time but switches to another whenever the running one hits an await on I/O, such as a network call.
• AsyncAnthropic() builds its HTTP calls on top of httpx's async transport, so an outstanding Claude request yields control back to the loop instead of parking a thread.
• Anthropic() uses httpx's sync transport; a call blocks the calling thread until a response header arrives (or, when streaming, until the first chunk arrives).
• A sync client called from inside async def code still works, but it blocks the entire event loop for the duration of the call, stalling every other coroutine scheduled on that loop, including unrelated requests being served by the same FastAPI process.
• Constructing a fresh client per request (sync or async) discards connection pooling and forces a new TLS handshake more often than necessary; both client classes are meant to be built once and reused.

Sync vs Async at a Glance

Python Notes

# Running many summaries concurrently with the async client
import asyncio
import anthropic
 
client = anthropic.AsyncAnthropic()
 
async def summarize(text: str) -> str:
    message = await client.messages.create(
        model="claude-sonnet-5",
        max_tokens=300,
        messages=[{"role": "user", "content": text}],
    )
    return message.content[0].text
 
async def main():
    documents = ["Doc A...", "Doc B...", "Doc C..."]
    results = await asyncio.gather(*(summarize(doc) for doc in documents))
    print(results)
 
asyncio.run(main())

asyncio.gather is what actually earns you the concurrency benefit of the async client: it launches all the requests before awaiting any of them, so they run overlapped rather than one after another. Using AsyncAnthropic() but still awaiting each call sequentially in a loop gets you none of the throughput gain and only the added complexity.

Gotchas

• Calling the sync client inside an async FastAPI route. client.messages.create(...) (no await) inside async def blocks the entire event loop for that call's duration, stalling every other request the process is handling. Fix: use AsyncAnthropic() inside async route handlers, or run the sync call in a thread pool with await run_in_threadpool(...).
• Constructing a new client per request. Building anthropic.Anthropic() or anthropic.AsyncAnthropic() inside a request handler discards connection pooling on every call. Fix: construct one client at module or app startup and reuse it.
• Mixing asyncio.run() calls inside an already-running event loop. Calling asyncio.run(...) from inside a FastAPI handler (which is already inside a loop) raises a RuntimeError. Fix: await the async client directly in the async handler rather than wrapping it in asyncio.run().
• Sequential await in a loop instead of asyncio.gather. for doc in docs: await summarize(doc) runs requests one at a time, giving up the concurrency the async client was chosen for. Fix: launch the coroutines together and await them as a group with asyncio.gather (or a bounded asyncio.Semaphore to cap concurrency).
• Forgetting async with for async streaming. Using with instead of async with on AsyncAnthropic().messages.stream(...) raises a TypeError, since the async client's stream object is an async context manager. Fix: always pair AsyncAnthropic() streaming with async with and async for.
• Assuming the async client is faster per call. A single request through AsyncAnthropic() takes the same wall-clock time as the same request through Anthropic() - the benefit only appears when multiple requests overlap. Fix: don't switch to async for latency reasons alone; switch it for concurrency.

Alternatives

FAQs

Related

• The Anthropic Python SDK Mental Model - why sync and async share one API surface
• Streaming Responses with the Python SDK - stream() on both client types
• Handling Streaming Tool Use in Async Python Workflows - combining AsyncAnthropic with tool use
• Python SDK Retry and Timeout Configuration Reference - max_retries and timeout on both clients

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the official anthropic Python SDK (latest 0.x release). Model names, SDK versions, and pricing move quickly - verify current specifics at platform.claude.com/docs before relying on them.