Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Hybrid Workflow

Yanshi supports two complementary execution modes:

  • Deterministic DAG workflows through yanshi_core::Flow.
  • Agent-native loops through yanshi_agents::AgentRuntime and ReActAgent.

Hybrid workflow support connects those modes in both directions, plus a third bridge where an agent authors a DAG up front:

  • AgentNode embeds an agent inside a DAG.
  • WorkflowTool exposes a DAG workflow as an agent-callable tool.
  • Dynamic workflow — an LLM plans a whole DAG once, which is then compiled to a Flow and executed deterministically (see Dynamic Workflow).

Use the first two when most of a process should remain deterministic, recoverable, and inspectable, but one step needs agent reasoning or tool selection. Use dynamic workflow when the task is plannable up front but its shape varies per request — you pay one LLM “compile” and get a reproducible, governed run.

Architecture

Parent Flow
  -> deterministic nodes
  -> AgentNode
       -> ReActAgent / AgentRuntime
          -> ToolRegistry
             -> built-in tools
             -> MCP tools
             -> WorkflowTool
                  -> child Flow
  -> downstream deterministic nodes

The DAG owns ordering, dependencies, retries, checkpoints, and workflow state. The agent owns planning, tool calls, reflection, memory, and stop reasons for the autonomous step.

When To Use It

Use AgentNode when a DAG needs a non-deterministic decision point:

  • Route a case based on free-form user input.
  • Gather information with tools before returning a structured answer.
  • Delegate one node to a Skill-backed agent.
  • Preserve the rest of the workflow as a deterministic pipeline.

Use WorkflowTool when an agent should call stable automation:

  • Format, validate, transform, or enrich data through an existing DAG.
  • Keep deterministic business logic outside the prompt loop.
  • Let an agent decide when to invoke a workflow, while the workflow remains testable on its own.

Avoid hybrid execution when every step can be modeled as a normal DAG node. Plain workflows are easier to replay and reason about.

AgentNode

AgentNode wraps a ReActAgent as an AsyncNode.

Input:

KeyTypeRequired
messageFlowValue::Json(String)yes

Outputs:

KeyTypeMeaning
responseFlowValue::Json(String)final answer text
session_idFlowValue::Json(String)agent session id
stop_reasonFlowValue::Json(Object)serialized stop reason
agent_resultFlowValue::Json(Object)full serialized AgentRunResult

AgentNode treats non-success stop reasons as node execution failures. That lets the parent DAG retry or fail using the same control flow as any other node.

Minimal shape:

#![allow(unused)]
fn main() {
use std::collections::HashMap;
use std::sync::Arc;

use yanshi_agents::nodes::AgentNode;
use yanshi_agents::react::{ReActAgent, ReActConfig};
use yanshi_core::flow::{Flow, GraphNode, NodeType};
use yanshi_core::FlowValue;
use yanshi_memory::SessionMemory;
use yanshi_tools::ToolRegistry;
use serde_json::json;

let agent = ReActAgent::new(
  ReActConfig::new("gpt-4o").with_persona("Answer the workflow request."),
  Box::new(SessionMemory::default_window()),
  Arc::new(ToolRegistry::new()),
);

let agent_node = AgentNode::from_agent("assistant", agent);
let flow = Flow::new(vec![GraphNode {
  id: "agent".to_string(),
  node_type: NodeType::Standard(Arc::new(agent_node)),
  dependencies: Vec::new(),
  input_mapping: None,
  run_if: None,
  initial_inputs: HashMap::from([(
    "message".to_string(),
    FlowValue::Json(json!("Summarize this workflow state.")),
  )]),
}]);
}

WorkflowTool

WorkflowTool wraps a Flow as a normal agent tool.

Default parameter schema:

{
  "type": "object",
  "description": "Initial workflow inputs keyed by input name.",
  "additionalProperties": true
}

Each JSON property is converted into a FlowValue. Values that deserialize as explicit FlowValue are preserved; other values become FlowValue::Json.

Minimal shape:

#![allow(unused)]
fn main() {
use std::sync::Arc;
use std::time::Duration;

use yanshi_agents::tools::WorkflowTool;
use yanshi_tools::ToolRegistry;

let workflow_tool = WorkflowTool::new(
  "format_summary_workflow",
  "Run a deterministic child workflow that formats a summary.",
  child_flow,
)
.with_timeout(Duration::from_secs(10));

let mut registry = ToolRegistry::new();
registry.register(Arc::new(workflow_tool));
}

