Streaming, Tool Use & Vision
CoreWork with the Messages API's core request/response mechanics · Difficulty 2/5
Explanation
Streaming
Setting stream=True delivers the response as server-sent events as the model generates it, rather than waiting for the full response. The integration code consumes events (message_start, content_block_delta, message_stop) and assembles the text incrementally. This lowers perceived latency for interactive UIs -- it changes *when* tokens arrive, not how many tokens are generated or billed.
Tool Use
Pass a tools array of JSON-schema tool definitions. When Claude decides to use one:
- The response's
stop_reasonis `tool_use` - The response
contentcontains a `tool_use` block (tool name and arguments) - Your code executes the tool
- You send the result back as a `tool_result
block inside a newuser` message
This loop is the foundation of every agent built on the Messages API (full treatment in the tool-design/MCP domain).
Vision (Multimodal Input)
Content blocks can include images (base64-encoded or by URL) alongside text, so Claude can read screenshots, charts, and documents in the same request as a text instruction. This is the "multi-format input" capability referenced across the exam blueprint.
Common exam traps
- **"Streaming reduces cost."** It does not -- it reduces perceived latency only; total tokens and total cost are unchanged.
- Treating a
tool_usestop_reason as a final answer rather than a signal that the loop must continue: execute the tool, then send a `tool_result` block back. - Assuming vision requires a separate API -- it is the same Messages API, with image content blocks alongside text in the same message.
Key Takeaways
- Streaming delivers server-sent events as generation happens, lowering perceived latency without changing total tokens or cost
- A tool_use stop_reason means Claude wants to call a tool: execute it, then return a tool_result block in a new user message
- Vision content blocks (base64 or URL images) sit alongside text in the same Messages API request
- "Streaming saves money" is a common exam trap -- it only changes delivery timing
Glossary Terms
The structured units that make up Claude's response. Types include: `text` (plain text response), `tool_use` (a request to call a tool with specific inputs), `tool_result` (the caller's response to a tool request), and `thinking` (internal reasoning when extended thinking is enabled). A single response can contain multiple content blocks of mixed types.
An API mode where Claude sends partial response tokens as they are generated, rather than waiting for the full response. Reduces perceived latency for users. Use server-sent events (SSE) to consume the stream. Not available with the Message Batches API.
A content block type in the user message that returns the output of a tool execution back to Claude. Must include the 'tool_use_id' matching the original tool_use block. Can be text, images, or error messages. Claude processes the result and continues reasoning.
A content block type in Claude's response indicating the model wants to call a specific tool. Contains 'id', 'name', and 'input' fields. The agent must execute the tool and return results in a tool_result content block for the conversation to continue.
Related Concepts
Messages API Request Shape, stop_reason & usage
A Messages API request needs messages (alternating user/assistant), model, and required max_tokens; system and tools are optional
Extended Thinking and Prompt Caching
Extended thinking produces internal reasoning before the answer; thinking tokens are billed as output tokens