Skip to content

README.zh-CN.md

Latest commit

 

History

History
477 lines (358 loc) · 27.1 KB

README.zh-CN.md

File metadata and controls

477 lines (358 loc) · 27.1 KB
Raw

LightAgent Banner

License GitHub release GitHub issues GitHub stars GitHub forks GitHub contributors Docs PyPI Downloads Python Version Code Style

LightAgent🚀 超轻量、可“成长”的智能体框架，现已原生支持Skill

🚀 LightAgent 不再只是“聊天”，而是真正的“完成任务”。LightAgent 把记忆（mem0）、工具（Tools）、思维树（ToT）和多智能体协作融合进一个极简的包中，而你只需 一行代码 就能构建一个能自我学习、按需加载Skill的智能体 —— 就像给大模型装上“招式库”与“执行大脑”。

🔥 为什么开发者会爱上它？

  • Skill 原生支持：像管理代码一样管理 AI 能力。把 PDF 处理、代码审查、SOP 流程打包成可复用的 Skill，Agent 按需调用 —— 告别 prompt 堆积，迎接工程化 AI。
  • 比 OpenAI Swarm 更简易的多智能体协作：无需复杂编排，轻松构建“Agent 小分队”，并行拆解复杂任务。
  • MCP 协议（stdio/sse）开箱即连：无缝接入外部数据源与工具，Agent 的“手”从此无限延伸。
  • 零成本切换底层模型：OpenAI、智谱 ChatGLM、DeepSeek、阶跃星辰、通义千问…… 想用哪个用哪个。
  • 开箱即用的 API 服务：标准 OpenAI 流式输出格式，可直接接入主流 Chat 前端（如 NextChat、LobeChat），秒变生产级应用。

🌟 LightAgent = 轻 + 灵 + 可扩展
从个人脚本到企业级 Workflow，它帮你把“聪明的模型”变成“可靠的员工”。
Star 我们，尝试你的第一个 Skill 驱动的 Agent —— 改动几行代码，见证 AI 真正“动手做事”。

新闻

  • new[2026-08-15] LightAgent v0.10.0 开发版：新增统一的事件溯源 Agent Runtime，支持可持久化 Session、异步执行、Capability Registry 与 Policy、Inbox/Goals/Budgets、上下文压缩与恢复、Jobs/子 Agent、标准化 Skills/MCP 适配器和 SQLite FTS5 检索。
  • [2026-08-15] LightAgent v0.9.7 正式发布：新增轻量、零依赖的 Connector 契约及离线校验与示例，强化 Python 执行器安全检查，补充可选的 Mem0 Graph 安全验证矩阵，并通过公共 API 兼容性清单为 v1.0 稳定化做准备。
  • [2026-07-30] LightAgent v0.9.6 正式发布：新增生产级 Trace 汇总与导出、确定性评测、工具、handoff 和 LightFlow 的可持久化人工审批，以及共享 Graph Memory 的 fail-closed 写入准入与审计控制。
  • [2026-07-10] LightAgent v0.9.3 正式发布：补全 after_run、on_error 和记忆检索 Hooks 生命周期，新增独立的 max_tool_iterations 流式工具循环上限并保持 max_retry 向后兼容，同时完善错误收尾、Trace 和回归测试。
  • [2026-06-24] LightAgent v0.9.0 开发版：新增可持久化 LightFlow checkpoint、resume/rerun、审批节点、更清晰的步骤状态和 trace 元数据，同时补充 Guardrails 模板、MemoryPolicy 控制和 SharedMemoryPool 原型。
  • [2026-06-14] LightAgent v0.8.1 开发版：新增 MemoryScope 元数据约定、MemoryPolicy 来源/范围/可信度过滤，并补充 Trace、用户记忆、自我反思记忆和 LightSwarm 委托状态的边界说明。
  • [2026-06-02] LightAgent v0.8.0 开发版：新增 LightFlow 工作流编排能力，支持确定性多步骤 Agent 执行、DAG 依赖、步骤输出传递、重试和 flow trace 事件。
  • [2026-05-29] LightAgent v0.7.0 开发版：新增可选的结构化 Trace 可观测能力，支持记录运行生命周期、模型请求摘要、工具调用、工具结果和错误事件，并提供 agent.export_trace() 便于生产调试。
  • [2026-05-28] LightAgent v0.6.5 正式发布：新增可选结构化运行结果、结构化流式事件、可捕获的 LightAgent 错误和工具参数校验，同时保持默认 agent.run() 与 stream=True 行为兼容。
  • [2026-05-27] LightAgent v0.6.4 正式发布：提升运行时工具调度可靠性，新增结构化错误码和排查文档，扩展 OpenAI 兼容模型配置说明。