The tool output is a JSON serialization of the child workflow results. It is returned both as compatible string content and as a structured ToolOutputPart::Resource with a workflow://<tool_name> URI.

If any child workflow node returns an error, WorkflowTool returns an error ToolOutput. If the workflow exceeds its timeout, the tool call fails with a tool execution error.

Dynamic Workflow

AgentNode and WorkflowTool compose a fixed DAG with an agent. Dynamic workflow is the third bridge: the agent authors the DAG itself, once, then hands it back to the deterministic executor. This slides the run down the binding-time axis — many scattered runtime LLM decisions collapse into one up-front artifact (a Flow) that inherits retry / checkpoint / timeout / tracing / replay for free.

The flow:

goal (natural language)
  -> DynamicWorkflowAgent::plan        # one LLM call -> WorkflowPlan (JSON)
       WorkflowPlan { steps: [ WorkflowPlanStep { id, tool, params, depends_on } ] }
  -> compile_plan_to_flow              # plan -> yanshi_graph::Flow
       depends_on -> graph edges (independent steps run in parallel,
                     dependent steps receive their deps' outputs)
  -> FlowRunner::run                   # execute the Flow deterministically

The pieces live in yanshi_agents::dynamic:

  • WorkflowPlan / WorkflowPlanStep — the declarative, LLM-shaped plan ({ id, tool, params, depends_on }). Validated for duplicate ids + dangling dependencies; cycles are caught by the executor’s topological sort.
  • compile_plan_to_flow(plan, registry) — compiles the plan into a real Flow of tool calls. depends_on becomes graph dependencies, so the same dependency-ready scheduler that runs hand-written DAGs runs the authored one.
  • DynamicWorkflowAgent — wires an LLM planner to an injected Arc<dyn FlowRunner>. plan(goal) makes the planning call; run(goal) does plan -> compile -> execute. run_with_replan(goal, max_replans) (L1.1) is run with recovery: any step without a successful result — failed outright or blocked by an upstream failure — is left outstanding, already-succeeded steps are carried forward as precomputed pass-throughs (never re-run), and the planner is asked for a revised plan covering just what’s still missing, up to max_replans rounds. The FlowRunner injection (rather than a direct dependency on the executor) is what keeps yanshi-agents off yanshi-core; surfaces inject yanshi_core::CoreFlowRunner::concurrent(n).

CLI surface

yanshi workflow dynamic \
  --goal "Fetch the changelog and summarize the last release" \
  --model gpt-4o \
  --allow-domain raw.githubusercontent.com \
  --allow-path ./out \
  --max-concurrency 8 \
  [--dry-run] [--approve none|cli|auto-allow|auto-deny] [--profile dev|production] \
  [--replan <n>] [--output text|json]

One LLM planning call authors a WorkflowPlan, which is compiled to a Flow and executed concurrently via FlowExt. --replan <n> (W2.1, default 0 — disabled) switches this to run_with_replan: on a step failure the planner is asked for a revised plan covering only what’s still missing, up to n rounds; already-succeeded steps are never re-run. Every round’s new tool calls go through the same governed (and, when --approve is set, approval-wrapped) registry as round 0. Has no effect combined with --dry-run, since nothing executes there for a step to fail and trigger a revision — dry-run always shows just the round-0 plan.

Governance

Dynamic workflow is governed at exactly the seams the harness defines, so an agent-authored plan is not a security hole:

  • The built-in tool registry is restrictive by default — only FileTool + HttpTool are registered (no shell), behind a SandboxPolicy that denies every path / domain unless granted via --allow-path / --allow-domain.
  • --dry-run prints the authored plan and exits without executing any tool, so you can inspect what the LLM proposed before letting it run.
  • --approve != none routes every tool call through the Harness approval pipeline (wrap_registry): the planner and compiler share one Arc<ToolRegistry>, so the approved/audited registry is exactly the one the compiled Flow executes against.

Bare invocation runs unsupervised (U4.1). --profile defaults to dev, which (per the --approve doc above) resolves to --approve none when --approve itself is unset. That means yanshi workflow dynamic --goal ... --model ... with no other flags executes every LLM-authored tool call immediately, with no approval prompt — unlike yanshi harness run/chat, which default to --profile local (interactive cli approval) since U2.3. This asymmetry is intentional, not an oversight: workflow dynamic’s dev default predates U2.3 and existing scripts/users rely on bare invocation staying unsupervised for fast local iteration; changing it would be a breaking change to that established behavior. For CI or production use, always pass --profile local or --profile production explicitly (and layer --allow-path / --allow-domain restrictively) rather than relying on the bare-invocation default.

Runnable Example

Run the self-contained mock example:

cargo run -p yanshi-agents --example hybrid_workflow_agent

The example:

  1. Builds a child DAG with one deterministic formatting node.
  2. Wraps the child DAG as format_summary_workflow.
  3. Registers that workflow tool in an agent ToolRegistry.
  4. Embeds the agent in a parent DAG through AgentNode.
  5. Uses a mock model response to call the workflow tool.
  6. Prints the agent response and structured runtime result.

Expected high-level result:

Agent response:
"Hybrid answer: workflow summary for hybrid DAG + agent runtime"

Checkpoint And Resume

Hybrid workflows use the normal Flow checkpoint system.

When an AgentNode completes, its output is saved in workflow state. That includes the full agent_result, so checkpoint state preserves the agent step history:

  • observe step.
  • plan or tool call steps.
  • tool result steps.
  • reflection steps when enabled.
  • verification steps when enabled.
  • final answer step.

On resume, Flow skips nodes already completed in the checkpoint. If a downstream node failed after an AgentNode, resume continues after the agent node and does not repeat completed agent tool calls.

This behavior is covered by checkpoint recovery tests that assert:

  • checkpoint state preserves agent_result.steps.
  • resume does not re-execute an already completed agent-like node.
  • downstream nodes can retry after restoring the agent output from checkpoint state.

Tracing

Workflow tracing can attach a listener to Flow and capture nested agent details from agent_result.

The trace path is:

workflow trace
  -> node trace
     -> agent_result
        -> AgentTrace
           -> tool calls

Tool names beginning with mcp_ are marked as MCP calls by the tracing layer, allowing one trace to connect:

workflow -> agent node -> agent step -> tool call -> MCP tool

Failure Modes

Common failure points:

  • Missing message: AgentNode returns a node input error.
  • Non-string message: AgentNode returns a node input error.
  • Agent stop reason is not success: AgentNode returns a node execution error.
  • Child workflow node fails: WorkflowTool returns an error tool output.
  • Child workflow timeout: WorkflowTool returns a tool execution error.
  • Agent repeats or chooses the wrong tool: tune the agent persona, tool descriptions, and schemas.

Design Guidance

Keep deterministic work in DAG nodes. Give the agent a narrow decision boundary and expose stable work as tools.

Good hybrid boundary:

parse input -> validate account -> AgentNode decides next action -> deterministic fulfillment workflow

Good workflow-tool boundary:

agent investigates issue -> calls calculate_refund_workflow -> explains result

Risky boundary:

agent owns every workflow step, retry decision, and data transformation

That shape loses most of the benefits of deterministic workflow orchestration.

Current Boundaries

Current support includes:

  • AgentNode wrapping ReActAgent.
  • WorkflowTool wrapping Flow.
  • Workflow tool timeout support.
  • Agent result serialization into DAG output state.
  • Checkpoint resume that skips completed agent outputs.
  • Trace extraction from nested agent_result.
  • Dynamic workflow: WorkflowPlan -> compile_plan_to_flow -> FlowRunner, the DynamicWorkflowAgent LLM planner, and the yanshi workflow dynamic CLI with sandbox + approval governance.

Known follow-up work:

  • More declarative configuration for AgentNode and WorkflowTool.
  • A fixed DAG workflow example independent of agents.
  • More examples showing Skill-backed agents inside DAGs.
  • Richer tool metadata source classification across built-in, script, MCP, and workflow tools.
  • Dynamic-workflow plans that include AgentNode steps (an authored DAG with a non-deterministic node), and a PlanExecuteAgent that emits a Flow instead of running its plan sequentially.