How to Use Deep Agents for Open Source: A Practical Walkthrough

I was drowning in a mess of Python scripts trying to automate open source repository maintenance. I needed something that could triage issues, update documentation, run tests, and submit PRs — all in one long-running session without losing context halfway through. Every agent framework I tried either choked on multi-step tasks or required me to wire up my own context management, planning, and subagent delegation from scratch. Then I found Deep Agents, LangChain's open source agent harness built specifically for long-horizon work. Here's what I learned getting it up and running.

The Problem That Led Me Here

I maintain a mid-sized open source project with a growing backlog of stale issues, outdated docs, and failing CI checks. I wanted an agent that could:

Read through open issues and categorize them
Update documentation based on recent code changes
Run test suites and fix simple failures
Draft PRs with proper descriptions

Simple prompt-and-response tools kept losing track of where they were. They'd start triaging issues, then forget the original plan when the conversation got long. I needed something with built-in planning, persistent memory, and the ability to delegate subtasks without everything collapsing into context window chaos.

Getting Started: Installation

Deep Agents is available as both an SDK and a CLI tool called dcode. I started with the CLI since I wanted to test it quickly on my repo.

curl -LsSf https://langch.in/dcode | bash

This installs dcode on your system. You can also install it via pip if you prefer:

pip install deepagents

The first surprise: the CLI install was smooth, but I initially didn't realize I needed to configure my model provider separately. Deep Agents is model-agnostic, which is great, but it means you have to bring your own API keys. I set up my OpenAI key first:

export OPENAI_API_KEY="sk-..."

You can also use Anthropic, local models via Ollama, or any provider that supports tool calling. I later switched to Claude for coding tasks and found it worked just as well — the model swap was seamless, which is one of Deep Agents' real strengths.

Running My First Task: Issue Triage

I pointed dcode at my open source repo and gave it a concrete task:

dcode

Then in the interactive session:

> Go through the open issues in this repository. Categorize each one as bug, feature request, question, or stale. Add the appropriate label to each issue. For any issue that's been inactive for 90+ days, add a "stale" label and post a polite comment asking if it's still relevant.

What happened next impressed me. Deep Agents didn't just start blindly calling the GitHub API. It created a plan first — breaking the task into steps like "fetch open issues," "analyze each issue," "determine category," "apply labels," and "handle stale issues." This planning step is built into the harness, and you can watch it decompose the objective before execution begins.

The agent then worked through the issues one by one. When it hit a rate limit on the GitHub API, it backed off and retried — something I didn't have to code myself. It triaged 47 issues in about 20 minutes, which would have taken me an entire afternoon.

Context Management: The Real Differentiator

Here's where Deep Agents shines compared to other agent setups I've used. Long-running tasks generate massive conversation histories. Most agents either crash when they hit the context limit or start "forgetting" earlier steps.

Deep Agents handles this with built-in middleware that:

Compresses conversation history — older messages get summarized automatically
Offloads large tool results to disk — instead of keeping a huge API response in context, it writes it to the virtual filesystem and keeps a reference
Uses prompt caching — reduces latency and cost on repeated patterns

I watched this in action when my agent was processing those 47 issues. After about issue 15, the context was getting large. Deep Agents compacted the earlier conversation, keeping a summary of what had already been triaged while freeing up space for the remaining issues. The agent never lost track of its progress.

Subagents: Delegating Parallel Work

For my next task, I wanted to update documentation across multiple files based on recent code changes. This is where subagents came in handy.

Deep Agents lets you spawn subagents for independent subtasks, each with its own isolated context window. This means one subagent can work on the API reference docs while another updates the README, and neither one's context bleeds into the other.

In the SDK, this looks like:

from deepagents import DeepAgent

agent = DeepAgent(model="claude-sonnet-4-20250514")

result = agent.invoke(
    "Update all documentation files to reflect the changes in the v2.3 release. "
    "Work on the README, API reference, and changelog in parallel using subagents."
)

The main agent decomposed this into three subtasks, spawned subagents for each, and coordinated the results. Each subagent had its own context window, so they didn't interfere with each other. The main agent waited for all three to complete, then gave me a summary.

One gotcha: subagents share the same virtual filesystem by default, so if two subagents try to edit the same file simultaneously, you can get conflicts. I learned this the hard way when two subagents both tried to update the changelog at once. The solution is to be specific about file ownership when delegating — tell each subagent exactly which files it owns.

The Virtual Filesystem and Persistent Memory

Deep Agents includes a virtual filesystem that persists across sessions. This is where it stores system prompts, skills, and long-term memory. For open source work, this is incredibly useful.