历史版本说明请查看 GitHub Releases。

lightswarm_demo_cn.png

✨ 特性

  • 轻量高效 🚀：极简设计，快速部署，适合各种规模的应用场景。（No LangChain, No LlamaIndex）核心框架保持小而清晰，按需使用模型、MCP、记忆和可观测相关依赖，完全开源。
  • 记忆支持 🧠：支持为每个用户自定义长期记忆，原生支持 mem0 记忆模块，实现对话过程中自动管理用户个性化记忆，让 Agent 更智能。
  • 自主学习 📚️：每个agent拥有自主学习能力，并且拥有权限的管理员可以管理每个agent。
  • 工具集成 🛠️：支持自定义工具（Tools）和MCP工具集成，灵活扩展，满足多样化需求。
  • 复杂目标 🌳：内置带反思的思维树（ToT）模块，支持复杂任务分解和多步推理，提升任务处理能力。
  • 多智能体协同 🤖：比Swarm更简单的多智能体协同，内置的LightSwarm实现意图判断和任务转移功能，能够更智能地处理用户输入，并根据需要将任务转移给其他代理。
  • 独立执行 🤖：无人为干预自主完成任务工具调用。
  • 多模型支持 🔄：兼容 OpenAI、智谱 ChatGLM、百川大模型、阶跃星辰、DeepSeek、Qwen 系列大模型。
  • 流式 API输出 🌊：支持 OpenAI 流格式 API 服务输出，无缝接入主流 Chat 框架，提升用户体验。
  • Trace 可观测性 🔎：通过 trace=True 可选开启结构化运行轨迹，记录运行开始/结束、模型请求摘要、工具调用、工具结果和错误，同时保持默认字符串返回行为不变。
  • 评测框架 📊：LightEvaluator 可对 Agent 或 LightFlow 执行确定性回归用例，检查输出、工具选择、策略事件、恢复能力、延迟、usage 和预估成本。
  • 人工审核 👤：HumanApprovalHook、可持久化审核存储和 LightFlow 审批 checkpoint 支持高风险动作的批准、拒绝、参数编辑、人工响应、批量审核和 trace 反馈。
  • Runtime Hooks 🧩：通过有序 hooks=[...] 中间件观察、替换或阻断运行、模型、工具、记忆、LightSwarm handoff 和 LightFlow 步骤阶段；安全策略可使用 PolicyHook 在异常或超时时 fail closed，并将决策写入 trace。
  • 事件溯源 Runtime 🧱：可选的持久化 Session、回放、checkpoint、fork、异步入口、分层 Capability Provider、统一 Policy、Inbox、Goals、Budgets、Jobs、子 Agent、上下文压缩和 SQLite FTS5 检索。
  • Tools工具生成器 🚀：只需将您的API文档交给[Tools工具生成器]，它将自动化地为您打造专属的tools，助您在短短1小时内快速构建数百个个性化的自定义工具，提升效率，释放您的创新潜能。
  • agent自我学习 🧠️：每个agent拥有自己的场景记忆能力，拥有从用户的对话中进行自我学习能力。
  • 自适应tools机制 🛠️：支持添加无限量tools，在上万个工具中让大模型过滤无关工具后再发送给大模型，可大幅度降低Token消耗。
  • 工作流编排 🔁：LightFlow 将多个 Agent 编排为确定性多步骤工作流，支持显式依赖、步骤输出传递、重试、checkpoint、resume/rerun、审批节点、fallback agent 和可追踪执行。
  • 共享记忆原型 🧠：SharedMemoryPool 提供带来源元数据和范围检索的追加式内存共享记忆，适合多 Agent 实验。
  • Guardrails 模板 🛡️：可复用的输入、工具和输出安全策略模板，可用于隐私拦截、敏感工具确认、高风险参数校验和输出脱敏。

