Skip to content

V1 Getting Started

weego edited this page Nov 15, 2026 · 5 revisions

安装与第一个 Agent

简体中文 | English

适用版本:LightAgent v1.0.0。本页的默认 Agent 使用 OpenAI 兼容的 Chat Completions 服务。想用已登录的本机 Codex CLI,而不是配置模型 API,请跳到 执行后端与 Codex。

1. 选择安装方式

PyPI 安装和源码安装是两种独立方式,任选其一即可。 建议先创建独立虚拟环境。该版本的 CI 覆盖 Python 3.10–3.13:

python -m venv .venv
source .venv/bin/activate

Windows PowerShell 激活命令:.\.venv\Scripts\Activate.ps1。

方式一:从 PyPI 安装(推荐)

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'。

方式二:从 GitHub 源码安装

需要 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 安装的依赖和配置要求见 基础与可选依赖对照表。

2. 用原生后端发起对话

设置 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 参考。

3. 选择结果格式与并发方式

用法 返回与适用场景
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 控制工具循环上限;不显式传后者时保留原有兼容行为。超时或策略拒绝时要检查结构化错误,不将业务失败当成成功。流式内容已经发给客户端后不能靠最终输出规则撤回;敏感场景请在业务层先缓冲和审查。详见 错误处理 和 安全、观测与评测。

4. 可选规划与自我学习

  • tree_of_thought=True 增加规划和工具筛选环节。已有工具很多或任务需要分步时才启用,先测额外延迟与调用成本。可独立配置 tot_model、tot_api_key、tot_base_url。见 Tree of Thought。
  • self_learning=True 结合记忆生成反思;内部反思并不是可直接注入的用户记忆。开启前配置隔离、审查、晋升和清理机制。见 记忆与 RAG。
  • 基础对话不会自动成为可重连长任务。固定流程选择 LightFlow,动态任务选择 LightDAG,跨进程恢复的普通任务选择 ExecutionService。

Clone this wiki locally