Repository navigation
V1 Getting Started en
简体中文 | English
Applies to LightAgent v1.0.0. The default Agent in this guide uses an OpenAI-compatible Chat Completions service. To use an authenticated local Codex CLI instead of configuring a model API, see Agent Backends and Codex.
Installation from PyPI and installation from source are alternatives. Choose one. Create an isolated virtual environment first. This release's CI covers Python 3.10–3.13:
python -m venv .venv
source .venv/bin/activateOn Windows PowerShell, activate it with .\.venv\Scripts\Activate.ps1.
pip downloads the published package; no Git or source checkout is required. Choose one command below: the base package for core features, selected extras for specific integrations, or all for every optional Python dependency.
pip install lightagent
pip install 'lightagent[mcp,mem0]'
pip install 'lightagent[all]'These commands install the same package with different optional dependencies. To pin PyPI v1.0.0, use pip install 'lightagent==1.0.0' or pip install 'lightagent[all]==1.0.0'.
Git is required. pip fetches the v1.0.0 source tag from GitHub and builds LightAgent locally instead of downloading the LightAgent package from PyPI. Dependencies are still typically resolved from the package index. You do not need to run Option 1 first.
python -m pip install 'git+https://github.com/wanxingai/LightAgent.git@v1.0.0'To install from source with all optional dependencies, use this instead:
python -m pip install 'lightagent[all] @ git+https://github.com/wanxingai/LightAgent.git@v1.0.0'python -c 'from LightAgent import __version__; print(__version__)'An ordinary Agent does not require Codex, Docker, LightResearch, the MCP SDK, or a database. See the base and optional dependencies table for what each extra installs and what you still need to configure.
Set LIGHTAGENT_MODEL, LIGHTAGENT_API_KEY, and LIGHTAGENT_BASE_URL before running this example. Inject the key from the environment or a secret manager rather than putting it in source. Use the model ID and base URL from your provider. The base URL is usually the /v1 root, not /chat/completions.
import os
from LightAgent import LightAgent
agent = LightAgent(
name="docs-demo",
instructions="你是一个用中文简洁回答的助手。",
model=os.environ["LIGHTAGENT_MODEL"],
api_key=os.environ["LIGHTAGENT_API_KEY"],
base_url=os.environ["LIGHTAGENT_BASE_URL"],
auto_discover_skills=False,
)
print(agent.run("用一句话介绍 LightAgent。"))
result = agent.run("给出三个项目验收要点。", result_format="object", trace=True)
if result.error:
raise RuntimeError(result.error)
print(result.content)
print(result.usage, result.trace_id)name identifies the Agent, instructions defines its behavior, and role can describe its responsibilities for LightSwarm routing. ToT and self-learning are disabled by default. This example disables automatic Skill discovery so the current project's files do not affect the run. For OpenAI, DeepSeek, Qwen, OpenRouter, Atlas Cloud, or local vLLM and llama.cpp, verify model IDs, function calling, and streaming against the provider: API compatibility does not imply identical behavior. provider="litellm" requires the corresponding extra. See Model Provider Configuration.
| Call | What it returns and when to use it |
|---|---|
agent.run(query) |
The compatible string return, for the simplest call. |
agent.run(query, result_format="object", trace=True) |
A RunResult with content, error, usage, tool summaries, and a trace. Missing usage is not zero usage. |
agent.run(query, stream=True) |
The compatible streaming iterator. Forward chunks using the protocol your application expects. |
agent.run(query, stream=True, result_format="event") |
An iterator of StreamEvent objects; dispatch by type and data. |
await agent.arun(query) |
Use in async applications. In streaming mode, await the iterator, then consume it with async for. |
See Usage and Budgets for token counts, cost estimates, and missing usage.
Continue with the agent created above:
for event in agent.run("讲一个简短的技术比喻。", stream=True, result_format="event"):
print(event.type, event.data)import asyncio
async def main():
result = await agent.arun("你好", result_format="object")
if result.error:
raise RuntimeError(result.error)
print(result.content)
asyncio.run(main())For native execution, max_retry controls retries and max_tool_iterations caps the tool loop. Omitting the latter preserves the previous behavior. Check structured errors for timeouts and policy rejections rather than treating those as business success. A final output rule cannot retract content already streamed to a client; where review is required, buffer and inspect the response in your application. See Error Handling and Safety, Observability, and Evaluation.
-
tree_of_thought=Trueadds planning and tool selection. Enable it when there are many tools or the work benefits from decomposition, and measure the added latency and call cost. You can configuretot_model,tot_api_key, andtot_base_urlseparately. See Tree of Thought. -
self_learning=Trueuses memory to generate reflections. Internal reflections are not directly injectable user memories. Configure isolation, review, promotion, and cleanup before enabling it. See Memory and RAG. - An ordinary conversation does not automatically become a reconnectable task. Use LightFlow for fixed workflows, LightDAG for dynamic workflows, and ExecutionService for ordinary tasks that must survive a process restart.
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