Skip to content

Stream

What is the Stream?#

The Stream in AG2 is a central event bus that facilitates communication between agents and system components. It operates on an event-driven architecture where components can publish events (derived from BaseEvent) and other components can subscribe to these events.

The Stream manages the flow of messages, actions, and tool calls, allowing for decoupled and scalable architectures. You interact with the Stream by publishing events to it and subscribing to specific events you want to listen to.

Passing a custom stream to an Agent#

By default, agents create a MemoryStream instance internally for each conversation.

However, you can pass a custom stream to an agent when calling its ask method. This allows you to set up subscribers on the stream before the conversation starts, letting you observe or intercept the agent's internal events.

from ag2 import Agent, MemoryStream
from ag2.events import ModelRequest, ModelResponse

agent = Agent("my_agent")

my_stream = MemoryStream()

# Subscribe to see what the model requests and returns
@my_stream.where(ModelRequest | ModelResponse).subscribe()
def log_model_activity(event):
    print(f"[{event.__class__.__name__}] {event}")

# Pass the stream to the agent
response = await agent.ask("Hello!", stream=my_stream)

How to subscribe to stream events#

You can listen to events flowing through the stream using the subscribe method. To filter which events you receive, you can use the where method.

Note

All event subscribers and interrupters support the same powerful execution context capabilities as Agent Tools.

By type-hinting the Context object (or using Depends, Inject, Variable), your subscribers can access injected dependencies, interact with human-in-the-loop flows, or access conversation variables.

For more detailed information on specific context features, see Dependency Injection, Context Variables, Depends, Human-in-the-loop.

Subscribe to events of a specific type#

To subscribe to events of a specific type, pass the event class to stream.where().

from ag2 import MemoryStream
from ag2.events import ToolCallEvent

stream = MemoryStream()

def handle_tool_call(event: ToolCallEvent):
    print(f"Tool called: {event.name}")

# Subscribe only to ToolCallEvent events
stream.where(ToolCallEvent).subscribe(handle_tool_call)

Subscribe to multiple event types#

You can subscribe to multiple event types using the bitwise OR operator (|).

1
2
3
4
5
6
7
from ag2.events import ToolCallEvent, ModelMessage

def handle_event(event):
    print(f"Received event: {event}")

# Subscribe to either ToolCallEvent or ModelMessage events
stream.where(ToolCallEvent | ModelMessage).subscribe(handle_event)

Exclude events of a specific type#

You can negate an event type using the bitwise NOT operator (~). This creates a condition that matches everything except the specified type.

# Subscribe to all events except ToolCallEvent
stream.where(~ToolCallEvent).subscribe(handle_event)

Subscribe to events with a specific value#

You can filter events based on the value of their fields. The event classes define fields that support comparison operators.

# Subscribe only to ToolCallEvent events where the name is "fetch_data"
stream.where(ToolCallEvent.name == "fetch_data").subscribe(handle_event)

Static subscribers with decorators#

You can use subscribe as a decorator to register static handlers cleanly. This works well with where filters.

1
2
3
4
5
6
7
8
9
stream = MemoryStream()

@stream.where(ToolCallEvent).subscribe()
def on_tool_call(event: ToolCallEvent):
    print(f"Handling tool call: {event.name}")

@stream.subscribe()
def on_any_event(event):
    print(f"Global logger: {event}")

Dynamic subscribers by context manager#

If you only need to listen to events for a specific duration or within a specific block of code, you can use sub_scope as a context manager. This dynamically subscribes the handler when entering the block and unsubscribes when exiting.

1
2
3
4
5
6
7
def temp_listener(event):
    print("Temporary event captured:", event)

# temp_listener is active only inside the with block
with stream.sub_scope(temp_listener):
    # Perform actions that might trigger events
    pass

You can also combine this with where:

with stream.where(ModelMessage).sub_scope(temp_listener):
    pass

Subscriber timeouts#

Set timeout in seconds to limit each invocation of a subscriber or interrupter. The default is None (no limit); a configured value must be finite and greater than zero.

import httpx

from ag2 import Agent, MemoryStream
from ag2.events import ModelResponse

stream = MemoryStream()