🧭 架构速览

层级 主要 API 适用场景
单 Agent 运行时 LightAgent 一个 Agent 的模型调用、工具、记忆、流式输出、trace 和 guardrails。
持久化运行状态 Session、AgentRuntime 可回放事件、checkpoint、Inbox、Goals、Budgets、Jobs 和上下文恢复。
能力层 CapabilityRegistry、PolicyEngine 分层 Provider、权限快照、生命周期、策略与审计。
多 Agent 路由 LightSwarm 在多个专业 Agent 之间进行角色化委托。
确定性工作流 LightFlow DAG 工作流、重试、checkpoint、持久化审批、resume 和 rerun。
工具与集成 tools、ToolRegistry、MCP Python 工具、生成工具、运行时加载工具或 MCP 工具服务。任意 Python 执行默认关闭，并要求显式沙箱边界。
记忆边界 MemoryPolicy、MemoryScope 租户隔离、来源、可信度、过期和写入准入控制。
共享记忆原型 SharedMemoryPool 多 Agent 共享记忆实验。
安全控制 input_guardrails、tool_guardrails、output_guardrails 隐私拦截、敏感工具确认、高风险参数校验和输出脱敏。
Runtime Hooks hooks、HookContext、HookDecision 在生命周期边界实现策略、审计、脱敏、路由和 payload 改写。
可观测性 trace=True、summarize_trace、trace exporter 结构化事件、延迟、usage、重试/错误指标以及 JSONL 或外部导出。
评测 LightEvaluator、EvaluationCase 对输出、工具、策略事件、恢复、延迟和成本执行固定回归用例。
人工审核 HumanApprovalHook、ApprovalDecision、review store 工具/handoff 的 fail-closed 审核、参数编辑、持久化决策和反馈。

核心使用模式

LightAgent 保持默认调用路径简单，同时允许逐步加入生产级控制。

模式 最小调用 说明
基础响应 agent.run(query) 默认返回字符串。
流式输出 agent.run(query, stream=True) 返回 OpenAI 兼容的流式 chunk。
结构化结果 agent.run(query, result_format="object") 返回内容和结构化元数据。
Trace agent.run(query, trace=True) 记录事件，不改变默认字符串返回。
用户记忆 agent.run(query, user_id="alice") 使用配置的记忆后端和 MemoryPolicy。
工具 LightAgent(..., tools=[fn]) 函数应提供 tool_info 元数据。
Guardrails LightAgent(..., input_guardrails=[...]) 为 Agent 添加输入、工具和输出策略。
Runtime Hooks LightAgent(..., hooks=[fn]) 观察、替换或阻断生命周期 payload。
评测 LightEvaluator().run(agent, cases) 基于结构化 trace 执行确定性行为检查。
工具审批 LightAgent(..., hooks=[HumanApprovalHook(...)]) 在选定工具或 handoff 执行前要求人工审核。
工作流 LightFlow().step(...).run(query) 用于确定性多步骤执行。
持久化 Session agent.run(query, session_id="project-42") 延续并回放持久化会话。
异步调用 await agent.arun(query) 避免阻塞 asyncio 应用。

安全工具默认行为

从 v0.10.1 开始，任意 Python 执行工具默认不会注册。对于受限的算术和 数据表达式，请使用内置的 safe_expression 工具：

from LightAgent import safe_expression

print(safe_expression("45 * 9827"))

启用 execute_python_code、execute_python_file 或 execute_python_code_stream 需要设置 enable_unsafe_python=True，并注册显式 的 SandboxProvider。执行器只是受控子进程，并不是安全沙箱；详见 Python 执行器安全说明。

评测并审核高风险动作

from LightAgent import EvaluationCase, HumanApprovalHook, LightEvaluator

agent.hooks.hooks.append(HumanApprovalHook(tools={"send_payment"}))

report = LightEvaluator().run(agent, [
    EvaluationCase(
        name="payment policy",
        query="支付 42 号发票",
        expected_trace_events=("approval_required",),
        forbidden_tools=("delete_account",),
    ),
])
print(report.to_dict())

