Skip to content

LightFlow

weego edited this page Nov 15, 2026 · 2 revisions

LightFlow

LightFlow is the deterministic workflow layer introduced in LightAgent v0.8.0. It chains one or more LightAgent instances into explicit named steps, so application code can express repeatable multi-step execution without adding a heavy orchestration dependency.

Use LightFlow when a task needs a fixed sequence or DAG of agent work, predictable dependency passing, per-step retries, and a single structured result for the whole workflow.

What It Provides

  • DAG-style dependencies between named steps.
  • Automatic output passing from dependency steps.
  • Custom step prompts through callable query builders.
  • Per-step retry limits.
  • LightFlowResult and LightFlowStepResult objects.
  • Optional flow-level trace events.

Basic Usage

from LightAgent import LightAgent, LightFlow

research_agent = LightAgent(
    name="ResearchAgent",
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
)

writer_agent = LightAgent(
    name="WriterAgent",
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
)

flow = (
    LightFlow()
    .step("research", agent=research_agent)
    .step("write", agent=writer_agent, depends_on=["research"])
)

result = flow.run("Analyze this company", trace=True)

print(result.content)
print(result.success)
print(result.trace)

When a step depends on earlier steps and does not define a custom query, LightFlow appends dependency outputs to the original input.

Custom Step Input

Use a callable query when a step needs precise prompt construction:

flow = (
    LightFlow()
    .step("research", agent=research_agent)
    .step(
        "write",
        agent=writer_agent,
        depends_on=["research"],
        query=lambda context: (
            f"Write a concise report from: {context['outputs']['research']}"
        ),
    )
)

The callable receives a context dictionary:

Key Meaning
input Original flow input.
outputs Mapping of completed step name to string output.
steps Mapping of completed step name to LightFlowStepResult.

Step Retries

Retries are configured per step:

flow.step("research", agent=research_agent, max_retry=2)

If a step still fails after its retries, the flow stops and returns a LightFlowResult with success == False. Completed step results remain available for debugging.

Result Formats

The default return value is a LightFlowResult object:

result = flow.run("Analyze this company")

print(result.content)
print(result.success)
print(result.steps[0].content)
print(result.error)

You can also request a plain string or dictionary:

text = flow.run("Analyze this company", result_format="str")
data = flow.run("Analyze this company", result_format="dict")

Supported values are:

result_format Return type
object LightFlowResult
str Final flow content
dict Serializable dictionary

Trace Events

Pass trace=True to collect flow-level events:

Event Meaning
flow_start The flow started.
step_start A step started.
step_end A step completed or failed.
flow_end The flow completed or stopped on failure.

Each step also preserves the underlying agent trace when the agent returns a structured RunResult.

Validation

LightFlow validates common workflow mistakes before execution:

  • empty step names
  • duplicate step names
  • missing run() method on step agents
  • max_retry < 1
  • unknown dependencies
  • dependency cycles

Current Scope

LightFlow remains a fixed, non-streaming workflow engine. v1.0.0 supports JSON checkpoints, approval nodes, resume, and selective reruns. See the runnable v1.0.0 approval and resume example for the current behavior. Use LightDAG or ExecutionService for dynamic verified graphs or ordinary reconnectable workloads respectively.

See the runnable example in example/10.lightflow.py and the focused tests in tests/test_lightflow.py.

Clone this wiki locally