Skip to content

ADR: Deep Agent Dependency Management

Status: Accepted
Date: January 16, 2026
Authors: Development Team
Reference: docs/specs/spec_deep_agent_adoption_v1.md

Context

We are adopting the Deep Agent pattern from LangChain/LangGraph to replace our current GlobalPlannerNode + agent_execution_node pattern. This requires adding the deepagents package as a dependency.

The deepagents package provides: - write_todos / read_todos tools for explicit multi-step planning - task() tool for subagent/skill delegation with context isolation - Filesystem middleware for large artifact management - Backend abstractions for workspace storage

Decision

Pin deepagents to exact version (currently 0.3.6).

Why Exact Version Pinning?

  1. Stability: LangChain ecosystem evolves rapidly; minor versions can introduce breaking changes
  2. Reproducibility: Same behavior across dev, staging, and production environments
  3. Controlled upgrades: Forces explicit review of changelogs before upgrading

Dependency Entry

# In pyproject.toml
"deepagents==0.3.6",  # Pin exact version - see docs/adr/adr_deep_agent_dependency.md

Upgrade Policy

Before Upgrading

  1. Review changelog: Check langchain-ai/deepagents releases for breaking changes
  2. Test in isolated branch: Create test/deepagents-upgrade-X.Y.Z branch
  3. Run full test suite: Including integration and E2E tests
  4. Run benchmarks: Verify no performance regression
  5. Update this ADR: Document version change and any migration steps

Upgrade Steps

# 1. Create test branch
git checkout -b test/deepagents-upgrade-0.3.7

# 2. Update version in pyproject.toml
# Change: "deepagents==0.3.6" -> "deepagents==0.3.7"

# 3. Update lock file
uv lock

# 4. Rebuild Docker
docker compose build backend

# 5. Run tests
docker compose exec backend pytest -vv

# 6. Run benchmarks
docker compose exec backend pytest tests/performance/ -vv

# 7. If all pass, create PR
# 8. Require Tech Lead approval for merge

Major Version Upgrades

For major version changes (e.g., 0.x → 1.x):

  1. Requires Tech Lead approval before starting
  2. Create migration plan documenting API changes
  3. Extended testing period (minimum 1 week in staging)
  4. Rollback plan documented and tested

Rollback Procedure

If issues found after upgrading:

  1. Revert pyproject.toml to previous version
  2. Run uv lock to regenerate lock file
  3. Rebuild Docker images: docker compose build backend
  4. Redeploy: Follow standard deployment procedure
  5. Document issue in this ADR under "Known Issues"

Consequences

Positive

  • (+) Explicit control over dependency version
  • (+) Reproducible builds across environments
  • (+) Forced review of changes before adoption

Negative

  • (-) Manual effort to stay updated
  • (-) May miss security patches if not monitoring
  • (-) Need to track upstream releases

Mitigations

  • Set up GitHub Dependabot or Renovate to alert on new versions
  • Quarterly review of dependency versions (add to tech debt backlog)
  • Subscribe to LangChain changelog: https://changelog.langchain.com

Version History

Version Date Notes
0.3.6 Jan 16, 2026 Initial adoption

Known Issues

None currently documented.

References