Skip to content
/
Tier A A8 Cross-runtime harness

deepagentsjs

deepagentsjs · langchain-ai/deepagentsjs · ★ 1.3k · last commit 2026-05-22

Primitive shape
No installable primitives
00

Summary

deepagentsjs — Summary

deepagentsjs is the official TypeScript/JavaScript port of LangChain's Deep Agents Python library, described as a "1:1 compatibility" re-implementation using LangGraph.js. It ships as the deepagents npm package and exposes the same createDeepAgent() entry point, returning a LangGraph CompiledStateGraph with the same middleware stack: filesystem tools (read_file, write_file, edit_file, ls, glob, grep), planning via write_todos, sub-agent delegation via the task tool, and context management. The TypeScript version is notable for its advanced generic type system — InferDeepAgentType, InferSubagentByName, ResolveDeepAgentTypeConfig — ensuring full type inference through the agent's configuration at compile time. Unlike the Python counterpart, the JS package at version 1.10.2 has substantially more releases than the Python's 0.6.3, suggesting the TS version may be the more actively iterated primary target.

Compared to seeds, deepagentsjs occupies the same position as deepagents-langchain: closest to claude-flow in architecture (LangGraph-backed, sub-agent-capable, checkpointer-aware), but differs by living entirely in TypeScript npm-land with no Claude Code integration, no MCP server, and full type safety via Zod schemas.

01

Overview

deepagentsjs — Overview

Origin

Official TypeScript port of LangChain's deepagents Python library, maintained in a separate monorepo langchain-ai/deepagentsjs. Shares the same "batteries-included" brand and identical feature goals with the Python version. The libs/deepagents/src/index.ts header states: "A TypeScript port of the Python Deep Agents library for building controllable AI agents with LangGraph. This implementation maintains 1:1 compatibility with the Python version."

Philosophy

From the README:

"Deep Agents is an agent harness. An opinionated, ready-to-run agent out of the box. Instead of wiring prompts, tools, and context management yourself, you get a working agent immediately and customize what you need."

What's included (verbatim from README):

  • Planning — write_todos for task breakdown and progress tracking
  • Filesystem — read_file, write_file, edit_file, ls, glob, grep for working memory
  • Sub-agents — task for delegating work with isolated context windows
  • Smart defaults — built-in prompt and middleware that make these tools useful out of the box
  • Context management — file-based workflows to keep long tasks manageable

Stack Relationship

Uses @langchain/langgraph as the graph runtime and langchain as the base agent framework. Same three-layer stack as Python: LangGraph → LangChain create_agent → Deep Agents.

Security Model

Same as Python: "Deep Agents follows a 'trust the LLM' model. The agent can do anything its tools allow. Enforce boundaries at the tool/sandbox level."

02

Architecture

deepagentsjs — Architecture

Distribution

  • Type: npm package (deepagents on npm)
  • Version analyzed: 1.10.2
  • Install: npm install deepagents / pnpm add deepagents / yarn add deepagents
  • Required runtime: Node.js (inferred from @types/node dep), TypeScript 5.0+, pnpm workspace

Repository Layout (monorepo)

libs/
├── deepagents/           # Main npm package (deepagents)
│   └── src/
│       ├── index.ts      # Public exports
│       ├── agent.ts      # createDeepAgent() factory
│       ├── config.ts     # Settings, project root detection
│       ├── middleware/   # Middleware layers
│       ├── profiles/     # Harness profiles + provider profiles
│       ├── skills/       # Skills system
│       ├── backends/     # State + filesystem backends
│       ├── stream.ts     # createSubagentTransformer, streaming types
│       ├── types.ts      # Generic type utilities (DeepAgentTypeConfig, etc.)
│       └── values.ts     # Constants
├── acp/                  # Agent Communication Protocol package
├── providers/            # Provider-specific packages
├── standard-tests/       # Shared test utilities
└── evals/                # Evaluation suite

