Repository navigation
Migration Guide
This guide covers practical upgrades across recent LightAgent versions.
For an upgrade to v1.0.0, start with deployment, migration, and verification, particularly for optional dependencies, historical backups, and the separate LightResearch extension. The sections below describe earlier version transitions.
- Existing
agent.run("hello")code remains compatible. - Existing
agent.run(query, stream=True, user_id=user_id)code remains compatible. - Structured results are opt-in through
result_format. - Tracing is opt-in through
trace=True. - LightFlow is additive in v0.8.0; existing
LightAgentandLightSwarmcalls do not need to change. - Memory isolation is stronger when
MemoryPolicyormemory_namespaceis configured.
v0.8.0 adds LightFlow for deterministic multi-step workflows. It is an additive API, so existing code such as agent.run("hello"), streaming runs, tools, memory, Skills, and LightSwarm remains compatible.
Import LightFlow only when you want workflow orchestration:
from LightAgent import LightAgent, LightFlow
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)Use LightFlow for fixed DAG-style workflows. Continue using LightSwarm when you want model-directed handoff between agents.
The initial v0.8.0 scope is non-streaming workflow execution. Durable execution, human approval nodes, and resume support are planned for later versions.
Validation and examples:
PYTHONPATH=. python -m pytest -q tests/test_lightflow.py
python example/10.lightflow.pyNo change is required:
response = agent.run("hello")
print(response) # strUse structured results only when needed:
result = agent.run("hello", result_format="object")
print(result.content)
print(result.tool_calls)
print(result.error)Legacy streaming remains compatible:
for chunk in agent.run(query, stream=True, user_id=user_id):
print(chunk, end="")Structured stream events are opt-in:
for event in agent.run(query, stream=True, user_id=user_id, result_format="event"):
print(event.type, event.data)Tool argument validation is stricter. Check that:
-
tool_info["tool_params"]names match the Python function parameters. - Required parameters are listed correctly.
- Types are JSON-schema-like values such as
string,integer,number,boolean,array, andobject.
Tracing is new and disabled by default:
result = agent.run("hello", result_format="object", trace=True)
print(result.trace_id)
print(result.trace)For string compatibility mode:
response = agent.run("hello", trace=True)
trace = agent.export_trace()Model request trace events store prompt-safe summaries, not full prompts. Tool arguments and tool outputs may appear in traces because they are required for debugging tool behavior.
For single-user experiments, existing memory adapters can continue to work.
For shared deployments, prefer:
from LightAgent import MemoryPolicy
agent = LightAgent(
model="gpt-4.1",
api_key="your_api_key",
base_url="https://api.openai.com/v1",
memory=memory_backend,
memory_policy=MemoryPolicy(
namespace="tenant-a",
allow_unattributed_results=False,
),
)Shortcut:
agent = LightAgent(
model="gpt-4.1",
api_key="your_api_key",
base_url="https://api.openai.com/v1",
memory=memory_backend,
memory_namespace="tenant-a",
)Use:
OPENAI_API_KEY
OPENAI_BASE_URLDo not use the old OPENAI_API_BASE name in new examples.
- Update package version.
- Replace old repository links with
https://github.com/wanxingai/LightAgent. - Confirm
OPENAI_BASE_URLis used. - Run the minimal agent example.
- Run at least one tool-calling example.
- Run memory examples with stable
user_id. - Add
MemoryPolicyfor shared memory backends. - Use
trace=Truewhen debugging new failures. - Use
LightFlowwhen a task needs deterministic multi-step orchestration. - Run focused tests before opening a PR.
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