待审批请求可写入 JsonReviewStore；使用 ApprovalDecision 完成审核后，通过 approval_id=request.request_id 重新运行。LightFlow 也可通过 flow.approve(...); flow.resume(...) 持久化并恢复步骤审批。

📋 文档

  • 常见安装、模型、工具、记忆、MCP、Skills、流式输出和 LightSwarm 问题，请查看 FAQ。
  • 确定性多步骤工作流、checkpoint、resume/rerun、审批节点、fallback agent 和步骤状态，请查看 LightFlow。
  • 自定义工具、运行时工具、ToolRegistry、ToolLoader、AsyncToolDispatcher 和 MCP 工具集成，请查看 Tools Guide。
  • 共享长期记忆或图记忆部署，请查看 Memory Security Guidance。
  • SharedMemoryPool 原型请查看 SharedMemoryPool。
  • 记忆写入准入、过期检索和低质量写入拦截，请查看 Memory Admission And Mutation Controls。
  • 输入、工具和输出安全策略，请查看 Guardrails。
  • 运行期中间件和生命周期 payload 改写，请查看 Runtime Hooks。
  • OpenRouter、本地模型和 OpenAI 兼容配置，请查看 Model Provider Configuration。
  • Trace 可观测能力请查看 Trace Observability。
  • 确定性回归用例、指标和 CI 方案请查看 Evaluation Harness。
  • 工具/handoff 审批、LightFlow 持久化审核、批量决策和反馈请查看 Human Review。
  • 持久化 Session、Capability Provider、Policy、Inbox、Goals、Budgets、Jobs、上下文压缩、子 Agent、Skills/MCP 更新和 SQLite FTS5 检索，请查看 LightAgent v0.10 Runtime。

🚧 即将推出

  • 智能体协同通讯 🛠️：智能体之间还可以共享信息和传递消息，实现复杂的信息通讯和任务协同。

🌟 为什么选择 LightAgent？

  • 开源免费 💖：完全开源，社区驱动，持续更新，欢迎贡献！
  • 易于上手 🎯：文档详尽，示例丰富，快速上手，轻松集成到你的项目中。
  • 社区支持 👥：活跃的开发者社区，随时为你提供帮助和解答。
  • 高性能 ⚡：优化设计，高效运行，满足高并发场景需求。

🛠️ 快速开始

安装LightAgent最新版本

pip install lightagent

（可选安装）通过 pip 安装 Mem0 包：

pip install mem0ai

或者，您可以通过一键点击在托管平台上使用 Mem0，点击这里。

Hello world 示例代码

from LightAgent import LightAgent

# 初始化 Agent
agent = LightAgent(model="gpt-4.1", api_key="your_api_key", base_url= "your_base_url")

# 运行 Agent
response = agent.run("你好，你是谁？")
print(response)

查看运行 Trace（v0.7.0）

Trace 默认关闭，需要显式传入 trace=True，不会改变原有 agent.run() 默认返回字符串的兼容行为。

from LightAgent import LightAgent

# 初始化 Agent
agent = LightAgent(model="gpt-4.1", api_key="your_api_key", base_url= "your_base_url")

# 以结构化对象形式查看运行轨迹
result = agent.run("你好，你是谁？", result_format="object", trace=True)
print(result.content)
print(result.trace_id)
print(result.trace)

for event in agent.export_trace():
    print(event["type"], event["data"])

通过system提示词设定模型自我认知

from LightAgent import LightAgent

# 初始化 Agent
agent = LightAgent(
     role="请记住你是LightAgent，一个可以帮助用户完成多工具使用的有用助手。",  # system角色描述
     model="gpt-4.1",  # 支持的模型：openai, chatglm, deepseek, qwen 等
     api_key="your_api_key",  # 替换为你的大模型服务商 API Key
     base_url="your_base_url",  # 替换为你的大模型服务商 api url
 )
# 运行 Agent
response = agent.run("请问你是谁？")
print(response)

使用工具示例代码

from LightAgent import LightAgent


# 定义工具
def get_weather(city_name: str) -> str:
    """
    Get the current weather for `city_name`
    """
    return f"查询结果: {city_name} 天气晴"