@stream.where(ModelResponse).subscribe(timeout=5.0)
async def report_response(event: ModelResponse) -> None:
    async with httpx.AsyncClient(timeout=3.0) as client:
        response = await client.post("https://metrics.example.com/responses", json={"content": event.content})
        response.raise_for_status()

agent = Agent("assistant")
reply = await agent.ask("Hello!", stream=stream)

The same parameter works with stream.subscribe(handler, timeout=5.0) and stream.sub_scope(handler, timeout=5.0), including filtered streams and interrupt=True subscriptions.

The limit starts when delivery reaches that handler and covers dependency resolution, handler execution, and dependency cleanup. Waiting for earlier handlers does not consume it. Calls the handler awaits, including nested event publication, share its limit. It does not limit the subscription's lifetime or detached background tasks.

Expiry raises TimeoutError to the event publisher, like other handler exceptions, and stops delivery of that event to subsequent handlers. During an agent turn this can fail the turn. The subscription remains registered for later events until explicitly removed or its scope ends.

Cancellation is cooperative

AG2 requests cancellation and waits for it to finish, so cancellation cleanup can exceed the configured limit. A synchronous callback running in a worker thread may continue after AG2 stops waiting. Configure timeouts on its HTTP client, database driver, or subprocess as well. Blocking code with sync_to_thread=False prevents the event loop from enforcing the timeout.

Get specific events#

To wait for and get the next occurrence of a specific event asynchronously, use the get async context manager. This yields a future that resolves to the matched event.

1
2
3
4
5
6
7
from ag2.events import HumanMessage

async def wait_for_human(stream: MemoryStream):
    async with stream.get(HumanMessage) as response:
        # Code here can trigger the event, or we just wait
        event = await response
        print(f"User said: {event.content}")

Iterate over stream events#

Use join() as a context manager when you want an async iterator of events for a bounded block of code. The iterator receives events published after the with block starts. Pass max_events to stop automatically after a fixed number of events.

1
2
3
4
5
from ag2.events import ToolResultEvent

with stream.where(ToolResultEvent).join(max_events=1) as results:
    async for event in results:
        print(f"Tool result: {event.result}")

Do not timeout individual join() pulls

Consume the iterator with a plain async for. Avoid wrapping individual pulls such as await asyncio.wait_for(events.__anext__(), timeout=...): cancelling one __anext__() closes the current iterator, so later events will not be yielded by that iterator. For bounded consumption, use join(max_events=N) or put one asyncio.timeout(...) around the whole loop.

Observe a Delegation Tree#

When an agent delegates through subagent tools, every descendant event reaches every ancestor's stream. Forwarding includes grandchildren and transient chunks; register an observer on the root agent to observe the whole tree without choosing a persistent child stream.

The event type distinguishes observation from local execution:

Source event What an ancestor receives Observer filter
Model requests/responses, tool events, and other operational events ChildEvent containing the original event @observer(ChildEvent); inspect event.source_event
Transient events such as ModelMessageChunk TransientChildEvent, a transient subclass of ChildEvent The same @observer(ChildEvent) filter
UsageEvent and every TaskEvent The source event type, with delegation provenance; both inherit InertEvent @observer(UsageEvent); lifecycle classes such as @observer((TaskStarted, TaskCompleted, TaskFailed))

A ChildEvent is non-conversational: it does not enter the ancestor's model transcript or trigger its tools, model loop, or HITL handlers. The original author's task_id, agent_name, and origin_event_id identify its source. Its path contains delegation task IDs from the outermost invocation to that author. Forwarding through another ancestor keeps the same source rather than nesting another observation envelope.

Type filters match the delivered event itself. A parent subscription to ToolCallEvent receives local tool calls; inspect ChildEvent.source_event to find calls authored by descendants. BaseEvent.source_event returns the event itself for a local event, so shared inspection code can use that property on either form.

This example streams a worker's reply through the OpenAI Responses API and reports actual token usage across the tree. Install ag2[openai] and set OPENAI_API_KEY as described in the Quick Start.

import asyncio

from ag2 import Agent, observer
from ag2.config import OpenAIResponsesConfig
from ag2.events import ChildEvent, ModelMessageChunk