After my first session triaging issues, the agent had learned patterns about my repository — which labels exist, what the naming conventions are, how issues are typically structured. In my next session, it recalled this information without me having to explain it again.

You can also define skills — reusable behaviors the agent can load on demand. I created a skill for "PR review" that includes specific instructions about my project's coding standards and review checklist:

# In config.toml
[[skills]]
name = "pr-review"
description = "Review pull requests following project conventions"
prompt = """Review this PR against our coding standards:
- All public functions must have docstrings
- Tests required for new features
- No breaking changes without a deprecation path
- Follow the existing code style in each module"""

Now when I ask the agent to review a PR, it loads this skill automatically.

Human-in-the-Loop: Staying in Control

For open source work, I don't want an agent running unchecked on my repository. Deep Agents supports human-in-the-loop approval for sensitive operations.

I configured it to require approval before:

Pushing commits
Creating PRs
Posting comments on issues
Modifying CI configuration

# config.toml
[approval]
require_approval = ["git_push", "git_commit", "github_comment", "github_pr_create"]

When the agent wants to perform one of these actions, it pauses and shows me what it's about to do. I can approve, edit, or reject. This saved me from an embarrassing moment when the agent was about to comment "This issue appears to be stale and inactive" on an issue that was actually a critical bug someone was actively working on.

Using the SDK for More Control

The CLI is great for quick tasks, but for more complex workflows, the SDK gives you finer control. Here's a script I wrote to automate my weekly open source maintenance:

from deepagents import DeepAgent
from langgraph.checkpoint.memory import MemorySaver

# Set up persistence for cross-session memory
checkpointer = MemorySaver()

agent = DeepAgent(
    model="claude-sonnet-4-20250514",
    checkpointer=checkpointer,
    skills=["issue-triage", "doc-updater", "pr-review"],
)

# Run weekly maintenance
result = agent.invoke(
    "Perform weekly maintenance: "
    "1) Check for stale issues older than 60 days and label them. "
    "2) Review open PRs that have been waiting more than 7 days. "
    "3) Update the changelog with any merged PRs from this week. "
    "4) Run the test suite and report any failures.",
    config={"configurable": {"thread_id": "weekly-maintenance-2024-01-15"}}
)

The thread_id lets me resume this conversation later. If the agent gets interrupted (which happened once when I lost my network connection), I can pick up where it left off using the same thread ID.

Tracing with LangSmith

Deep Agents integrates natively with LangSmith for tracing. This was a lifesaver for debugging. When my agent went off the rails during a doc update task, I could open LangSmith and see exactly which step went wrong — it had misinterpreted a code comment as a public API method and wrote documentation for something that didn't exist.

To enable tracing:

export LANGSMITH_API_KEY="lsv2_..."
export LANGSMITH_TRACING=true

The traces show you every tool call, every model invocation, and every decision the agent made. It's not free (LangSmith has usage-based pricing), but for debugging complex agent behavior, it's worth it.

Practical Tips and Honest Limitations

After using Deep Agents for a few weeks on my open source project, here's what I've learned:

Tips:

Start with the CLI before writing SDK code. It's faster to iterate and you'll learn what the agent can do naturally.
Be very specific in your task descriptions. "Update the docs" is too vague. "Update the API reference in docs/api.md to reflect the new parameters added to the process_data function in src/processor.py" works much better.
Use skills for repetitive tasks. If you find yourself giving the same instructions over and over, extract them into a skill.
Always configure human-in-the-loop for any action that modifies your public repository. Agents will make mistakes.
Watch your API costs. Long-running tasks with subagents can burn through tokens quickly. Monitor your usage.

Limitations:

The planning system sometimes over-decomposes simple tasks. I've seen it break "fix this typo" into five separate steps, which is wasteful.
Subagent coordination isn't perfect. If subagents need to share information, you have to design that into your task description explicitly.
The documentation is still maturing. I had to read source code to understand some configuration options that weren't clearly documented.
It's opinionated, which is mostly good, but means fighting the framework if your workflow doesn't match its assumptions. If you just want a simple agent without planning or subagents, Deep Agents is overkill — use LangChain's create_agent instead.
MCP server integration works but can be flaky. I had issues connecting to a GitHub MCP server that would occasionally time out.

Despite these limitations, Deep Agents has become my go-to for complex open source maintenance tasks. The built-in context management alone saves me from the "agent amnesia" problem that plagued my earlier attempts. And the fact that it's open source means I can inspect, modify, and contribute back when something doesn't work the way I need it to.

How to use Deep Agents for open source