# 在函数内部定义工具信息
get_weather.tool_info = {
    "tool_name": "get_weather",
    "tool_description": "获取指定城市的当前天气信息",
    "tool_params": [
        {"name": "city_name", "description": "要查询的城市名称", "type": "string", "required": True},
    ]
}

tools = [get_weather]

# 初始化 Agent
agent = LightAgent(model="gpt-4.1", api_key="your_api_key", base_url= "your_base_url", tools=tools)

# 运行 Agent
response = agent.run("请帮我查询一下上海的天气情况")
print(response)

支持自定义无限数量的工具。

多个工具示例： tools = [search_news,get_weather,get_stock_realtime_data,get_stock_kline_data]

功能详解

README 保留核心使用模型；更长的示例、适配器配置和生产实践放在专门文档中。

1. 可拆卸记忆模块（mem0）

LightAgent 接受任何提供 store(data, user_id) 和 retrieve(query, user_id) 的记忆后端。使用 user_id 隔离对话；当记忆跨用户、租户、Agent 或 trace 共享时，应配置 MemoryPolicy。

2. 工具集成

使用带 tool_info 元数据的 Python 函数向 Agent 暴露受控能力。高级运行时工具、ToolRegistry、ToolLoader、AsyncToolDispatcher 和 MCP 请查看 Tools Guide。

3. Tools 工具生成器

agent.create_tool() 可以根据 API 文档或自然语言描述生成工具代码。生成工具应放在可审查的 tools 目录中，并在生产使用前测试。

4. 思维树（ToT）

当任务需要显式规划、反思和多工具选择时，启用 tree_of_thought=True。

5. 多智能体协同

LightSwarm 用于在专业 Agent 之间进行角色化委托。保持每个 Agent 角色清晰，并用记忆策略约束跨 Agent 记忆写入。

6. 流式 API

agent.run(query, stream=True) 返回 OpenAI 兼容流式 chunk，适合聊天 UI 和长输出。

7. Agent 自我学习

自我学习应与记忆后端和 MemoryPolicy 配合使用，避免低质量、隐私、过期或无关内容进入长期记忆。反思、委托摘要等内部证据默认先生成不可注入的记忆候选，需要通过 memory_promotion_admission 或 agent.promote_memory_candidate(candidate_id) 显式提升后，才会进入未来 prompt。 从 v0.9.4 升级时，应先审查旧的内部记忆，再为通过审查的记录回填 promotion_status="promoted" 和 injectable=True；require_promotion_for_internal_memory=False 仅用于临时兼容。具体迁移说明请查看 Memory Admission。

8. Trace 与 Langfuse

LightAgent 可通过内置 trace 或 Langfuse 配置观察运行过程。

9. Agent 测评

LightEvaluator 可围绕确定性业务用例评估输出、工具选择、策略事件、恢复能力、延迟、usage 和预估成本。

10. LightFlow 工作流

LightFlow 是确定性工作流层，适合让任务按已知步骤执行，而不是完全依赖自由形式规划。

  • 步骤状态：pending、running、success、failed、skipped、waiting_approval。
  • DAG 校验：flow.validate(strict=True)。
  • 步骤控制：timeout、max_retry、cancel_if、fallback_agent、requires_approval、approval_handler。
  • 持久化与恢复：JsonLightFlowStore、flow.resume(run_id)、flow.rerun_step(run_id, step_name)、flow.get_run(run_id)、flow.list_runs()。

请查看 LightFlow。

11. Guardrails

Guardrails 是围绕 Agent 执行的轻量策略钩子：输入策略检查用户问题，工具策略检查工具调用，输出策略检查或脱敏最终输出。

from LightAgent import (
    LightAgent,
    high_risk_parameter_guardrail,
    output_redaction_guardrail,
    privacy_input_guardrail,
    sensitive_tool_confirmation_guardrail,
)

agent = LightAgent(
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="your_base_url",
    input_guardrails=[privacy_input_guardrail()],
    tool_guardrails=[
        sensitive_tool_confirmation_guardrail(["transfer_money"], approved=False),
        high_risk_parameter_guardrail({"amount": lambda value: float(value) <= 1000}),
    ],
    output_guardrails=[output_redaction_guardrail()],
)

