deep agents/streaming

22 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Enable subgraph streaming with stream_subgraphs parameter

To receive subagent events in Deep Agents, enable the `stream_subgraphs` parameter when calling the stream method. This activates LangGraph's subgraph streaming to surface events from subagent execution.

Namespace structure for identifying event sources

When subgraphs streaming is enabled, each streaming event includes a namespace that identifies which agent produced it. The namespace is a tuple of node names and task IDs representing the agent hierarchy. An empty tuple `()` indicates the main agent. A subagent spawned by the main agent's task tool call has a namespace like `("tools:abc123",)`. Nested nodes within a subagent appear as deeper tuples like `("tools:abc123", "model_request:def456")`.

Stream subagent progress with stream_mode updates

Use `stream_mode="updates"` to track subagent progress as each step completes. This mode is useful for showing which subagents are active and what work they have completed. Events will show when the model runs, tools execute, and when subagents finish with their results.

Stream LLM tokens from main agent and subagents

Use `stream_mode="messages"` to stream individual tokens from both the main agent and subagents. Each message event includes metadata that identifies the source agent, allowing you to track token generation across the entire agent hierarchy.

Stream tool calls from subagents

When subagents use tools, you can stream tool call events to display what each subagent is doing. Tool call chunks appear in the `messages` stream mode, allowing real-time visibility into tool execution within subagent execution.

Emit custom progress events from subagent tools

Use `get_stream_writer()` in Python or `config.writer` in JavaScript inside your subagent tools to emit custom progress events. These custom updates allow you to send user-defined signals from inside subagent node execution, enabling fine-grained progress tracking.

Combine multiple stream modes for complete execution visibility

Multiple stream modes can be combined by passing a list like `stream_mode=["updates", "messages", "custom"]` to get a complete picture of agent execution. This allows simultaneous tracking of progress updates, LLM tokens, tool calls, and custom events.

v2 streaming format with unified chunk structure

Deep Agents use the v2 streaming format (requires LangGraph >= 1.1), which is the recommended approach. Every chunk in v2 format is a dict with `type`, `ns`, and `data` keys, providing a unified shape regardless of stream mode, number of modes, or subgraph settings. This eliminates nested tuple unpacking required in the v1 format. To enable v2, pass `version="v2"` when streaming.

v2 chunk structure and fields

In v2 streaming format, each chunk contains: `type` (the stream mode like "updates", "messages", or "custom"), `ns` (the namespace tuple identifying the agent, empty tuple for main agent, ("tools:<id>",) for subagents), and `data` (the payload). This unified structure replaces the v1 nested tuple format of (namespace, (mode, data)).

Track subagent lifecycle for monitoring

Monitor when subagents start, run, and complete by tracking namespace changes and status updates in streaming events. This allows you to understand the full execution timeline of subagent work alongside the main agent.

Event streaming as alternative to v2 streaming

For new applications, Deep Agents v0.6 introduces event streaming (event-streaming API) as the recommended approach over traditional stream modes. Event streaming provides separate iterators per projection (subagents, messages, tool calls, values) allowing independent consumption instead of branching on stream_mode chunks.

Example LangSmith configuration in env file

Example ~/.deepagents/.env configuration: LANGSMITH_TRACING=true LANGSMITH_API_KEY=lsv2_... DEEPAGENTS_CODE_LANGSMITH_PROJECT=deepagents-code

LangSmith tracing can be enabled via /auth

To log agent operations, tool calls, and decisions in LangSmith, run /auth and add your LangSmith API key. Tracing is enabled on the next launch.

Slash command /trace opens thread in LangSmith

The /trace command opens the current thread in LangSmith.

LangSmith tracing configuration with LANGSMITH_TRACING

Set LANGSMITH_TRACING=true in ~/.deepagents/.env to enable LangSmith tracing that persists across sessions.

LangSmith API key configuration

Set LANGSMITH_API_KEY in ~/.deepagents/.env to enable LangSmith tracing without needing per-shell exports.

DEEPAGENTS_CODE_LANGSMITH_PROJECT variable

Use DEEPAGENTS_CODE_LANGSMITH_PROJECT to name the project that receives Deep Agents Code's own traces. It defaults to 'deepagents-code' and is scoped to Deep Agents Code, not affected by LANGSMITH_PROJECT set in a project's .env.

Agent traces versus shell-command traces

Deep Agents Code produces two kinds of LangSmith traces: Agent traces are Deep Agents Code's own model calls, tool calls, orchestration, and middleware; Shell-command traces are traces emitted by code that Deep Agents Code runs in a shell, such as tests, scripts, or a local LangGraph app.

DEEPAGENTS_CODE_LANGSMITH_REPLICA_PROJECTS for dual-write

Set DEEPAGENTS_CODE_LANGSMITH_REPLICA_PROJECTS to mirror agent traces to a second LangSmith project. When set and tracing is active, each agent run is written to both the primary project and the named replica project.

LangSmith project status line in Deep Agents Code

When LangSmith tracing is configured, Deep Agents Code displays a status line with a link to the LangSmith project. In supported terminals, the link can be clicked to open it directly.

Example separate agent traces from app traces

Set DEEPAGENTS_CODE_LANGSMITH_PROJECT=deepagents-code in ~/.deepagents/.env for Deep Agents Code's own traces, and LANGSMITH_PROJECT=customer-support-agent in .env for application traces. This keeps them separate when Deep Agents Code debugs applications that also use LangSmith.

Example dual-write traces to second project

Set DEEPAGENTS_CODE_LANGSMITH_REPLICA_PROJECTS=team-shared in ~/.deepagents/.env to mirror agent traces to a shared team project in addition to the primary project.

Give your agent this brain