Chapter 11 · Streaming and subagent events

stream supports modes such as updates/messages/custom; delegated subtasks can also produce an independent stream.subagents event stream, rendering each subtask as its own channel.

Mechanics and design choices

The UI layer consumes typed events, with different modes mapping to different components. Deep Agents adds subagents events on top of standard streams, giving each delegated task its own handle; these are hidden by default and need explicit subscription.

Example

import os
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model=os.environ["MODEL_ID"],
    api_key=os.environ["DEEPAGENT_API_KEY"],
    base_url=os.environ.get("DEEPAGENT_BASE_URL", "https://api.openai.com/v1"),
)

import asyncio
from deepagents import create_deep_agent

agent = create_deep_agent(
    model=model,
    system_prompt="Answer in one line.",
)

async def run():
    async for chunk in agent.astream(
        {"messages": [{"role": "user", "content": "Say: ready."}]},
        config={"configurable": {"thread_id": "ch11"}},
        stream_mode=["messages", "custom"],
        version="v2",
    ):
        if chunk["type"] == "messages":
            token, meta = chunk["data"]
            if token.content:
                print(token.content, end="|", flush=True)

asyncio.run(run())

Run and verify

API key required. Acceptance: the terminal streams “ready” (or an equivalent one-line confirmation) without errors.

Pitfalls

Typed events are not the entire state sent to the frontend — filter sensitive fields first. Subagent events are hidden by default and subscribed to when needed.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What does messages mode yield?

2. Are subtask events visible by default?

3. Which mode for custom progress?

4. What to do with sensitive fields?

Hands-on exercises

1. Subscribe to updates and render progress.
2. Subscribe to subagent events and render subtasks separately.
3. Design a reconnect-and-deduplicate strategy.

Official references

• overview
• context-engineering

Verified on 2026-09-17 with Deep Agents 0.7.15.