Skip to content

Stream phases

StreamingContentType is a string enum with ten values, attached to every StreamChunk via chunk.phase.

Phase Value Emitted when chunk.content type
THINKING "thinking" Reasoning model emits internal-monologue tokens str (token)
TOOL_REQUESTED "tool_requested" A streamed agent-loop driver is about to dispatch a round's tool calls: one per call, every call in the round announced before any of them is approved or run dict {"name": str, "arguments": dict, "id": str}
TOOL_CALLING "tool_calling" A tool call has just been dispatched and its result is available; id matches the call's TOOL_REQUESTED dict {"name": str, "arguments": dict, "response": str, "id": str}
CONTINUING "continuing" A streamed agent-loop driver is about to inject a round of its own (a nudge after an empty turn, or the forced tools-disabled wrap-up at the round cap); emitted once per injected round, immediately before that round's own chunks dict {"kind": "continuation" \| "final_answer", "prompt": str}, where kind matches the provenance tag written onto the injected message
INBOX "inbox" A streamed agent-loop driver is about to open a round that delivers an inbox message: an Inbox source had a message pending at a round boundary, and the round that follows is the model reading it. Distinct from CONTINUING, which names a prompt the loop composed for itself: this one is the user's dict {"text": str}
GENERATING "generating" The final response stream str (token)
IMAGE_GENERATING "image_generating" Per-step image-generation progress (HF callback / Gemini start-done) dict {"step": int, "total_steps": int, "image": PIL.Image \| None, "final": bool, "result": str \| bytes \| None}
AUDIO_GENERATING "audio_generating" Per-step audio-generation progress (one final chunk for MusicGen; N progress + 1 final for diffusers) dict {"step": int, "total_steps": int, "final": bool, "result": str \| bytes \| tuple \| None, "duration_s": float}
SPEECH_GENERATING "speech_generating" Per-chunk speech-generation progress (one final chunk for HuggingFace single-pass; N chunks for OpenAI HTTP stream) dict {"chunk_index": int, "total_chunks": int \| None, "final": bool, "result": str \| bytes \| ... \| None}
DONE "done" Terminal marker (rarely yielded; reserved) str (usually empty)

The enum inherits from str, so members compare equal to their string values, so chunk.phase == "thinking" is fine.

Helpers on StreamChunk

chunk.is_text()             # True for THINKING and GENERATING
chunk.is_tool_request()     # True for TOOL_REQUESTED (a call announced, not yet run)
chunk.is_tool_call()        # True for TOOL_CALLING
chunk.is_continuing()       # True for CONTINUING (both kinds: read content["kind"] for which)
chunk.is_inbox()            # True for INBOX (a round delivering a message the host handed the run)
chunk.is_image_progress()   # True for IMAGE_GENERATING
chunk.is_audio_progress()   # True for AUDIO_GENERATING
chunk.is_speech_progress()  # True for SPEECH_GENERATING
chunk.is_done()             # True for DONE

These avoid sprinkling phase comparisons through your code. Each is named for its phase and not for one of the kinds that phase can carry, which is why is_continuing() is also true of the forced wrap-up, a round that tells the model to stop calling tools.

Typical sequences

Model behaviour Phase sequence
Plain text generation GENERATING*
Thinking model, no tools THINKING*, then GENERATING*
Tool-using model THINKING* (if thinking), TOOL_REQUESTED per call, then TOOL_CALLING per call, GENERATING*
A streaming tool TOOL_REQUESTED, the tool's own chunks, then its TOOL_CALLING
Tool-using model, multi-round TOOL_REQUESTED* → TOOL_CALLING* → THINKING*? → GENERATING* repeated; chunk.iteration increments per round (agent context)
A round the loop injected CONTINUING, then that round's own chunks (THINKING*?, TOOL_CALLING* for a nudge, GENERATING*); chunk.iteration on the CONTINUING chunk is the injected round's own index
A round delivering an inbox message INBOX, then that round's own chunks (THINKING*?, TOOL_CALLING*, GENERATING*); chunk.iteration on the INBOX chunk is that round's own index

* = "one or more chunks".

TOOL_REQUESTED exists because TOOL_CALLING arrives only once a call returns: a tool that takes a minute would otherwise leave a streamed caller showing nothing for that minute. A round's calls are all announced first, before approval, so a refused call has an announcement too (its TOOL_CALLING carries the refusal). Pair the two by id, not by position: with concurrent_tool_calls=True the results arrive together after every call has run.

chunk.iteration tells you the round number moved, not who moved it: a tool round, a nudge after an empty turn, and the forced wrap-up all advance it identically. CONTINUING is what separates the last two from the first (see why it needs its own phase). INBOX is a third case iteration alone cannot tell apart from a tool round: the words are a host's, delivered between rounds a run was already going to make, not the loop's own and not the model's.

Async surface

aimu.aio yields the same StreamChunk type; phase, content, agent, iteration are unchanged. The consumption protocol differs: Iterator[StreamChunk] on the sync surface vs AsyncIterator[StreamChunk] on the async surface. Phase semantics and filtering are identical on both. See how-to: use async.

Filtering

Pass include=[...] to chat() or generate() to drop phases:

client.chat("hi", stream=True, include=["generating"])
client.chat("hi", stream=True, include=["thinking", "generating"])
client.chat("hi", stream=True, include=[StreamingContentType.GENERATING])  # enum form

Accepts strings or enum members. Omitting include= yields all phases.

include= is a chat() / generate() argument, so it does not reach CONTINUING or INBOX: both chunks come from the agent loop above the client, and Agent.run takes no include=. Drop them on chunk.phase in your own loop if you do not want them.

See also