agentsclimarketplace

Building with deepagents

Skill tyroneross/build-loop/skills/building-with-deepagents

Build or refactor an agent using the OSS `deepagents` framework (SubAgent API, middleware, tool scoping, streaming, checkpointing). Use when the user wants a multi-agent/subagent system built with deepagents, or the code imports it. Not for `.claude/agents/*.md` definitions.From its SKILL.md

Install
npx -y skills add tyroneross/build-loop --skill building-with-deepagents

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

11.0 KB, as published. Nobody here has run it

<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <[email protected]> | SPDX-License-Identifier: Apache-2.0 -->

Building With DeepAgents (OSS)

This skill is for agents running on the open-source deepagents package (pip install deepagents) on top of LangChain / LangGraph, typically paired with a local model via langchain-ollama. It is not for the hosted LangChain/DeepAgents cloud product — if you find yourself reaching for LangSmith Platform or hosted subagents, stop: those features don't apply here. Prefer Arize Phoenix (self-hosted, OpenInference instrumentation) for observability in OSS deployments.

Read this skill before writing or modifying code that calls create_deep_agent, defines agent "roles", or streams LangGraph events.

When this applies

Triggers (check any):

  • Project imports deepagents (grep from deepagents)
  • Project has a multi-role agent concept (planner / researcher / writer / etc.)
  • Work touches tool binding, system prompts, focus/single-agent mode, or streaming of an existing DeepAgents app
  • Pain report mentions: tool-call hallucinations, "silent thinking" gaps, focus-mode prompt injection, per-agent model routing

Authoritative sources

Read these in order when you need more detail than this skill:

  1. references/api-quick-reference.md — the SubAgent TypedDict, create_deep_agent() signature, middleware stack, cached on disk
  2. references/anti-patterns.md — concrete bugs we've hit and what DeepAgents does / doesn't prevent
  3. Live source — the installed package is always ground truth. Find it with:
    python3 -c "import deepagents; print(deepagents.__file__)"
    
    Read graph.py (the assembly logic) and middleware/subagents.py (the SubAgent TypedDict + dispatch).
  4. GitHub: https://github.com/langchain-ai/deepagents — CHANGELOG for recent middleware additions
  5. LangGraph docs: https://langchain-ai.github.io/langgraph/ — streaming modes, checkpointing, interrupts. DeepAgents is a thin wrapper over LangGraph.
  6. Context7 MCP: mcp__plugin_context7_context7__resolve-library-id("deepagents") for on-demand doc lookups during build.

Core principles

Principle 1 — Per-subagent tool scoping is the hallucination fix

Small local models (< 14B) emit fabricated tool-call namespaces when given a large flat tool set for a prompt that needs none (e.g. repo_browser.write_todos when only write_todos was requested). The canonical fix is not validation after the fact — it's restricting each subagent's tool surface so the model has fewer options to invent against.

Do: pass subagents=[{"name": "planner", "tools": [], ...}] so the Planner only sees DeepAgents' built-in middleware tools. Don't: pass a single flat tools=[...] list and inject "You are the X agent" in the system prompt.

Evidence: middleware/subagents.py:65 — the SubAgent["tools"] field; middleware/subagents.py:347 — per-subagent tool resolution falling back to default_tools if unspecified.

Principle 2 — The middleware stack is always-on; treat it as free

DeepAgents injects by default (see graph.py:192-260):

  • TodoListMiddleware → provides write_todos
  • FilesystemMiddleware → ls, read_file, write_file, edit_file, glob, grep
  • SummarizationMiddleware → automatic context-window pruning
  • PatchToolCallsMiddleware → cleans up orphaned tool calls (missing ToolMessage)
  • SubAgentMiddleware → the task tool for main-agent delegation

You do NOT need to re-implement any of these. If you wrote your own summarization, thread-storage loader, or orphan-tool-call cleanup before finding this skill — delete it.

Principle 3 — Focus mode = scoped main agent, NOT prompt injection

"Single-agent" or "focus" mode (user pins one role, skips delegation) should be implemented by:

# Focus mode: main agent IS the role.
agent = create_deep_agent(
    model=role_model,
    tools=scoped_tools,           # only the role's allow-list
    system_prompt=role_prompt,     # the role's system_focus verbatim
    subagents=[],                  # no delegation — no `task` tool
)

Not by appending "\n\n## Single-Agent Mode\n\nYou are the X agent..." to a shared system prompt. The prompt-injection approach leaves the full flat tool surface accessible, which is exactly the hallucination failure mode Principle 1 addresses.

Principle 4 — Keep local optimizations that DeepAgents doesn't cover

DeepAgents is agnostic to:

  • Local-model cold-load (no Ollama awareness). Keep your warmup + heartbeat code.
  • SSE transport to a UI. DeepAgents emits LangGraph events; you still wire the HTTP.
  • Fast-path routing for trivial prompts. As of v0.4.x there is no "skip the graph" concept; future middleware additions could change this — re-check the changelog before removing a fast-path layer.
  • Tool-name validation as a defensive layer. DeepAgents' PatchToolCallsMiddleware only handles orphaned ToolMessage, not invalid tool names.

Don't delete these when migrating to DeepAgents' native features. They solve different problems.

The SubAgent spec — quick reference

