LangChain Dynamic Workflow
nemori-ai/langchain-dynamic-workflow
Orquestração determinística e resumível de multi-agentes em LangChain
Ver no GitHubOrquestração determinística e resumível de multi-agentes para LangChain deepagents, portando o conceito de Dynamic Workflows do Claude Code. Inverte o controle de fluxo: em vez de o LLM decidir passo a passo, um script determinístico governa loops, branches e paralelização, mantendo resultados intermediários em variáveis e isolando contextos de agentes.
Instalação
npx convez-ai nemori-ai/langchain-dynamic-workflow1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Tarefas fan-out pesadas com múltiplas pesquisas paralelas
- Workflows longos e multi-etapa que excedem o context window
- Pipelines que precisam de resume determinístico com token budget compartilhado
- Orquestração de agentes com paralelização, pipeline e race conditions
Veredito

Ferramenta técnica e madura (alpha 0.3.0) que resolve um problema real em workflows com LLM: evitar context bloat e não-determinismo invertendo controle de fluxo. Essencial para quem constrói sistemas multi-agente sofisticados em LangChain que precisam escalar e ser reproduzíveis.
README
A tradução para o português deste README ainda está na fila.
langchain-dynamic-workflow
English | 中文
Deterministic, scripted, resumable multi-agent orchestration for LangChain
deepagents— a community port of Claude Code's Dynamic Workflows.
A normal agent decides its control flow turn by turn: every loop, branch, and fan-out lives in the model's context window, burning tokens and accumulating intermediate state. langchain-dynamic-workflow inverts that — a deterministic orchestration script owns the control flow, and only leaf agent() calls delegate to deepagents, each running in an isolated, discarded context, so only the final result reaches the caller's context.
| Normal agent | Dynamic workflow | |
|---|---|---|
| Who decides the next step | the LLM, turn by turn | the script (deterministic code) |
| Where intermediate results live | the model's context window | script variables |
| What reaches the caller's context | the whole trajectory | only the final result |
Table of contents
- Why
- Highlights
- Architecture
- Installation
- Quickstart
- Host agents and the meta layer
- Resume, budget, and observability
- Examples
- Public API
- Development
- Status
- License
Why
Turn-by-turn control flow has three costs that compound as a task grows: the context window fills with intermediate reasoning, the trajectory is non-deterministic, and an interrupted run cannot resume without replaying the model. Inverting control flow addresses all three at once — the script holds the loops and branches, intermediate results stay in plain variables, and a content-hash journal makes a resumed run replay completed work at zero model cost.
Reach for it when a task is fan-out heavy (research N angles, grade M candidates), long and multi-step (the trajectory would otherwise overflow the context), or needs deterministic resume and a shared token budget across many sub-agents.
Highlights
- Deterministic control flow — loops, branching, and fan-out live in code, not in the model's head.
- Context quarantine — each leaf runs in a fresh, discarded deepagents context; only its folded result returns.
- Parallel, pipeline, and race fan-out —
parallel()(blocking barrier),pipeline()(no-barrier streaming), andrace()(best-of-N early exit: the first result satisfyingwinwins, in-flight losers are cancelled, the decision is journaled so resume reproduces the winner) over a shared concurrency gate. - Cross-leaf reduce — first-class helpers fold many leaf results:
survives(refute-by-default voting),dedup,reconcile(double-blind reviewer reconciliation), andcorroborate(judge-panel aggregation). - Resumable by content hash — a success-only journal replays completed leaves on resume at zero model cost.
- Cross-session persistence — wire the optional
[sqlite]store and a fresh process resumes a run byrun_id, replaying completed leaves at zero model cost (a superset of Claude Code's same-session-only resume). - Fail-loud determinism guard — a replay whose
agent()call sequence diverges raises rather than serving a positionally misaligned cache entry. - Shared token budget — one ceiling across every leaf, with a
loop-until-budgetidiom. - Observability by default — every
agent/parallel/pipeline/racecall emits a span to an opt-in sink (zero cost when unset). - Large fan-out batch map —
ctx.batch_mapstreams anIterable/AsyncIterablethrough a bounded admission window, so thousands of items never materialize thousands of tasks; results return in input order with automatic live count/ETA progress. - Background-run live drill-in — a detached background run is no longer opaque: its runtime events are buffered on its slot and a live turn replays them as the same per-leaf cards an inline run streams, so a host can drill into a running background job and report back each run's result on demand.
- Per-leaf sandbox isolation + real execution — execution leaves lease isolated backends (a
/shared/route enables explicit producer→consumer hand-off); opt intoLocalSubprocessSandboxfor real subprocess build/test with exit-code gating, resource limits, and admission control. - Real git worktree + branch/PR — opt into
GitWorktreeProviderand each file-mutating leaf runs in its own realgit worktree/ branch (its authoritative change is the realgit diff), folded into an integration branch via realgit mergeand finalized as a PR. - In-run human sign-off —
ctx.checkpointpauses a run for a human decision and resumes with it via a journal-driven gate (a superset of Claude Code, which accepts no input mid-run). - Meta layer — a host agent authors an orchestration script at runtime; an AST gate validates it before a single restricted
exec. - Strict engineering — Python 3.12, async-first, pyright
strict, and Layer 0/1/2 boundaries enforced by import-linter.
Architecture
Three layers, with a one-directional dependency (Layer 2 → Layer 1 → Layer 0) that import-linter enforces mechanically:
- Layer 0 — substrate: LangGraph durable execution (
@entrypoint+@task+ checkpointer). Provides resume, replay, and cached-result skip. - Layer 1 — orchestration runtime: the primitives —
agent(),parallel()(barrier),pipeline()(no barrier),race()(best-of-N early exit),phase(),log(),budget,workflow()— plus the two patches LangGraph lacks: a content-hash journal (LangGraph's native cache is index-based) and a fail-loud determinism guard (LangGraph treats determinism as convention). - Layer 2 — meta layer: an LLM authors a Python orchestration script; an AST gate validates it (no imports, dunders, or banned names) before a restricted-builtins
exec.
Leaf agent() calls resolve a named deepagent from a registry (roster) and invoke it as a @task, reusing deepagents' context quarantine and sandbox backends.
Installation
uv sync # install dependencies + create .venv
Python 3.12+. Dependency management via uv. The package is not yet published to PyPI; install it from a clone or as a git dependency.
Quickstart
Write an orchestration script (the ctx exposes the primitives), register your leaf agents in a roster, and run it. A leaf is any runnable whose state has a messages key — typically a deepagents.create_deep_agent(...):
import asyncio
from deepagents import create_deep_agent
from langchain_dynamic_workflow import Ctx, Roster, run_workflow
async def main() -> None:
# 1. Register leaf agents by name (build-time wiring; the agent never does this).
roster = Roster().register(
"researcher",
create_deep_agent(model="anthropic:claude-haiku-4-5"),
description="Researches one topic",
)
# 2. The orchestration script owns the control flow; only leaf agent() calls
# delegate to deepagents. parallel() is a blocking barrier; a failed leaf
# lands as None (filter the holes) and never aborts the barrier.
async def orchestrate(ctx: Ctx) -> str:
ctx.phase("research")
findings = await ctx.parallel(
[
lambda t=topic: ctx.agent(f"Research {t}", agent_type="researcher")
for topic in ("batteries", "solar", "wind")
]
)
surviving = [f for f in findings if f is not None]
return f"synthesized {len(surviving)} findings: " + " | ".join(surviving)
# 3. Run it. Only the final result reaches you — not the whole trajectory.
result = await run_workflow(orchestrate, roster=roster)
print(result)
asyncio.run(main())
Host agents and the meta layer
To let a host agent drive workflows in the background, attach create_workflow_middleware(roster, workflows=...) to a host create_deep_agent. The agent then controls runs through a single workflow tool:
| Command | Effect |
|---|---|
run | Launch a registered workflow by name; returns a run_id immediately. |
run_script | Launch an ad-hoc script the agent authors on the spot (the meta layer). |
status | Poll a run and fetch its result (large results are offloaded behind a handle). |
resume | Re-run against the same journal so completed leaves replay at zero cost. |
cancel | Stop an in-flight run. |
A run executes in the background and a completion notice is injected before the host's next turn, so launching never blocks the conversation.
The meta layer (run_script). The host writes an async def orchestrate(ctx, args) and submits the source. It passes an AST security gate (no imports, dunder access, banned builtins, or str.format injection) and then runs under a restricted-builtins namespace via a single, confined exec. A rejected script returns its exact violations so the host can fix them and resubmit. Build-time code can do the same programmatically with run_workflow_from_source(source, roster=...).
Security boundary. The gate plus the restricted namespace stop an honest model's slip — they are not a security sandbox, and a determined adversarial script can still escape. Submit only scripts the host authors itself; for adversarial input, run the engine behind an out-of-process isolation backend.
⚠️ Real shell execution is a DANGEROUS opt-in — NOT a security sandbox
By default, execution leaves use the offline in-memory backend and run no real shell. You can opt a
SandboxManagerinto a real local-subprocess backend (SandboxManager(sandbox_factory=local_subprocess_factory(ExecPolicy(...)))), which runs each leaf's shell command in a private per-leaf temporary directory. This is not a security sandbox — read this before enabling it.What a command CAN still do — it runs as you, on your host:
- Read and write any host path via absolute paths. The per-leaf temp directory bounds only the default working directory, not the reachable filesystem.
cat ~/.ssh/id_rsaorrm -rf /some/pathis fully within reach.- Use the network with your user's permissions — exfiltrate, download, connect anywhere your account can.
- Consume host resources beyond the best-effort POSIX
rlimits — the limits are a runaway guard, not a hard cgroup-grade containment.What it DOES guarantee (resilience, not confinement):
- A private temp working directory per leaf — no accidental execution in the engine's own directory.
- The engine file APIs stay rooted, with
..traversal rejected.- A bounded effective timeout with best-effort process-group kill (SIGTERM → grace → SIGKILL on POSIX).
- Bounded combined stdout+stderr output (flagged when truncated).
- A bounded count of concurrent executions.
What it deliberately does NOT provide (deferred sharp edges):
- Hard filesystem confinement (container / chroot / nsjail / firejail).
- Network-egress blocking.
- cgroup-grade CPU / memory / process containment.
- Strong orphan cleanup for processes that deliberately daemonize or escape the process group.
The single biggest risk is false security. A per-leaf temp working directory looks isolated but is not. Never run untrusted or adversarial commands through it. For those, run the engine behind an out-of-process isolation backend (a container).
Windows is weaker still: no
rlimits and no honest resource/security posture — only a timeout, an output cap, a temp working directory, best-effort termination, and the concurrency bound.
Resume, budget, and observability
run_workflow takes a few keyword-only knobs that compose:
journal=— pass the same journal store across calls for cached-result resume: completed leaves replay at zero model cost, and the determinism guard verifies the call sequence has not diverged.budget=— a shared token ceiling for all leaves; once spent, the nextagent()raisesWorkflowBudgetExceededError. Drives thewhile ctx.budget.remaining() > Tidiom.on_span=— a sink receiving a span for everyagent/parallel/pipelinecall; resumed runs re-emit spans flaggedcached=True.sandbox_manager=— leases an isolated execution backend per leaf that needs one; pure-reasoning leaves allocate nothing.
Examples
The 19 feature demos under examples/features/ each isolate one mechanism and run offline with no API key (deterministic fake models). The two flagships under examples/flagship/ carry the real end-to-end path: offline by default, they light up live OpenRouter leaves with native web search + prompt caching when you opt in. To drive the real path, install the demo extras with uv sync --group example, put OPENROUTER_API_KEY and the LANGSMITH_* settings in a local .env, then set LDW_DEMO_REAL_MODEL (defaults to anthropic/claude-opus-4.8; set it to any OpenRouter slug to override). The full taxonomy and the authoritative index of every demo live in examples/AGENTS.md.
| Demo | Shows |
|---|---|
flagship/deep_research_preset | Flagship (real model): a host drives the registered deep_research workflow — parallel search → extract → adversarial verify → synthesize, with native web search + prompt caching. |
flagship/deep_research_authored | Flagship (real model): a host authors the deep-research script live and runs it via run_script (AST gate happy path), same web-search + caching leaf stack. |
The 19 offline feature demos (one mechanism each, no API key) and the full taxonomy live in examples/AGENTS.md.
# any offline feature demo:
uv run python -m examples.features.parallel
# a flagship, offline by default:
uv run python -m examples.flagship.deep_research_preset
# fully real end-to-end (live OpenRouter host + leaves):
LDW_DEMO_REAL_MODEL=anthropic/claude-opus-4.8 uv run python -m examples.flagship.deep_research_preset
Public API
The stable, public surface is exported from the package root and follows semantic versioning from 0.1.0:
- Library core —
run_workflow: the developer / build-time entry. - Meta layer —
compile_workflow_source/run_workflow_from_source/extract_meta: compile and run an LLM-authored source string through the AST gate. - Registries —
Roster/RosterEntry,WorkflowRegistry. - Host-facing —
create_workflow_tool,create_workflow_middleware,skills_path/skill_files. - Primitives — exposed on the
Ctxhanded to your script:agent/parallel/pipeline/race/dag/loop_until/batch_map/phase/log/budget/workflow/checkpoint.ctx.dag(nodes)runs aDagNodedependency graph in topological order (independent-failure tracking);ctx.loop_until(...)is a bounded sequential loop helper.ctx.batch_map(items, fn, *, max_in_flight=None, total=None, label="batch_map")maps one asyncfnover anIterable/AsyncIterablethrough a bounded admission window (in-flight ≈worker_count + queue_maxsize, decoupled from N), collectinglist[T | None]in input order (a failingfnlandsNone, no abort) and auto-emitting transient count/ETA progress.ctx.race(candidates, *, win, win_tag="")runsRaceCandidatespecs concurrently and returns aRaceResultfor the first whose result satisfieswin, cancelling the rest; the decision is journaled (content-hash,win_tag-keyed) so resume reproduces the winner and dispatches nothing.ctx.checkpoint(ask, *, tag="")pauses the run for a human sign-off — a journal-driven gate that raisesWorkflowSignoffRequired; the host resumes with the decision viarun_workflow(resume=...)(theapprovetool command on the host surface). - Cross-leaf reduce — pure helpers that fold the result lists
parallel/pipelinehand back:survives(refute-by-default vote),dedup,reconcile(dual-blind reviewer reconciliation),corroborate(cross-leaf corroboration), plus theReviewItem/Reconciled/Consensusresult types. Also injected into therun_scriptnamespace, so a host-authored script calls them by name without an import. - Race value types —
RaceCandidate(one content-hashable agent-call spec, mirroring anagent()call) andRaceResult(the winner, its index, and.won). Both are injected into therun_scriptnamespace, so a host-authored script constructs and reads them by name without an import. - Execution & isolation backends —
SandboxManagerplus the pluggable seams a host opts into:LocalSubprocessSandbox/local_subprocess_factory/ExecPolicyfor real subprocess execution;WorktreeProvider/InMemoryWorktreeProviderand the real-gitGitWorktreeProviderfor per-leaf worktree isolation; andPullRequestProvider/PullRequestRef/LocalPullRequestProviderfor PR finalization. The real backends are DANGEROUS opt-ins (real subprocess /git), not security sandboxes. - Persistence —
WorkflowRunStore/RunSpec/InMemoryRunStore(default, zero-dep) andSqliteWorkflowStore(the optional[sqlite]extra), so a run resumes across processes. - Live observability sinks —
run_workflow's keyword-onlyon_span/on_span_begin/on_leaf_event/on_command(all default no-op, out-of-band) plus the value typesSpan/SpanBegin/SpanKind/LeafEvent/CommandEventand their*Sinkaliases. For a detached background run the same sinks feed a bounded per-slot buffer —BgRunManager.event_sinks(run_id)(built fromRunEventSinks, threaded into the detachedrun_workflow) captures the run's events asBufferedEvents, andBgRunManager.buffered_events(run_id)returns them for a live turn to replay; the buffer is transient telemetry (never journaled / replayed, isolation preserved). - Topological fan-out + nesting —
DagNode(thectx.dagnode spec, also injected into therun_scriptnamespace) and theWorkflowDagError/WorkflowCycleErrorexceptions. - Batch progress —
BatchMetrics(thectx.batch_mapcount/ETA payload) andProgressKind.BATCH/ProgressEntry.metrics. - Types and errors —
Budget,JournalStore/InMemoryJournalStore/JournalRecord/race_key, theBgRunManagerfamily (RunSnapshot,BufferedEvent,RunEventSinks), and theWorkflow*Errorexceptions (WorkflowScriptError,WorkflowSignoffRequired,WorkflowCheckpointError, and the rest).
Public signatures are stable; new parameters are added keyword-only with defaults. Names prefixed with _ (modules and members) are internal and may change without notice.
Development
uv sync # install dependencies + create .venv
uv run pytest # run tests (coverage gate, line >= 85%)
uv run ruff check . # lint
uv run ruff format . # format
uv run pyright # type check (strict)
uv run lint-imports # verify the Layer 0/1/2 architecture boundaries
Status
0.3.0 released (tagged v0.3.0); 0.4.0 in progress — not yet published to PyPI. All three layers are implemented and the public API is stable. The v0.3.0 line landed cross-leaf reduce (M1), race (M2), parallel-run observability (M3.5), cross-session persistence (M3), real local execution (M5), in-run human sign-off (M4), real git worktree + branch/PR (M6), and topological/DAG fan-out + deep nesting (M7). The v0.4.0 line has landed batch ergonomics (ctx.batch_map, E) and background-run transport — live drill-in + result report-back (v0.4.0 M3). See CHANGELOG.md for the full log.