LightAgent

环境要求

• Python 环境（PyPI 上提供 lightagent 包）
• 可用的 OpenAI 兼容 API：api_key 与 base_url
• 使用长期记忆时需额外安装 mem0ai（可选）
• 使用工具调用时需自行提供带 tool_info 元数据的函数

安装与启动步骤

1. 1安装 LightAgent

   使用 pip 从 PyPI 安装最新版 lightagent 包，这是整个框架的唯一必需依赖。

   pip install lightagent

   复制

2. 2可选安装 Mem0

   只有需要 Mem0 记忆后端时才安装 mem0ai；不装也能正常跑基础对话。

   pip install mem0ai

   复制

3. 3创建 Agent 实例

   用 model、api_key、base_url 三个参数初始化 LightAgent，后两个换成你自己的真实值。

   from LightAgent import LightAgent
   
   agent = LightAgent(model="gpt-4.1", api_key="sk-xxxxxxxx", base_url="https://api.openai.com/v1")

   复制

4. 4运行一次对话

   调用 agent.run 传入问题，默认返回字符串，直接 print 即可看到模型回复。

   response = agent.run("Hello, who are you?")
   print(response)

   复制

5. 5开启追踪日志

   加 result_format="object"、trace=True 拿到结构化结果与 trace，再遍历导出的事件。

   result = agent.run("Hello, who are you?", 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"])

   复制

6. 6接入自定义工具

   在构造 LightAgent 时通过 tools 传入函数列表，函数需暴露 tool_info 元数据，数量不限。

   agent = LightAgent(
       model="gpt-4.1",
       api_key="sk-xxxxxxxx",
       base_url="https://api.openai.com/v1",
       tools=[search_news, get_weather],
   )

   复制

7. 7编排 LightFlow 工作流

   用 LightFlow 串起多步任务并持久化检查点，失败后可用 run_id 调用 resume 从断点续跑。

   from LightAgent import JsonLightFlowStore, LightAgent, LightFlow
   
   research_agent = LightAgent(model="gpt-4.1", api_key="sk-xxxxxxxx", base_url="https://api.openai.com/v1")
   writer_agent = LightAgent(model="gpt-4.1", api_key="sk-xxxxxxxx", base_url="https://api.openai.com/v1")
   
   store = JsonLightFlowStore(".lightflow_runs")
   flow = (
       LightFlow(store=store)
       .step("research", agent=research_agent, timeout=30)
       .step("write", agent=writer_agent, depends_on=["research"], max_retry=2)
   )
   
   result = flow.run("Analyze this company", run_id="report-001", trace=True)
   
   if not result.success:
       result = flow.resume("report-001")
   
   print(result.status)
   print(flow.get_run("report-001")["steps"])

   复制

关键配置

如何确认成功

执行 agent.run("Hello, who are you?") 后能 print 出模型回复文本，说明安装与密钥配置均正常。

常见问题

注意事项

• 示例里的 api_key、base_url 必须替换成自己的真实值，切勿硬编码提交到仓库。
• 追踪默认关闭且不改变 agent.run() 的返回类型，需要显式传 trace=True 才记录事件。
• 安全敏感的回调建议用 PolicyHook 包装，异常或超时会 fail closed，普通观测钩子则保持失败隔离。
• JsonLightFlowStore(".lightflow_runs") 会在该目录写入运行记录，可按需更换路径。