LLM Engineering·Lesson 45 of 67·advanced
The Anthropic Python SDK: messages and streaming
Install it, call it, stream it, and handle the errors properly — including the retry rules that decide whether your client survives a bad afternoon.
In this lesson · 20 min
- →Create a client and make a request without hard-coding a key
- →Stream a response and accumulate it correctly
- →Read the stream event types and know which ones matter
- →Catch the SDK's typed exceptions, most specific first
- →Configure timeouts and retries, and know what the SDK already retries
- →Turn on adaptive thinking and choose an effort level
The SDK is a thin, well-shaped wrapper over the one endpoint from the last lesson. This lesson is about using it well — which is mostly about streaming and about failing properly.
Getting started
pip install anthropic
export ANTHROPIC_API_KEY="sk-ant-..." # never in the source
import anthropic
client = anthropic.Anthropic() # reads the environment
response = client.messages.create(
model="claude-opus-5",
max_tokens=16000,
system="You are a careful assistant.",
messages=[{"role": "user", "content": "Explain embeddings in two sentences."}],
)
print("".join(b.text for b in response.content if b.type == "text"))
print(response.usage.input_tokens, "in,", response.usage.output_tokens, "out")
Streaming
Streaming matters for two separate reasons. The visible one is that a reader sees words appear instead of waiting. The invisible one matters more: a long non-streaming request can sit past an idle-connection timeout and fail after doing all the work.
with client.messages.stream(
model="claude-opus-5",
max_tokens=64000,
messages=[{"role": "user", "content": "Write a short essay on retrieval."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
final = stream.get_final_message()
print()
print(final.stop_reason, final.usage.output_tokens)
stream.text_stream yields text as it arrives; get_final_message() gives you the assembled
message afterwards — the same object a non-streaming call would have returned. You almost always
want both.
Here is that loop against a recorded stream, so you can see the accumulation:
The event stream
text_stream is a convenience over a richer event stream. Iterate the stream itself when you need
tool calls, thinking, or usage as it updates:
| Event | Fires |
|---|---|
message_start |
once, at the beginning |
content_block_start |
when a text, thinking or tool_use block begins |
content_block_delta |
for each chunk — check delta.type |
content_block_stop |
when a block finishes |
message_delta |
carries stop_reason and updated usage |
message_stop |
once, at the end |
Errors
The SDK raises typed exceptions. Catch them most specific first, because the difference between them is the difference between retrying and giving up:
On your own machine that chain is:
try:
response = client.messages.create(...)
except anthropic.NotFoundError:
... # wrong model id — do not retry
except anthropic.RateLimitError:
... # 429 — back off
except anthropic.APIStatusError as error:
if error.status_code >= 500:
... # retryable
else:
raise # a 400 will fail identically next time
except anthropic.APIConnectionError:
... # network — retryable
What the SDK already retries
So you do not need a retry loop for the ordinary cases — the SDK has one. Configure it rather than reimplementing it:
client = anthropic.Anthropic(max_retries=5, timeout=30.0) # seconds, in Python
# Or per request, without mutating the client:
client.with_options(timeout=5.0, max_retries=0).messages.create(...)
Thinking and effort
Adaptive thinking lets the model decide how much reasoning a request deserves; effort sets the
overall depth and spend:
response = client.messages.create(
model="claude-opus-5",
max_tokens=16000,
thinking={"type": "adaptive", "display": "summarized"},
output_config={"effort": "high"}, # low | medium | high | xhigh | max
messages=[{"role": "user", "content": "Work through this carefully..."}],
)
for block in response.content:
if block.type == "thinking":
print("[thinking]", block.thinking)
elif block.type == "text":
print(block.text)
Two details that catch people out. Thinking is on by default on Claude Opus 5, so omitting the
parameter still gets you adaptive thinking. And display defaults to "omitted", which returns
thinking blocks with empty text — if you are streaming reasoning to a reader, ask for
"summarized" explicitly or the page just looks frozen.
Async
For concurrency — the subject of module 8 — the same API exists as AsyncAnthropic:
import asyncio, anthropic
async def main():
client = anthropic.AsyncAnthropic()
response = await client.messages.create(
model="claude-opus-5",
max_tokens=16000,
messages=[{"role": "user", "content": "Hello"}],
)
print(response.content[0].text)
asyncio.run(main())
Try it yourself
Write collect(events): return a dict with text, thinking, stop_reason and output_tokens gathered from one pass over the event stream.
Write should_retry(error): True for rate limits, 5xx statuses and connection errors; False for 400, 401 and 404.
Check yourself
Why does the SDK refuse a non-streaming request with a very large max_tokens?
Check yourself
Your client catches `except anthropic.APIError` and retries five times. What goes wrong?
Recap
anthropic.Anthropic()reads the key from the environment; never hard-code it.- Stream anything long:
messages.stream(...),stream.text_stream, thenget_final_message(). - The event stream carries
content_block_delta(branch ondelta.type), andmessage_deltacarriesstop_reasonand usage. - Catch typed exceptions most specific first; 429, 5xx and connection errors are retryable, 400, 401 and 404 are not.
- The SDK already retries the transient cases — configure
max_retriesandtimeoutinstead of writing your own loop, and remember worst-case wall-clock multiplies. thinking={"type": "adaptive"}withoutput_config={"effort": ...}; ask fordisplay="summarized"if you want to show the reasoning.