Repository navigation
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.
- DAG-style dependencies between named steps.
- Automatic output passing from dependency steps.
- Custom step prompts through callable
querybuilders. - Per-step retry limits.
-
LightFlowResultandLightFlowStepResultobjects. - Optional flow-level trace events.
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.
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. |
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.
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 |
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.
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
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.
LightAgent Wiki - see the repository, releases, and issues.
- Installation and Your First Agent
- Tools and Integrations
- Memory, Sessions, and RAG
- Workflows and Multiple Agents
- Agent Backends and Codex
- Durable Execution, Jobs, and Subagents
- Safety, Observability, and Evaluation
- Usage, Cost Estimates, and Budgets
- Deployment, Migration, and Verification
- 安装与第一个 Agent
- 工具和集成
- 记忆、会话与 RAG
- 工作流与多 Agent
- 执行后端与 Codex
- 持久执行、Jobs 与 Subagents
- 安全、观测与评测
- 用量统计、费用估算与预算
- 部署、升级与验收
- Quick Start
- Core Concepts
- API Reference
- Examples Cookbook
- Migration Guide
- Tools
- Tool Generator
- Memory
- MCP
- Skills
- LightFlow
- Tree of Thought
- Self-Learning
- Multi-Agent
- Tracing and Debugging
- Langfuse Observability
- Model Providers
- browser-use Integration
- Testing and CI
- Deployment Guide
- Architecture
- Security
- Known Limitations
- FAQ
- FAQ 中文
- Roadmap
- Release Process
- Contributing