Deep Agents Integration¶

Pisama ingests LangChain Deep Agents traces through the DeepAgentsAdapter. Deep Agents is a structured multi-step agent runtime built on LangGraph that introduces three primitives:

Planning via the write_todos tool — the agent authors a todo list that becomes part of its state.
Context isolation via the task tool — the agent spawns a subagent that runs in an isolated context window.
Persistent memory via the LangGraph Memory Store — key-value state that survives across runs.

Deep Agents' own runtime provides in-the-loop guardrails. Pisama complements those with post-hoc forensic detection across the trace.

Install¶

Deep Agents is included with pisama-core — no extra dependency. The adapter parses state dicts directly, so you do not need to install langchain, langgraph, or deepagents on the Pisama side.

pip install pisama-core

Minimal Example¶

from deepagents import create_deep_agent
from pisama_core.adapters.deep_agents import DeepAgentsAdapter
from pisama_core.detection import run_detectors

# 1. Build your Deep Agent (your code — unchanged).
agent = create_deep_agent(
    tools=[web_search, read_file],
    instructions="You are a research assistant.",
)

# 2. Run the agent and collect the state checkpoints.
config = {"configurable": {"thread_id": "research-001"}}
agent.invoke({"messages": [{"role": "user", "content": "Summarize today's AI news."}]}, config)
states = [snap.values for snap in agent.get_state_history(config)]

# 3. Convert the trace with Pisama's adapter.
adapter = DeepAgentsAdapter(session_id="research-001", agent_name="researcher")
trace = adapter.parse_trace(states)

# 4. Run detection.
findings = run_detectors(trace)
for f in findings:
    print(f.detector, f.severity, f.summary)

The adapter is ingestion-only — it does not import the Deep Agents or LangGraph SDK, so it works against any state-dict payload that matches the documented shape. Pass whatever your runtime exposes (agent.get_state_history(), a custom checkpointer, or persisted JSON).

What the Adapter Captures¶

Deep Agents primitive	Pisama span
`write_todos` tool call	`TASK` span with `goals` attribute carrying the plan
`task` (subagent spawn)	Child `AGENT` span with `deep_agents.subagent.isolated_context=true`
Tool calls (other than `write_todos`)	`TOOL` span
AI / human / tool messages	`LLM` / `USER_INPUT` / `TOOL` spans
LangGraph state transitions	`state_delta:{node}` events on the root span

The root span is tagged Platform.LANGGRAPH with platform_version="deep-agents-v1" so any LangGraph-aware dashboards or detectors pick it up without a vendor-specific branch.

Detectors That Typically Fire on Deep Agents Failures¶

Deep Agents trades complexity for structure, which exposes a characteristic failure profile:

Detector	Why it fires on Deep Agents traces
`decomposition`	`write_todos` produces a plan that does not cover the user's intent, or has missing / redundant steps.
`coordination`	Supervisor / subagent handoffs drop information at the boundary.
`context`	Subagent spawned with insufficient context (isolated window can amplify this).
`overflow`	Main agent's context window blows up because subagent results are re-injected without summarization.
`derailment`	A subagent drifts from its assigned sub-task and produces output unrelated to the parent plan.
`loop`	The planner re-runs `write_todos` in circles when its own output fails downstream.
`completion`	The agent marks todos as `completed` when subagent output did not satisfy the goal.

See the Failure Modes guide for detector thresholds.

State Shape Reference¶

Each element in the states iterable is a dict with:

Key	Type	Description
`node`	`str`	Graph node that produced this state (e.g. `agent`, `tools`, `planner`, `supervisor`).
`messages`	`list`	LangChain messages (or plain `{type, content, tool_calls, ...}` dicts).
`todos`	`list`	Current todo list, typically `[{content, status}, ...]`. Populated by `write_todos`.
`subagents`	`list`	Subagent spawn events: `[{name, task, handoff, result}, ...]`.

Any other state keys are preserved in the state-delta events attached to the root span.