Key Dependencies

  • @langchain/langgraph ^1.3.0 — graph runtime
  • @langchain/core ^1.1.44 — base primitives
  • langchain ^1.4.0 — agent framework
  • zod ^4.3.6 — schema validation + typed result inference
  • fast-glob ^3.3.3 — file globbing
  • micromatch ^4.0.8 — glob pattern matching
  • yaml ^2.8.2 — YAML parsing

Build System

  • pnpm workspace (monorepo)
  • tsdown bundler for CJS + ESM dual output
  • TypeScript 6.0+ (note: very current TS version)
  • Biome linter/formatter (.oxlintrc.jsonc, .oxfmtrc.jsonc)

Config Files

  • pnpm-workspace.yaml — workspace definition
  • .env.example — provider API key variables
  • No project-level config for the harness itself; configuration is programmatic via createSettings()

Target AI Tools

Model-agnostic via LangGraph.js providers. Works with @langchain/anthropic, @langchain/openai, any @langchain/core chat model.

03

Components

deepagentsjs — Components

Primary Entry Point

Export Purpose
createDeepAgent(params?) Factory returning CompiledStateGraph; analogous to Python's create_deep_agent()

Type System (TypeScript-specific)

Type Purpose
DeepAgent<T> Complete agent type bag
DeepAgentTypeConfig Generic config for typing the agent
ResolveDeepAgentTypeConfig<T> Resolves merged default + user config
InferDeepAgentType<T> Infer the compiled agent type from params
InferDeepAgentSubagents<T> Infer sub-agent registry type
InferSubagentByName<T, Name> Lookup a sub-agent's type by string name
SupportedResponseFormat<T> Union of response formats
InferStructuredResponse<T> Infer structured output type from result schema

Profile System

Export Purpose
HarnessProfile Interface for per-model behavior overrides
HarnessProfileOptions Config shape for a harness profile
createHarnessProfile() Factory for harness profiles
registerHarnessProfile() Register a custom profile globally
getHarnessProfile() Retrieve a registered profile
EMPTY_HARNESS_PROFILE Default no-op profile
REQUIRED_MIDDLEWARE_NAMES Names of middleware that cannot be excluded

Streaming Types

Export Purpose
createSubagentTransformer() Transform raw LangGraph event stream into typed sub-agent events
DeepAgentRunStream Typed stream of agent events
SubagentRunStream Typed stream from a sub-agent invocation

Configuration

Export Purpose
createSettings(opts?) Build a Settings object from env + config
findProjectRoot() Detect project root from filesystem heuristics

Middleware (inferred from Python parity, src/middleware/)

Same middleware as Python: filesystem, subagents, async subagents, memory, skills, summarization, patch tool calls, permissions — all implemented in TypeScript.

No CLI Binary

The TS package ships no standalone CLI binary. There is no bin field in the deepagents package.json for a coding REPL equivalent (unlike Python's dcode). The .agents/ ACP protocol support is in the sibling libs/acp/ package.

05

Prompts

deepagentsjs — Prompts

Excerpt 1: Quickstart usage (from README)

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent();

const result = await agent.invoke({
  messages: [
    {
      role: "user",
      content: "Research LangGraph and write a summary in summary.md",
    },
  ],
});

Prompting technique: The framework provides a built-in system prompt (parallel to the Python BASE_AGENT_PROMPT). The user provides only a task description. The harness handles tool availability, context management, and behavioral guardrails automatically.

Excerpt 2: Customization example (from README)

import { ChatOpenAI } from "@langchain/openai";
import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: new ChatOpenAI({ model: "gpt-5", temperature: 0 }),
  tools: [myCustomTool],
  systemPrompt: "You are a research assistant.",
});

Prompting technique: The systemPrompt parameter appends user-defined instructions after the built-in base prompt. The base prompt defines core behavioral guardrails; the user prompt specializes the role.