请查看 Guardrails。

12. SharedMemoryPool

SharedMemoryPool 是多 Agent 共享记忆实验的内存原型，建议与 MemoryPolicy 配合控制 namespace、source、scope、trust、confidence、promotion status 和 agent name。

主流Agent模型支持

LightAgent 兼容 OpenAI 风格 chat completion endpoint，包括 OpenAI、OpenRouter、智谱 ChatGLM、DeepSeek、Qwen、StepFun、Moonshot/Kimi、MiniMax、vLLM、llama.cpp、Ollama 兼容接口和自托管网关。

For provider-specific parameters, base URLs, local model setup, and troubleshooting, see Model Provider Configuration.

使用场景

  • 智能客服：通过多轮对话和工具集成，提供高效的客户支持。
  • 数据分析：利用思维树和多智能体协同，处理复杂的数据分析任务。
  • 自动化工具：通过自动化工具生成，快速构建定制化工具。
  • 教育辅助：通过记忆模块和流式 API，提供个性化的学习体验。

🛠️ 贡献指南

我们欢迎任何形式的贡献！无论是代码、文档、测试还是反馈，都是对项目的巨大帮助。如果您有好的想法或发现 Bug，请提交 Issue 或 Pull Request。以下是贡献步骤：

  1. Fork 本项目：点击右上角的 Fork 按钮，将项目复制到您的 GitHub 仓库。
  2. 创建分支：在本地创建您的开发分支： 
    git checkout -b feature/YourFeature
  3. 提交更改：完成开发后，提交您的更改： 
    git commit -m 'Add some feature'
  4. 推送分支：将分支推送到您的远程仓库： 
    git push origin feature/YourFeature
  5. 提交 Pull Request：在 GitHub 上提交 Pull Request，并描述您的更改内容。

我们会在第一时间审核您的贡献，感谢您的支持！❤️

🙏 致谢

上海万行AI与上海财经大学统计与数据科学学院张立文教授课题组联合开源了新一代智能体框架 LightAgent。LightAgent 的开发和实现离不开以下开源项目的启发和支持，特别感谢这些优秀的项目和团队：

  • MCP：感谢 mcp 提供的模型上下文协议（MCP），为 LightAgent 的动态工具集成提供了标准化基础设施。
  • mem0：感谢 mem0 提供的记忆模块，为 LightAgent 的上下文管理提供了强大支持。
  • Swarm：感谢 Swarm 提供的多智能体协同设计思路，为 LightAgent 的多智能体功能奠定了基础。
  • ChatGLM3：感谢 ChatGLM3 提供的高性能中文大模型支持和设计灵感。
  • Qwen：感谢 Qwen 提供的高性能中文大模型支持。
  • DeepSeek-V3：感谢 DeepSeek-V3 提供的高性能中文大模型支持。
  • 阶跃星辰：感谢 step 提供的高性能中文大模型支持。

📄 许可证

LightAgent 采用 Apache 2.0 许可证。您可以自由使用、修改和分发本项目，但请遵守许可证条款。

📬 联系我们

如有任何问题或建议，欢迎随时联系万行AI或上海财经大学统计与数据科学学院张立文教授联系：

我们期待您的反馈，一起让 LightAgent 变得更强大！🚀

LightAgent - 让智能更轻量，让未来更简单。 🌈

LightAgent —— 轻量、灵活、强大的主动式 Agent 框架，助您快速构建智能应用！

Star History

Star History Chart

论文

@misc{2509.09292,
Author = {Weige Cai and Tong Zhu and Jinyi Niu and Ruiqi Hu and Lingyao Li and Tenglong Wang and Xiaowu Dai and Weining Shen and Liwen Zhang},
Title = {LightAgent: Production-level Open-source Agentic AI Framework},
Year = {2025},
Eprint = {arXiv:2509.09292},
Eprinttype = {arXiv},
Eprintclass = {cs.AI},
Url = {https://arxiv.org/abs/2509.09292},
Doi = {10.48550/arXiv.2509.09292},
Note = {Submitted on 11 Sep 2025}
}