from deepagents import create_deep_agent
from deepagents.middleware.subagents import SubAgent  # TypedDict

subagent: SubAgent = {
    "name": "researcher",                    # required
    "description": "Gathers web + file info",# required — main agent reads this to decide when to delegate
    "system_prompt": "You are RESEARCHER...",# required
    "tools": [web_search, scrape_url, ...],  # optional — if omitted, inherits main agent's tools
    "model": "provider:model-name",          # optional — per-agent model routing
    "skills": ["/path/to/skills/"],          # optional — markdown skills injection
    "interrupt_on": {"dangerous_tool": True},# optional — human-in-the-loop
    "permissions": [...],                    # optional — FilesystemPermission rules
}

agent = create_deep_agent(
    model=main_model,
    tools=[...],              # main agent's tools (subagents have their own)
    system_prompt="...",
    subagents=[subagent],     # ONE or more; ordering matters for main-agent selection
    checkpointer=...,         # pass a real Checkpointer, not MemorySaver, for durable threads
)

Recommended checkpointer

MemorySaver is volatile — threads vanish on restart. Use SqliteSaver for local apps:

from langgraph.checkpoint.sqlite import SqliteSaver
checkpointer = SqliteSaver.from_conn_string(".app/checkpoints.db")

Durable threads + resume-from-checkpoint come for free. You do not need a custom threads.py loader.

Streaming — match the UI's needs

DeepAgents exposes LangGraph's stream API verbatim. Pick the mode based on what the UI consumes:

ModeEmitsGood for
"updates"Node outputs (messages list) on each stepTool-event-level UI (our current bridge)
"messages"Token-by-token from the LLM nodeChat UI with per-token streaming
["updates", "messages"]BothThe usual answer — tool events and tokens
astream_events(version="v2")Typed on_tool_start, on_chat_model_stream, etc.Clean disambiguation without message-sniffing

If your current SSE loop does hasattr(msg, "tool_calls") or msg.type == "tool" branching, consider astream_events instead — cleaner event types, forward-compatible.

Local model gotchas

When paired with langchain-ollama:

  1. Always set a read timeout — default is infinite (None). A hung model blocks the UI forever:
    ChatOllama(model=..., client_kwargs={"timeout": httpx.Timeout(connect=5, read=600, write=30, pool=5)})
    
  2. Add .with_retry() for transient httpx.TransportError — common when a model is hot-unloaded mid-turn:
    llm.with_retry(stop_after_attempt=2, wait_exponential_jitter=True,
                   retry_if_exception_type=(httpx.TransportError, httpx.TimeoutException))
    
  3. num_ctx is sticky — changing it between calls triggers full KV-cache re-allocation in Ollama. Pick one per role, don't vary.
  4. Parallel tool calls are serialized by Ollama's OpenAI-compat endpoint even when the flag is set. Don't prompt the model to "call tools in parallel."
  5. Structured output (format: json) conflicts with tool calling — use one or the other per turn.

Anti-patterns we've encountered

  • Flat tool list + prompt-injected focus mode → tool-name hallucinations. See Principle 1.
  • Re-implementing summarization → SummarizationMiddleware is already in the default stack.
  • Using MemorySaver in production → threads vanish on restart. Swap to SqliteSaver.
  • Relying on agent.stream("updates") alone → tokens are invisible until a tool boundary. UI appears frozen. Use multi-mode or events.
  • Per-call num_ctx tuning → forces KV cache re-alloc. Fix num_ctx per role.
  • No .with_retry() → a single httpx.ReadError kills the turn.

Before you code

Run these checks:

  1. Read the installed source. cat $(python3 -c 'import deepagents, os; print(os.path.dirname(deepagents.__file__))')/middleware/subagents.py | head -100
  2. Check the version. pip show deepagents — know what API you have.
  3. Grep the repo for anti-patterns before adding new code:
    grep -rn "agent_focus_prompt\|## Single-Agent Mode\|flat tool" src/
    grep -rn "MemorySaver" src/   # durable threads?
    grep -rn "ChatOllama(" src/ | grep -v client_kwargs  # missing timeout?
    

Output (what "done" looks like)

A DeepAgents-based agent is well-built when:

  • Each role that exists conceptually has its own SubAgent spec with a scoped tools list
  • Focus/single-agent mode scopes the MAIN agent's tools — no prompt-level "You are the X agent" override
  • ChatOllama instances have client_kwargs={"timeout": ...} and .with_retry()
  • checkpointer is durable (SQLite/Postgres), not MemorySaver
  • astream_events(version="v2") or multi-mode streaming is used if the UI needs per-token updates
  • Local-only optimizations (warmup, heartbeat, fast-path, tool validator) are preserved — DeepAgents doesn't cover them
  • The tool-name validator is still present as a belt-and-braces guard against small-model fabrication

Related skills

  • build-loop:debug-loop — for investigating agent behavior (tool hallucinations, stuck streams)
  • prompt-builder:prompt-builder — for tightening per-role system_prompt text
  • calm-precision — if you're also building the UI side of the agent

Version 1.0 — 2026-04-13. Based on deepagents v0.4.x. Re-read the installed package source when the CHANGELOG mentions middleware or SubAgent changes.

Keep looking

Skills are one crate of 608,666. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.