Skip to content

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:

PythonPython not started

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:

PythonPython not started
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:

PythonPython not started

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

PythonPython not started

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

Exercise 1

Write collect(events): return a dict with text, thinking, stop_reason and output_tokens gathered from one pass over the event stream.

Your turnPython not started
Exercise 2

Write should_retry(error): True for rate limits, 5xx statuses and connection errors; False for 400, 401 and 404.

Your turnPython not started

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, then get_final_message().
  • The event stream carries content_block_delta (branch on delta.type), and message_delta carries stop_reason and 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_retries and timeout instead of writing your own loop, and remember worst-case wall-clock multiplies.
  • thinking={"type": "adaptive"} with output_config={"effort": ...}; ask for display="summarized" if you want to show the reasoning.