@observer(ChildEvent)
def observe_child(event: ChildEvent) -> None:
    source = event.source_event
    if isinstance(source, ModelMessageChunk):
        print(f"{event.agent_name}: {source.content}")

async def main():
    worker = Agent(
        "worker",
        config=OpenAIResponsesConfig(model="gpt-5", streaming=True),
        prompt="Answer the assigned question in one sentence.",
    )
    coordinator = Agent(
        "coordinator",
        config=OpenAIResponsesConfig(model="gpt-5", streaming=True),
        prompt="Delegate the question to task_worker exactly once, then summarize its response.",
        tools=[worker.as_tool(description="Answer a focused question.")],
        observers=[observe_child],
    )
    reply = await coordinator.ask("Why give each subagent its own conversation history?")
    print(reply.body)
    report = await reply.usage()
    print(f"Total tokens across the tree: {report.total.total_tokens}")

if __name__ == "__main__":
    asyncio.run(main())

Transient observations remain transient, so chunks are delivered live without being retained in default history. Normal persist_all behavior still applies. Forwarding awaits the ancestor's ordinary delivery pipeline: a slow subscriber can delay descendants, and subscriber errors follow normal stream delivery behavior. Filter broad subscriptions and cadence-based watches when they should only process part of the tree.

Reply to an Event's Author#

While the author is executing, await event.origin.send(reply_event) delivers an event to that exact invocation through its normal event pipeline. The handle addresses the original author even when a grandparent observes the event or several invocations use the same agent name. There is no name lookup or broadcast step.

Use a custom non-conversational event to exchange application guidance without starting another model call. In this example, the worker's tool requests guidance, the parent responds, and the worker records the response before its tool resumes.

The example uses OpenAIResponsesConfig; install ag2[openai] and set OPENAI_API_KEY as described in the Quick Start.

import asyncio

from ag2 import Agent, Context, observer, tool
from ag2.config import OpenAIResponsesConfig
from ag2.events import BaseEvent, ChildEvent

class GuidanceRequested(BaseEvent):
    __conversational__ = False

class Guidance(BaseEvent):
    __conversational__ = False
    text: str

@observer(ChildEvent)
async def give_guidance(event: ChildEvent) -> None:
    if isinstance(event.source_event, GuidanceRequested):
        await event.origin.send(Guidance(text="Focus on whether worker updates are visible to the parent"))

@observer(Guidance)
def receive_guidance(event: Guidance, context: Context) -> None:
    context.variables["guidance"] = event.text
    print(event.text)

@tool
async def request_guidance(context: Context) -> str:
    """Ask the coordinator how to continue."""
    await context.send(GuidanceRequested())
    return context.variables.get("guidance", "No guidance received; answer directly.")

async def main():
    worker = Agent(
        "worker",
        config=OpenAIResponsesConfig(model="gpt-5"),
        prompt="Call request_guidance before answering, then follow its guidance and answer in one sentence.",
        tools=[request_guidance],
        observers=[receive_guidance],
    )
    coordinator = Agent(
        "coordinator",
        config=OpenAIResponsesConfig(model="gpt-5"),
        prompt="Delegate the question to task_worker exactly once, then summarize its response.",
        tools=[worker.as_tool(description="Work with guidance from the coordinator.")],
        observers=[give_guidance],
    )
    reply = await coordinator.ask("How do copied and shared variables differ?")
    print(reply.body)

if __name__ == "__main__":
    asyncio.run(main())

The receiving pipeline determines the delivered event's effect. In particular, sending a model request can start a reentrant model call; delivery adds no scheduling barrier. Each delivery also records a DownEvent audit (or TransientDownEvent for a transient event).

Handles belong to one invocation, expire when it ends, and are not serialized. Saved history retains source metadata but has no live origin; accessing it on a replayed observation or a local inert event raises RuntimeError. Sending through an expired handle raises DeliveryError from ag2.tools.subagents and publishes DeliveryFailed on the sender's stream. Even a forwarded terminal lifecycle event no longer has an executing recipient.

Account for Descendant Usage#

Ancestors receive each descendant's original UsageEvent as it arrives, including spend before failure or cancellation. Its event_id, kind, provider, and model stay unchanged through forwarding. Descendant records additionally carry task_id, agent_name, and path; a local record has no delegation task ID and an empty path.