Prompt Architecture

  • Base system prompt: TypeScript string constant in src/agent.ts (parallel to Python's BASE_AGENT_PROMPT)
  • Harness profiles can modify the base prompt for specific model/provider combinations
  • Skills add dynamic instructions at invocation time
  • Zod result schemas provide typed output contracts rather than prompt-based output instructions
  • No static markdown prompt files are shipped in the npm package
09

Uniqueness

deepagentsjs — Uniqueness

Differs from Seeds

Deepagentsjs is the TypeScript twin of deepagents-langchain, sharing the same architecture (hierarchical sub-agents, LangGraph runtime, pluggable middleware) but in the npm ecosystem. Among the seeds, it is closest to claude-flow in scope (code-first multi-agent harness with LangGraph backing), but differs in having zero MCP toolserver, no Claude Code integration, and a sophisticated TypeScript type system for type-safe agent configuration. Unlike openspec or spec-kit (both npm packages in the seed set), deepagentsjs ships no slash commands, hooks, or markdown specs — it is purely an agent runtime library.

Distinctive Position

  • Only npm harness library in this batch (vs. oh-my-agent, chorus, flue which are framework-agnostic multi-tool distributions)
  • Version 1.10.2 vs Python 0.6.3: The TS version has significantly more version increments, suggesting it is the primary iteration target
  • Generic type system: The most type-safe agent harness in the batch — InferSubagentByName<T, Name> provides compile-time sub-agent type lookup
  • ACP (Agent Communication Protocol): Includes an ACP sibling package for standardized agent-to-agent messaging — a protocol-first multi-agent communication design not seen in other batch members

Explicit Anti-Patterns

Same as Python version (inherited from shared system prompt).

Observable Failure Modes

  • No CLI binary: JS users who want a REPL must wait for a future release or use Python's dcode
  • TypeScript generics complexity: the type utilities (ResolveDeepAgentTypeConfig, FlattenSubAgentMiddleware) may be hard to reason about for non-advanced TS users
  • LangGraph.js is a peer dependency concern: version mismatches between @langchain/langgraph and the package can cause runtime issues
  • No standalone executable: the package requires an embedding application to run

Relationship to Sibling

Canonical Python version: deepagents-langchain. This package maintains 1:1 feature compatibility with it but is independently versioned and iterated.

04

Workflow

deepagentsjs — Workflow

Execution Flow (same as Python counterpart)

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: new ChatOpenAI({ model: "gpt-5" }),
  tools: [myCustomTool],
  systemPrompt: "You are a research assistant.",
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "Research LangGraph and write a summary in summary.md" }],
});

Phases (implicit in agent loop)

Phase Description Artifact
Instantiation createDeepAgent(params) builds CompiledStateGraph In-memory LangGraph object
Invocation agent.invoke(state) or agent.stream(state) Async generator of events
Planning Agent uses write_todos for task decomposition In-context todo list
Execution Agent reads/writes files, calls tools File changes, outputs
Sub-agent delegation Agent spawns task tool call to delegate subtask Sub-agent result
Compaction Summarization middleware compacts message history Compressed message thread
Termination Agent yields control when done or blocked Final state

Structured Output

Unlike the Python version, the TypeScript API has first-class structured output typing via Zod:

const result = await agent.invoke({ messages }, {
  responseFormat: z.object({ summary: z.string(), files_created: z.array(z.string()) })
});
// result.summary and result.files_created are fully typed

Approval Gates

  • Human-in-the-loop approval available through HumanInTheLoopMiddleware (same opt-in as Python)

ACP Integration

The libs/acp/ sibling package implements the Agent Communication Protocol — a standard for agent-to-agent message exchange that may affect how sub-agents communicate in multi-agent setups.

06

Memory Context

deepagentsjs — Memory and Context

Same Architecture as Python Counterpart

The TypeScript implementation maintains 1:1 compatibility with the Python version's memory model.

