Skip to content

FAQ zh CN

weego edited this page Nov 15, 2026 · 4 revisions

FAQ 中文

LightAgent 是什么?

LightAgent 是一个轻量级 Python Agent 框架,用于构建支持工具调用、记忆、MCP、Skills、思维树、结构化结果、Tracing、确定性 LightFlow 工作流和简单多智能体协作的 Agent 应用。

LightFlow 是什么?

LightFlow 是 v0.8.0 新增的工作流层,用于确定性的多步骤 Agent 执行。它支持命名步骤、依赖关系、步骤级重试、输出传递和工作流级 trace 事件。

from LightAgent import LightFlow

flow = (
    LightFlow()
    .step("research", agent=research_agent)
    .step("write", agent=writer_agent, depends_on=["research"])
)

result = flow.run("Analyze this company", trace=True)

更多内容见 LightFlow。

agent.run("hello") 还兼容吗?

兼容。默认仍然返回字符串。

response = agent.run("hello")
print(response)

如果需要结构化结果,可以显式开启:

result = agent.run("hello", result_format="object")
print(result.content)
print(result.tool_calls)
print(result.trace_id)

agent.run(query, stream=True, user_id=user_id) 还兼容吗?

兼容。默认仍然返回旧版流式 generator。

for chunk in agent.run(query, stream=True, user_id=user_id):
    print(chunk, end="")

如果需要结构化流式事件:

for event in agent.run(query, stream=True, user_id=user_id, result_format="event"):
    print(event.type, event.data)

支持哪些模型提供商?

LightAgent 使用 OpenAI-compatible Chat Completions API。只要模型服务兼容该接口,就可以通过 model、api_key、base_url 接入。常见场景包括 OpenAI、OpenRouter、DeepSeek/Qwen 兼容接口、vLLM、llama.cpp server mode 和 Ollama OpenAI-compatible API。

如果使用工具调用、MCP 或 Skills,需要确认所选模型支持 OpenAI-compatible function calling。

如何自定义工具?

定义一个 Python 函数,并给函数添加 tool_info 元数据:

def get_weather(city_name: str) -> str:
    return f"{city_name} is sunny."

get_weather.tool_info = {
    "tool_name": "get_weather",
    "tool_description": "Get current weather information for a city.",
    "tool_params": [
        {
            "name": "city_name",
            "description": "The city name to query",
            "type": "string",
            "required": True,
        }
    ],
}

然后在初始化 Agent 或调用 run() 时传入:

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

更多内容见 Tools。

如何使用记忆?

传入一个实现 store(data, user_id) 和 retrieve(query, user_id) 的对象即可。

agent = LightAgent(
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
    memory=memory_backend,
)

共享记忆后端建议配置 MemoryPolicy 或 memory_namespace,避免不同用户、租户或环境之间的记忆混用。更多内容见 Memory 和 Security。

如何接入 MCP?

配置 mcp_settings 后调用异步方法 setup_mcp():

import asyncio

asyncio.run(agent.setup_mcp(mcp_setting=mcp_settings))

v1.0.0 安装 mcp extra 后支持 stdio、SSE 和 Streamable HTTP;详情见 工具和集成。

Skills 和 Tools 有什么区别?

Tools 负责执行动作,例如查天气、调用数据库、执行代码或访问外部 API。

Skills 负责提供可复用的任务说明、流程、参考资料、脚本和资产。LightAgent 会发现 SKILL.md 元数据,并在任务匹配时通过 Skill 工具激活完整说明。

如何调试一次运行?

推荐使用结构化结果和 trace:

result = agent.run("hello", result_format="object", trace=True)
print(result.content)
print(result.trace)

也可以开启本地 debug 日志:

agent = LightAgent(
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
    debug=True,
    log_level="DEBUG",
)

常见错误码是什么意思?

  • LA-401: 鉴权失败。
  • LA-404: 模型、endpoint 或资源不存在。
  • LA-413: 请求过大。
  • LA-429: 触发限流。
  • LA-JSON: JSON 或工具参数解析失败。
  • LA-TOOL: 工具执行失败。

更多内容见 Tracing and Debugging。

如何贡献?

请先阅读:

还有哪些重要页面?

Clone this wiki locally