Use @observer(UsageEvent) for both local and descendant spend. For local-only usage or lifecycle subscriptions, filter the event's path == (); excluding ChildEvent alone still includes descendant inert events.

await reply.usage() includes local and descendant costs and deduplicates records by source identity. Custom reports should also count each UsageEvent.event_id once within their reporting scope. New delegations produce no kind="subtask" rollup or parts summary. ModelResponse.usage and terminal task usage are snapshots for inspection, not additional additive records. Existing archived rollups remain readable.

See TokenMonitor for budget alerts and Variable Scopes Across Subagents for the separate rules governing shared application state.

Query retained history#

Use stream.history.where(...) to inspect events already stored in a conversation. It accepts the same event classes and field conditions as live subscriptions. Building a query is synchronous; its all(), first(), last(), and count() methods are asynchronous and each reads a fresh, finite snapshot.

import asyncio
from ag2 import Context, MemoryStream
from ag2.events import ToolCallEvent

async def main():
    stream = MemoryStream()
    context = Context(stream)
    await context.send(ToolCallEvent(name="lookup", arguments='{"page": 1}'))
    await context.send(ToolCallEvent(name="lookup", arguments='{"page": 2}'))
    calls = stream.history.where(ToolCallEvent)
    lookups = calls.where(ToolCallEvent.name == "lookup")
    print(await lookups.count())  # 2
    print(await lookups.first())  # First stored lookup
    print(await lookups.last())   # Most recent stored lookup
    print(await lookups.all())    # Both lookups, in publication order

asyncio.run(main())

Chained where clauses combine with AND and leave the original query unchanged. Class queries include subclasses. all() returns a fresh list of the ordinary stored event objects; first() and last() return None for an empty selection, and count() returns zero. Storage errors propagate to the caller.

History queries select top-level stored occurrences. They preserve repeated publications and do not expand tool batches, model responses, or child streams. A filtered stream shares its parent's History: a live subscription filter does not implicitly restrict history queries.

Unlike stream.get() or join(), these operations never wait for future events. They cover retained history only. Events removed by compaction are unavailable, so a history count is not a lifetime total.

Scope to the current user input#

history.since_last_user_input() selects events after the latest retained actual user input and excludes that input itself. It composes with the same filters and terminal methods. This example uses the OpenAI Responses API; set OPENAI_API_KEY before running it, as described in the Quick Start:

import asyncio

from ag2 import Agent, tool
from ag2.config import OpenAIResponsesConfig
from ag2.events import ToolCallEvent

@tool
def lookup() -> str:
    """Look up an item."""
    return "item"

async def main():
    agent = Agent(
        "lookup",
        tools=[lookup],
        config=OpenAIResponsesConfig(model="gpt-5"),
        prompt="Use lookup to find items. Answer acknowledgements directly.",
    )
    reply = await agent.ask("Find an item using lookup.")
    history = reply.context.stream.history
    calls = history.since_last_user_input().where(ToolCallEvent)
    print("Calls for this input:", await calls.count())
    await reply.ask("Thanks")
    print("Calls for the new input:", await calls.count())

if __name__ == "__main__":
    asyncio.run(main())

The query is lazy, so the same calls object counts the second input after reply.ask("Thanks") starts a new interval.

A new interval starts with:

  • agent.ask(), agent.run(), and their continuations reply.ask() and reply.run();
  • a follow-up sent with run.enqueue(...) (feeding the turn while it runs), once the running turn consumes it.

Tool results, compaction summaries, and messages queued with context.enqueue(...) from tools or background tasks do not start a new interval, even when they arrive after the model's final response.

Each ModelRequest stores this in its origin field: "user" for input a person sent, "service" for framework messages. The provider still receives both as user-role content. Requests stored before the field existed count as "user". Code that forwards a person's message into a running turn, such as a chat bridge, marks it explicitly with context.enqueue("Use the March report instead", origin="user").

The boundary is found before filters apply, so history.where(ToolCallEvent).since_last_user_input() selects the same events. If compaction or retention has removed the latest user input, the scoped query returns an empty selection; it does not recover the boundary from a summary.

