Hybrid Workflow
Yanshi supports two complementary execution modes:
- Deterministic DAG workflows through
yanshi_core::Flow. - Agent-native loops through
yanshi_agents::AgentRuntimeandReActAgent.
Hybrid workflow support connects those modes in both directions, plus a third bridge where an agent authors a DAG up front:
AgentNodeembeds an agent inside a DAG.WorkflowToolexposes a DAG workflow as an agent-callable tool.- Dynamic workflow — an LLM plans a whole DAG once, which is then compiled to
a
Flowand 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:
| Key | Type | Required |
|---|---|---|
message | FlowValue::Json(String) | yes |
Outputs:
| Key | Type | Meaning |
|---|---|---|
response | FlowValue::Json(String) | final answer text |
session_id | FlowValue::Json(String) | agent session id |
stop_reason | FlowValue::Json(Object) | serialized stop reason |
agent_result | FlowValue::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 realFlowof tool calls.depends_onbecomes graph dependencies, so the same dependency-ready scheduler that runs hand-written DAGs runs the authored one.DynamicWorkflowAgent— wires an LLM planner to an injectedArc<dyn FlowRunner>.plan(goal)makes the planning call;run(goal)does plan -> compile -> execute.run_with_replan(goal, max_replans)(L1.1) isrunwith 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 tomax_replansrounds. TheFlowRunnerinjection (rather than a direct dependency on the executor) is what keepsyanshi-agentsoffyanshi-core; surfaces injectyanshi_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+HttpToolare registered (no shell), behind aSandboxPolicythat denies every path / domain unless granted via--allow-path/--allow-domain. --dry-runprints the authored plan and exits without executing any tool, so you can inspect what the LLM proposed before letting it run.--approve != noneroutes every tool call through the Harness approval pipeline (wrap_registry): the planner and compiler share oneArc<ToolRegistry>, so the approved/audited registry is exactly the one the compiledFlowexecutes against.
Bare invocation runs unsupervised (U4.1).
--profiledefaults todev, which (per the--approvedoc above) resolves to--approve nonewhen--approveitself is unset. That meansyanshi workflow dynamic --goal ... --model ...with no other flags executes every LLM-authored tool call immediately, with no approval prompt — unlikeyanshi harness run/chat, which default to--profile local(interactivecliapproval) since U2.3. This asymmetry is intentional, not an oversight:workflow dynamic’sdevdefault 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 localor--profile productionexplicitly (and layer--allow-path/--allow-domainrestrictively) 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:
- Builds a child DAG with one deterministic formatting node.
- Wraps the child DAG as
format_summary_workflow. - Registers that workflow tool in an agent
ToolRegistry. - Embeds the agent in a parent DAG through
AgentNode. - Uses a mock model response to call the workflow tool.
- 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:AgentNodereturns a node input error. - Non-string
message:AgentNodereturns a node input error. - Agent stop reason is not success:
AgentNodereturns a node execution error. - Child workflow node fails:
WorkflowToolreturns an error tool output. - Child workflow timeout:
WorkflowToolreturns 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:
AgentNodewrappingReActAgent.WorkflowToolwrappingFlow.- 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, theDynamicWorkflowAgentLLM planner, and theyanshi workflow dynamicCLI with sandbox + approval governance.
Known follow-up work:
- More declarative configuration for
AgentNodeandWorkflowTool. - 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
AgentNodesteps (an authored DAG with a non-deterministic node), and aPlanExecuteAgentthat emits aFlowinstead of running its plan sequentially.