Skip to content

V1 Tools and Integrations

weego edited this page Nov 15, 2026 · 2 revisions

工具和集成

简体中文 | English

适用版本:v1.0.0。工具是宿主授权的能力,不是模型提供的权限。工具参数应有 schema 和业务校验;只注册当前用户与工作区可用的能力。

Python 工具与诊断

这是一个无需密钥的 schema 和连接器验证示例。业务逻辑固定返回本地字符串:

from LightAgent import ConnectorManifest, ToolRegistry, validate_connector

def lookup(term: str) -> str:
    return {"lightagent": "轻量 Agent 框架"}.get(term.lower(), "无匹配")

lookup.tool_info = {
    "tool_name": "lookup",
    "tool_description": "查询本地术语表",
    "tool_params": [
        {"name": "term", "description": "术语", "type": "string", "required": True}
    ],
}

registry = ToolRegistry()
assert registry.register_tool(lookup)
assert not registry.validate_tools()

connector = ConnectorManifest(name="glossary", version="1.0.0", tools=[lookup])
report = validate_connector(connector)
assert report.valid, report.to_dict()
print(lookup("LightAgent"))

将 lookup 加进 LightAgent(..., tools=[lookup]) 可常驻注册;也可在单次 agent.run("查询 LightAgent", tools=[lookup]) 时传入,或用 load_tools() 从应用审查过的本地目录加载命名工具。使用 agent.validate_tools() 检查重复名称和 schema 诊断,测试时同时断言真正调用了预期工具,而不是只看回复。兼容 OpenAI 的模型也不一定支持所有 schema 或工具流式行为。工具组合、并发调度与会话级工具集限制见 工具参考。

内置工具与生成工具

  • 做简单数学,用默认的 safe_expression 或下列本地函数。它不是通用 Python 解释器;输入仍要符合业务限制。
  • 旧任意 Python 工具没有默认注册,模型及工具调度路径也会阻止它们。不要把旧执行器用于不受信代码;如需执行真实工作区任务,选用 显式后端 并实施独立隔离。
  • create_tool() 与 工具生成示例 用来生成草稿。不自动注册未审计代码;先查依赖、文件/网络副作用、参数与失败行为,再放进工具目录。
from LightAgent import evaluate_safe_expression

assert evaluate_safe_expression("2 * (3 + 4)") == 14

MCP:接入已审查的工具服务器

python -m pip install 'lightagent[mcp] @ git+https://github.com/wanxingai/LightAgent.git@v1.0.0'

在异步函数中对已经配置好模型的 agent 调用下列代码。先在本机启动受信服务器,再把 URL 替换为实际入口。示例服务无需凭据;生产凭据从环境或密钥管理系统解析,不置于仓库配置中。

mcp_settings = {
    "mcpServers": {
        "catalog": {
            "url": "http://127.0.0.1:8000/mcp",
            "transport": "streamable-http",
            "namespace": "catalog",
            "namespace_tools": True,
        },
    },
}

await agent.setup_mcp(mcp_setting=mcp_settings)
result = await agent.arun("用已授权的目录工具列出可见条目。", result_format="object")
print(result.content)

stdio 用 command、args 启动可信本地程序,SSE 使用 SSE 端点,Streamable HTTP 要显式配置 transport。保留 mcpServers 和 MCPClientManager 旧入口;创建实际连接才需要 MCP SDK。重连、工具清单刷新、命名空间与凭据解析见 MCP 配置参考、Tagged MCP 示例 和 运行时文档。连接成功不代表服务器提供的所有工具都应授权。

Skills:复用领域指令

PyYAML 是基础依赖,普通安装即可使用 Skills。以 skills/glossary/SKILL.md 为例:

---
name: glossary
description: 解释当前项目中的术语。
---

遇到项目术语问题时,先查询已注册的术语表工具。
查不到时说明未知,不虚构定义。

用 LightAgent(..., skills_directories=["./skills"]) 指定可信目录;默认也会发现约定路径,可用 auto_discover_skills=False 关闭自动发现。显式目录冲突可通过 SkillManager.list_conflicts() 诊断。Skill 只是声明与材料,不会自动获得脚本执行权限;不应将任意下载目录、脚本或 AGENTS.md 视为高信任指令。详见 Skills 和 工作区指南。

连接器、浏览器与对象存储

  • ConnectorManifest 聚合 tools、Skills、MCP 配置、Hooks、记忆适配、extras 和文档。前面的 validate_connector() 是离线检查,不安装依赖、不激活连接器,也不是安全证明。用 本地研究连接器 和 企业 API 注入示例 熟悉宿主如何选择组件。
  • 浏览器自动化是外部集成,基础安装不提供浏览器或远端浏览账户。参考 browser-use 适配 和 浏览器示例。先在自有或授权的无敏感数据页面验证,并为外部动作保留审批。
  • OSS/NOS 工具依赖 oss 或 nos extra 提供的 boto3。宿主配置受限的存储凭据和桶策略,仅授予目标对象所需权限。上传应有用户授权、审计与失败重试策略,避免凭据、私有文件或 URL 进入 Trace。

Clone this wiki locally