Raise events manually#

To raise or publish events to the stream, you should always use the Context object rather than sending them to the stream directly. The Context ensures that dependencies and the stream scope are properly propagated.

from ag2 import Context
from ag2.events import ModelMessage

async def publish_message(context: Context):
    event = ModelMessage(content="Hello from the agent!")
    # Always use context.send() to raise events
    await context.send(event)

Events Interrupters#

Interrupters allow you to intercept an event before it reaches regular subscribers. You can use an interrupter to modify the event, raise a completely different event in its place, or suppress it entirely.

To register an interrupter, pass interrupt=True to the subscribe method. If the interrupter returns an event, that event replaces the original one for subsequent interrupters and subscribers. If it returns None, the event is suppressed and propagation stops.

@stream.where(ModelMessage).subscribe(interrupt=True)
async def intercept_message(
    event: ModelMessage,
    context: Context,
) -> BaseEvent | None:
    if "secret" in event.content:
        # Suppress the event by returning None
        return None

    elif "alert" in event.content:
        # Replace it with a different event
        await context.send(AlertEvent(message=event.content))
        return None

    # Or modify and return the original event
    event.content = event.content.upper()
    return event

RedisStream — Persistent & Cross-Process Events#

RedisStream is a drop-in replacement for MemoryStream that adds persistent event history and cross-process pub/sub via Redis. Events are delivered to all subscribers — even across different processes or machines.

pip install "ag2[redis]"

Basic Usage#

from ag2 import Agent
from ag2.streams.redis import RedisStream
from ag2.config import OpenAICompletionsConfig

stream = RedisStream("redis://localhost:6379")

agent = Agent(
    "assistant",
    prompt="You are a helpful assistant.",
    config=OpenAICompletionsConfig("gpt-4o-mini"),
)

reply = await agent.ask("Hello!", stream=stream)

# History is persisted in Redis and survives restarts
history = list(await stream.history.get_events())

All the same subscription patterns (subscribe, where, sub_scope, get, interrupters) work exactly as with MemoryStream.

Serialization Format#

By default, events are serialized as JSON for human readability. You can switch to pickle for full Python object fidelity:

1
2
3
4
5
6
7
from ag2.streams.redis import RedisStream, Serializer

# JSON (default) — readable in Redis tools
stream = RedisStream("redis://localhost:6379")

# Pickle — preserves exact Python types
stream = RedisStream("redis://localhost:6379", serializer=Serializer.PICKLE)

Pickle trusts everything in Redis

Deserializing pickle runs arbitrary code. With Serializer.PICKLE, anyone who can write to the stream's Redis keys or publish to its Pub/Sub channel can execute code in every process that reads the stream — the same as giving them a shell on those hosts.

Use pickle only when the Redis instance is fully trusted: not reachable from untrusted networks, protected by authentication (and ACLs if it is shared), and written to only by your own processes.

The default JSON serializer does not make an untrusted Redis safe either: the stream restores whatever it reads, so anyone who can write to it can forge history and messages for your agents. Lock Redis down with either format.

Cross-Process Communication#

Multiple RedisStream instances sharing the same id automatically receive each other's events via Redis Pub/Sub:

from uuid import UUID
from ag2.streams.redis import RedisStream

STREAM_ID = UUID("aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee")

# Process A
stream_a = RedisStream("redis://localhost:6379", id=STREAM_ID)

# Process B (separate Python process)
stream_b = RedisStream("redis://localhost:6379", id=STREAM_ID)

# Events sent on stream_a are received by subscribers on stream_b, and vice versa

Cleanup#

Always close the stream when done to release Redis connections:

await stream.close()

Custom events#

You can create your own custom events by subclassing BaseEvent. Because of its metaclass, field definitions automatically support value-based filtering in where clauses.

from ag2.events import BaseEvent

class PaymentProcessed(BaseEvent):
    amount: float
    status: str

# You can now filter by fields on your custom event:
@stream.where(PaymentProcessed.status == "success").subscribe()
def handle_success(event: PaymentProcessed):
    print(f"Payment processed: {event.amount}")

# And raise them via Context
async def process_payment(context: Context):
    await context.send(PaymentProcessed(amount=100.50, status="success"))