Repository navigation
V1 Getting Started
简体中文 | English
适用版本:LightAgent v1.0.0。本页的默认 Agent 使用 OpenAI 兼容的 Chat Completions 服务。想用已登录的本机 Codex CLI,而不是配置模型 API,请跳到 执行后端与 Codex。
PyPI 安装和源码安装是两种独立方式,任选其一即可。 建议先创建独立虚拟环境。该版本的 CI 覆盖 Python 3.10–3.13:
python -m venv .venv
source .venv/bin/activateWindows PowerShell 激活命令:.\.venv\Scripts\Activate.ps1。
pip 下载已发布的包,无需 Git 或源码检出。下面的命令按需选一条:只用核心功能选基础包,只需要某些集成选指定 extras,需要所有可选 Python 依赖则选 all。
pip install lightagent
pip install 'lightagent[mcp,mem0]'
pip install 'lightagent[all]'这些命令安装的是同一个包,区别只在于可选依赖。要固定 PyPI 的 v1.0.0,使用 pip install 'lightagent==1.0.0' 或 pip install 'lightagent[all]==1.0.0'。
需要 Git。pip 会从 GitHub 拉取 v1.0.0 标签的源码,并在本地构建 LightAgent,而不是下载 PyPI 上的 LightAgent 包。依赖仍通常从包索引解析。不必先执行方式一。
python -m pip install 'git+https://github.com/wanxingai/LightAgent.git@v1.0.0'需要源码安装同时带全部可选依赖时,改用:
python -m pip install 'lightagent[all] @ git+https://github.com/wanxingai/LightAgent.git@v1.0.0'python -c 'from LightAgent import __version__; print(__version__)'普通 Agent 不需要 Codex、Docker、LightResearch、MCP SDK 或数据库。每个 extra 安装的依赖和配置要求见 基础与可选依赖对照表。
设置 LIGHTAGENT_MODEL、LIGHTAGENT_API_KEY 和 LIGHTAGENT_BASE_URL,然后运行代码。API key 从环境变量或密钥管理器注入,不写进源代码。模型 ID 和 Base URL 以实际服务配置为准;Base URL 通常是 /v1 根路径,不是 /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 是 Agent 标识,instructions 定义行为,role 可描述职责,便于 LightSwarm 路由。默认关闭 ToT 和自我学习。本例主动关闭 Skills 自动发现,使运行结果不受当前项目的 Skill 文件影响。OpenAI、DeepSeek、Qwen、OpenRouter、Atlas Cloud 或本地 vLLM/llama.cpp 的接法都要核对模型 ID、工具调用和流式实现;协议兼容不保证能力完全一致。使用 provider="litellm" 要安装对应 extra。见 模型 Provider 参考。
| 用法 | 返回与适用场景 |
|---|---|
agent.run(query) |
兼容的字符串返回,最短路径。 |
agent.run(query, result_format="object", trace=True) |
RunResult,包含 content、error、usage、工具摘要、Trace 等;供应商不返回 usage 时不要假设为零。 |
agent.run(query, stream=True) |
兼容流式迭代;按实际应用协议转发。 |
agent.run(query, stream=True, result_format="event") |
StreamEvent 迭代,按 type、data 分发。 |
await agent.arun(query) |
在异步应用内调用;流式模式等待取得迭代器后用 async for。 |
查看如何读取 token、估算费用和处理缺失记录,见用量统计与预算。
接续上面的 agent:
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())原生模式通过 max_retry 控制重试,通过 max_tool_iterations 控制工具循环上限;不显式传后者时保留原有兼容行为。超时或策略拒绝时要检查结构化错误,不将业务失败当成成功。流式内容已经发给客户端后不能靠最终输出规则撤回;敏感场景请在业务层先缓冲和审查。详见 错误处理 和 安全、观测与评测。
-
tree_of_thought=True增加规划和工具筛选环节。已有工具很多或任务需要分步时才启用,先测额外延迟与调用成本。可独立配置tot_model、tot_api_key、tot_base_url。见 Tree of Thought。 -
self_learning=True结合记忆生成反思;内部反思并不是可直接注入的用户记忆。开启前配置隔离、审查、晋升和清理机制。见 记忆与 RAG。 - 基础对话不会自动成为可重连长任务。固定流程选择 LightFlow,动态任务选择 LightDAG,跨进程恢复的普通任务选择 ExecutionService。
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