Short-term state

  • LangGraph CompiledStateGraph holds all conversation messages in state
  • Delta-channel optimization on messages: O(N) checkpoint growth
  • Tool outputs are part of the LangGraph message history

Long-term memory

  • MemoryMiddleware (TypeScript implementation in src/middleware/)
  • Backed by LangGraph.js BaseStore interface
  • Pluggable: in-memory, file-based, external store

Context Compaction

  • Summarization middleware compacts long conversation threads
  • Large tool outputs can be offloaded to disk (filesystem middleware)

TypeScript-Specific

  • createSettings() and findProjectRoot() — detect the LangGraph project root and read config from env/file
  • Settings are typed via the Settings interface
  • Checkpointer configuration is passed as typed params to createDeepAgent()

Persistence

  • LangGraph.js checkpointers: in-memory by default; PostgreSQL, SQLite via LangGraph.js integrations
  • Thread-based conversation scoping via LangGraph's thread_id
07

Orchestration

deepagentsjs — Orchestration

Multi-Agent Pattern

Same hierarchical sub-agent delegation as the Python version:

  • Parent agent uses task tool to delegate to sub-agents
  • Sub-agents have isolated context windows
  • Sub-agents can themselves delegate recursively
  • Typed: InferDeepAgentSubagents<T> gives compile-time sub-agent registry

Sub-Agent Type System (TypeScript-unique)

The TS version has a sophisticated generic type system for sub-agents:

type MyAgent = InferDeepAgentType<typeof agent>;
type Subagents = InferDeepAgentSubagents<MyAgent>;
type CodeSubagent = InferSubagentByName<MyAgent, "code">;

This enables type-safe sub-agent access patterns not possible in Python.

Stream Transformer

createSubagentTransformer() transforms raw LangGraph event streams into structured sub-agent events, enabling consumers to distinguish parent vs. sub-agent events in streaming output.

Isolation Mechanism

Same pluggable sandbox backends as Python. In-place by default; sandbox connectors for Daytona, E2B, etc. available through companion packages.

Multi-Model

Each createDeepAgent() accepts an independent model parameter. Sub-agents can use different models. No config-file-level routing.

Execution Mode

interactive-loop or one-shot depending on invocation pattern. Full LangGraph.js streaming support.

Crash Recovery

LangGraph.js checkpointing: resume from last checkpoint with same thread_id.

ACP Protocol

The libs/acp/ package in the monorepo implements the Agent Communication Protocol, enabling standardized agent-to-agent message exchange that may be used for sub-agent coordination in future versions.

08

Ui Cli Surface

deepagentsjs — UI/CLI Surface

CLI Binary

None. The deepagents npm package has no bin entry. It is a pure library package. There is no TypeScript equivalent of Python's dcode REPL (as of version 1.10.2 — this may change).

Local UI

None bundled. Same as Python: LangSmith Studio can connect to a running LangGraph.js server but is not bundled in this package.

IDE Integration

None. No .claude/ files, no Cursor config, no VS Code extension.

LangSmith Tracing

  • The langsmith package is listed as a peerDependency
  • LangGraph.js emits trace events compatible with LangSmith
  • Tracing enabled via environment variables (LANGCHAIN_TRACING_V2)

Developer Experience

  • Full TypeScript types including complex generics (InferDeepAgentType) — strong IDE autocomplete
  • Zod schemas for typed structured output
  • tsdown builds CJS + ESM dual output for broad compatibility
  • vitest for testing with UI mode available

Cross-Tool Portability

high — any LangGraph.js-compatible chat model (OpenAI, Anthropic, Google via @langchain provider packages).

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k
A8 Cross-runtime harness

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k
A8 Cross-runtime harness

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k
A8 Cross-runtime harness

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k
A8 Cross-runtime harness

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k
A8 Cross-runtime harness

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k
A8 Cross-runtime harness

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.