convez.ai
AgenteAutomaçãoAvançado
nemori-ai

LangChain Dynamic Workflow

nemori-ai/langchain-dynamic-workflow

Orquestração determinística e resumível de multi-agentes em LangChain

Ver no GitHub
BomPluginScore · de 0 a 100

Orquestraçã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-workflow

1 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

Estrelas
18
Forks
0
Acompanhando
2
Saúde
50%
Último commit
há 5 meses
Versão
v0.3.0
Issues abertas
0
Contribuidores
1

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

CI Python License: MIT Ruff Types: pyright strict Status: alpha 0.3.0-dev

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 agentDynamic workflow
Who decides the next stepthe LLM, turn by turnthe script (deterministic code)
Where intermediate results livethe model's context windowscript variables
What reaches the caller's contextthe whole trajectoryonly the final result

Table of contents

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), and race() (best-of-N early exit: the first result satisfying win wins, 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), and corroborate (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 by run_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-budget idiom.
  • Observability by default — every agent / parallel / pipeline / race call emits a span to an opt-in sink (zero cost when unset).
  • Large fan-out batch map — ctx.batch_map streams an Iterable / AsyncIterable through 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 into LocalSubprocessSandbox for real subprocess build/test with exit-code gating, resource limits, and admission control.
  • Real git worktree + branch/PR — opt into GitWorktreeProvider and each file-mutating leaf runs in its own real git worktree / branch (its authoritative change is the real git diff), folded into an integration branch via real git merge and finalized as a PR.
  • In-run human sign-off — ctx.checkpoint pauses 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:

CommandEffect
runLaunch a registered workflow by name; returns a run_id immediately.
run_scriptLaunch an ad-hoc script the agent authors on the spot (the meta layer).
statusPoll a run and fetch its result (large results are offloaded behind a handle).
resumeRe-run against the same journal so completed leaves replay at zero cost.
cancelStop 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 SandboxManager into 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_rsa or rm -rf /some/path is 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 next agent() raises WorkflowBudgetExceededError. Drives the while ctx.budget.remaining() > T idiom.
  • on_span= — a sink receiving a span for every agent / parallel / pipeline call; resumed runs re-emit spans flagged cached=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.

DemoShows
flagship/deep_research_presetFlagship (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_authoredFlagship (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 Ctx handed to your script: agent / parallel / pipeline / race / dag / loop_until / batch_map / phase / log / budget / workflow / checkpoint. ctx.dag(nodes) runs a DagNode dependency 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 async fn over an Iterable / AsyncIterable through a bounded admission window (in-flight ≈ worker_count + queue_maxsize, decoupled from N), collecting list[T | None] in input order (a failing fn lands None, no abort) and auto-emitting transient count/ETA progress. ctx.race(candidates, *, win, win_tag="") runs RaceCandidate specs concurrently and returns a RaceResult for the first whose result satisfies win, 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 raises WorkflowSignoffRequired; the host resumes with the decision via run_workflow(resume=...) (the approve tool command on the host surface).
  • Cross-leaf reduce — pure helpers that fold the result lists parallel / pipeline hand back: survives (refute-by-default vote), dedup, reconcile (dual-blind reviewer reconciliation), corroborate (cross-leaf corroboration), plus the ReviewItem / Reconciled / Consensus result types. Also injected into the run_script namespace, so a host-authored script calls them by name without an import.
  • Race value types — RaceCandidate (one content-hashable agent-call spec, mirroring an agent() call) and RaceResult (the winner, its index, and .won). Both are injected into the run_script namespace, so a host-authored script constructs and reads them by name without an import.
  • Execution & isolation backends — SandboxManager plus the pluggable seams a host opts into: LocalSubprocessSandbox / local_subprocess_factory / ExecPolicy for real subprocess execution; WorktreeProvider / InMemoryWorktreeProvider and the real-git GitWorktreeProvider for per-leaf worktree isolation; and PullRequestProvider / PullRequestRef / LocalPullRequestProvider for PR finalization. The real backends are DANGEROUS opt-ins (real subprocess / git), not security sandboxes.
  • Persistence — WorkflowRunStore / RunSpec / InMemoryRunStore (default, zero-dep) and SqliteWorkflowStore (the optional [sqlite] extra), so a run resumes across processes.
  • Live observability sinks — run_workflow's keyword-only on_span / on_span_begin / on_leaf_event / on_command (all default no-op, out-of-band) plus the value types Span / SpanBegin / SpanKind / LeafEvent / CommandEvent and their *Sink aliases. For a detached background run the same sinks feed a bounded per-slot buffer — BgRunManager.event_sinks(run_id) (built from RunEventSinks, threaded into the detached run_workflow) captures the run's events as BufferedEvents, and BgRunManager.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 (the ctx.dag node spec, also injected into the run_script namespace) and the WorkflowDagError / WorkflowCycleError exceptions.
  • Batch progress — BatchMetrics (the ctx.batch_map count/ETA payload) and ProgressKind.BATCH / ProgressEntry.metrics.
  • Types and errors — Budget, JournalStore / InMemoryJournalStore / JournalRecord / race_key, the BgRunManager family (RunSnapshot, BufferedEvent, RunEventSinks), and the Workflow*Error exceptions (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.

License

MIT

Ver o original no GitHub

Bom para

Relacionados