Streaming¶

agent.stream(prompt) starts a run and returns it. Iterate over it with async for to get its events as they happen:

--8 < --"examples/basic.py"

Events¶

Events are small, read-only objects backed by Rust. They work with isinstance and with match.

When the model asks for several tool calls at once, they run at the same time, and each ToolFinished comes as soon as its call ends: a fast call's result does not wait for a slow one. The model still reads the results in the order it asked for the calls.

A subagent's events come in the same stream, with subagent_id set (it is None for the main agent's events).

await agent.run(prompt) does the same run without streaming and returns the RunFinished event. It has no web streams: ai_sdk() and ag_ui() are on the run stream() returns. Without an event loop (scripts, Django, Celery), use agent.run_sync(prompt) and for event in agent.stream_sync(prompt): see Sync code.

One Agent can serve many runs at the same time: each run has its own history. Create it once and reuse it.

New fields may be added to events in minor versions; existing ones keep their meaning.

How a run ends¶

Every run that does not fail ends with RunFinished, whose stop_reason says why:

An answer cut by "length" may end in a half-written tool call: it is never run.

Stopping a run. run.stop() ends it at the next safe point and keeps what it did: an answer being streamed ends at once (its text so far is kept, as the last assistant message), tools already running finish, and no new request is sent. Keep reading the events: the run still ends with RunFinished, whose messages are a valid history to continue from. (Leaving the async for loop with break instead aborts the run and keeps nothing.)

run = agent.stream("Write a long story")
async for event in run:
    if isinstance(event, TextDelta) and user_pressed_stop():
        run.stop()

Errors keep the conversation. An AgentError raised by a run has the history up to the failure in error.messages, so a retry can continue instead of starting again. MaxTurnsExceededError (after max_turns model requests) is one too:

try:
    result = await agent.run("Plan my trip")
except MaxTurnsExceededError as error:
    result = await agent.run("Wrap up with what you have", history=error.messages)

Token usage¶

RunFinished.usage holds the tokens used by all the model requests of the run, with both APIs:

Counts the API did not report are 0. If requests is lower than turns, some requests sent no usage (some OpenAI-compatible servers don't).

result = await agent.run("Hi")
print(result.usage.input_tokens, result.usage.output_tokens)

total = Usage()  # all zeros
for result in results:
    total += result.usage

Tools and hooks see the tokens used so far as ctx.usage. A failed run still used (and paid for) tokens: an AgentError raised by a run has them in error.usage.

try:
    result = await agent.run("Hi")
except AgentError as error:
    print("used before failing:", error.usage)

Grouping streamed text¶

Models stream text in tiny pieces, and each TextDelta costs a little Python work. To get fewer, bigger events, choose how text is grouped with text_chunks:

Set it on the agent, or override it for one run:

agent = Agent(model="gpt-5-mini", text_chunks="paragraph")

async for event in agent.stream("Explain asyncio", text_chunks=20):
    ...

Batches of events¶

Each step of async for event in run hands one event from Rust to Python, and the hand-over costs more than most events. run.batches() hands over every event that is already waiting, as a list:

async for events in run.batches():
    for event in events:
        ...

It never waits to fill a batch: when events come one at a time (a real model streaming at its own pace), each list has one event and nothing changes. When they pile up (cached or very fast answers, a busy server falling behind), one step carries them all. run.ai_sdk() and run.ag_ui(...) (see Web frontends) read the run this way too. Numbers in the benchmarks.

Other settings¶

agent = Agent(
    model="gpt-5-mini",
    instructions="Be concise.",  # system prompt
    model_parameters={"temperature": 0.2},  # sent as-is to the API
    max_turns=20,  # model requests per run before MaxTurnsExceededError
)