ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

PraisonAI Agents Tools 开发指南:从函数工具到 pip 插件包的完整实践

PraisonAI Agents Tools 开发指南:从函数工具到 pip 插件包的完整实践 PraisonAI Agents Tools 开发指南从函数工具到 pip 插件包的完整实践【免费下载链接】PraisonAIPraisonAI — Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous self-improving agents that research, plan, code, and execute tasks. Deployed in 5 lines of code with built-in memory, RAG, and support for 100 LLMs.项目地址: https://gitcode.com/GitHub_Trending/pr/PraisonAI导读本文以 PraisonAI Agents 的 Tools 官方指南 为核心骨架系统讲解 PraisonAI 中工具Tool的核心概念、函数式与类式两种创建范式、基于 entry_points 的插件分发机制并结合praisonaiagents/tools目录下的真实源码BaseTool、tool 装饰器、ToolRegistry深入剖析工具注册、Schema 自动生成与自动发现的底层原理。读完本文你将能够独立为 Agent 编写、测试并打包分发自己的工具让 Agent 获得搜索、抓取、行情查询等任意特殊能力。什么是 ToolAgent 的特殊能力在 PraisonAI 中一个Tool工具就是一段赋予 AI Agent 特定能力的代码。可以把工具想象成我们给 Agent 装备的特殊能力互联网搜索工具让 Agent 具备联网检索网页的能力股票行情工具让 Agent 能查询实时股价与公司信息天气工具让 Agent 能获取指定地点的天气状况。从源码实现看工具的本质是可以被 LLM 调用并返回可序列化结果的函数或对象。PraisonAI 为工具建立了一套完整的抽象体系核心定义位于 tools/base.pyBaseTool是全部工具的抽象基类它强制要求子类实现run()方法并通过get_schema()输出 OpenAI 兼容的 function calling 结构{type: function, function: {...}}这样无论是 OpenAI、Gemini 还是其他 100 兼容 LLM都能理解并调用你的工具。插件系统把工具打包成 pip 安装包PraisonAI 现在支持完整的插件系统Plugin System外部开发者可以创建可通过pip install安装的工具包安装后工具会被 PraisonAI 自动发现。这是将自定义工具分发给社区或其他团队的标准方式。快速开始两种在代码中定义工具的方式from praisonaiagents import BaseTool, tool, Agent # 方法一基于类Class-based class WeatherTool(BaseTool): name get_weather description Get weather for a location def run(self, location: str) - dict: return {temp: 72, condition: sunny} # 方法二基于装饰器Decorator-based tool def search(query: str) - list: Search the web. return [{title: Result, url: https://...}] # 两种方式都可以直接挂载到 Agent 上 agent Agent( nameAssistant, tools[WeatherTool(), search] )从源码看BaseTool定义于 tools/base.py是一个抽象基类子类必须覆盖两个类属性name工具的唯一标识和description供 LLM 阅读的人性化描述直接影响模型何时选择调用该工具并实现抽象方法run()。tool装饰器定义于 tools/decorator.py则把普通函数包装成FunctionTool实例——它是BaseTool的子类因此两种方式产出的对象在 Agent 眼中完全等价可以混用。创建插件包Plugin Package的完整流程1. 创建工具包目录结构praisonai-weather/ ├── pyproject.toml ├── src/ │ └── praisonai_weather/ │ ├── __init__.py │ └── tools.py2. 在tools.py中定义工具from praisonaiagents import BaseTool class WeatherTool(BaseTool): name weather description Get current weather def run(self, location: str) - dict: # Your implementation return {temp: 72}3. 在pyproject.toml中通过 entry_points 注册[project] name praisonai-weather version 1.0.0 [project.entry-points.praisonaiagents.tools] weather praisonai_weather.tools:WeatherTool注意源码实证README 中使用的入口组名praisonaiagents.tools是历史组名。查看 tools/registry.py 可以发现当前官方规范入口组canonical group是praisonai.tools而praisonaiagents.tools与praisonai.tool_sources已降级为向后兼容的别名——别名组首次被发现时会发出DeprecationWarning且名称冲突时 canonical 组优先。因此新插件建议直接使用[project.entry-points.praisonai.tools]两种写法当前都能被识别。4. 用户安装并直接使用pip install praisonai-weatherfrom praisonaiagents import Agent # Tool is auto-discovered! agent Agent(tools[weather])这里的自动发现机制实现在 tools/registry.py 的ToolRegistry.discover_plugins()中注册表通过importlib.metadata.entry_points扫描安装包中声明为工具入口点的类或可调用对象类会被自动实例化并注册到全局注册表该扫描只执行一次_discovered标志且整个过程由threading.RLock保护天然适配多 Agent 并发场景。创建新工具两种范式1. 函数式Function-Based适合简单工具函数式最适合只做一件具体事情的简单工具就像只做加法的计算器。适用场景工具只完成一个简单任务不需要在多次调用之间记忆状态不需要与其他工具共享信息是一次性的快速操作。示例def internet_search(query: str): # Search the internet and return results return search_results使用方式from praisonaiagents.tools import internet_search results internet_search(AI news)源码层面internet_search是 tools/tools.py 中懒加载的 DuckDuckGo 搜索函数同时在 tools/init.py 的TOOL_MAPPINGS注册表中映射到duckduckgo_tools模块。你完全可以照葫芦画瓢把自己写的纯函数直接作为工具使用——PraisonAI 的解析器resolve_tool_name见 tools/resolver.py会依次尝试注册表 → 内置 TOOL_MAPPINGS → 可选外部包三级解析普通函数只要能被找到就能被 Agent 调用。2. 类式Class-Based适合复杂工具类式适合包含多个相关功能、或需要记忆信息的复杂工具就像一台能记住历史运算、支持多种数学操作的智能计算器。适用场景工具包含多个相互关联的功能需要记忆或共享信息需要高效管理资源如连接池有复杂的初始化配置需求。示例class StockTools: def get_stock_price(self, symbol): # Get current stock price return price def get_stock_info(self, symbol): # Get detailed stock information return info使用方式from praisonaiagents.tools import get_stock_price, get_stock_info price get_stock_price(AAPL) info get_stock_info(AAPL)类式的底层优势在于可以复用BaseTool的完整能力矩阵。从 tools/base.py 可以梳理出子类可用的关键资产成员作用name/description必填类属性工具的标识与 LLM 可读描述version工具版本号默认1.0.0parameters参数 JSON Schema不提供时会根据run()签名自动生成restart_safe声明工具的重启安全契约True表示只读/幂等、崩溃后可安全重跑False表示有副作用、恢复时绝不静默重放None默认表示未声明input_guardrails/output_guardrails仅作用于该工具的输入/输出护栏与Agent(guardrails...)的全局护栏不同run(**kwargs)抽象方法必须实现返回任意类型会字符串化后交给 LLMsafe_run(**kwargs)带异常捕获的执行入口统一返回ToolResult含success/error/metadata字段get_schema()输出 OpenAI 兼容的 function schema支持动态覆写validate()/validate_schema_roundtrip()定义期校验检查 name/description/run 是否齐全、Schema 能否通过 JSON 序列化往返此外ToolResult还支持多模态内容通道工具可以通过multimodal_content()、text_part()、image_part()、file_part()见 tools/base.py返回结构化文本/图片/文件片段使截图工具、图表渲染器等产出能直接成为下一轮对话中模型可见的消息部件。tool装饰器的进阶参数tool装饰器tools/decorator.py远不止包装函数那么简单它还暴露了与 Agent 对齐的完整配置面tool(nameweb_search, descriptionSearch the internet) def search(query: str, max_results: int 5) - list: return [...]availability传入() - (is_available, reason)回调运行时检查工具是否可用例如 API Key 缺失时自动对模型隐藏该工具结果会被注册表以 30 秒 TTL 缓存retry_policy为工具执行配置指数退避重试策略approval标记该工具需要人工审批True使用默认high风险等级字符串可显式指定critical/high/medium/low定义时即注册到全局 ApprovalRegistry本地、网关与服务化运行都会强制执行to_model_output提供result - compact_view回调给 LLM 喂精简摘要以节省上下文 token完整结果仍保留给展示、钩子与追踪restart_safe与BaseTool相同的重启安全声明input_guardrails/output_guardrails本工具专属的参数/结果护栏例如拦截发往外部域名的邮件、脱敏结果中的密钥Injected[T]参数将参数声明为Injected[dict]类型即可在调用时由框架自动注入会话状态如session_id此类参数会被自动排除出对外暴露的 Schema见 tools/decorator.py。如何选择你的实现方式动手前先问自己四个问题你的工具只做一件简单的事吗是 → 用函数式否 → 考虑类式你的工具需要记忆信息吗是 → 用类式否 → 用函数式工具的多个操作之间相互关联吗是 → 用类式否 → 用函数式你的工具需要高效管理资源吗是 → 用类式否 → 用函数式核心原则简单工具用函数复杂、有状态、需要资源管理的工具用类。真实世界示例两种范式的典型代表PraisonAI 内置工具本身就是两种范式的最佳范本全部可以通过from praisonaiagents.tools import ...导入互联网搜索工具函数式只做一件事搜索互联网无需记忆历史搜索每次搜索相互独立输入输出简单直接。SearxNG 搜索工具函数式基于本地 SearxNG 实例的隐私优先网页搜索支持可定制参数max_results结果数量上限、searxng_url实例地址每次搜索独立且安全是传统搜索引擎的隐私替代方案。其实现在 tools/searxng_tools.py默认连接http://localhost:32768/search聚合 google/bing/duckduckgo 多个引擎结果统一标准化为{title, url, snippet}格式并对连接失败、超时、解析错误均返回带error键的字典而不是抛异常——这正是错误处理优雅的代码示范。Spider 工具函数式通用网页抓取与爬取支持 CSS 选择器进行精确内容提取可抓取多页面并抽取链接/图片灵活应对各类爬取需求。Newspaper 工具函数式专注新闻文章抽取提取文章标题、正文、作者与发布日期内置 NLP 处理生成关键词与摘要按主题对新闻来源分类。股票行情工具类式做多件事查价格、查公司信息、查历史数据记忆股票信息以避免重复下载各操作相互关联都围绕股票高效管理连接资源。类式工具的典型调用链可以对照 tools/init.py注册表对类式工具采用缓存类、每次新建实例的工厂策略_create_tool_instance确保并发 Agent 之间不会共享可变状态、避免状态泄漏。上手步骤从零开始写一个工具选择范式依据上面的决策清单确定函数式还是类式创建工具文件起一个描述性的文件名如weather_tools.py放在praisonaiagents/tools目录下或你自己的包目录中编写工具添加清晰的文档字符串包含类型注解type hints以便于 Schema 自动生成优雅处理错误测试工具验证功能符合预期覆盖错误分支检查性能。关于 Schema 自动生成可以补充一个有趣的源码细节tools/schema.py 的annotation_to_json_schema会把 Python 类型注解翻译成 JSON Schema——Optional[int]变成{anyOf: [{type: integer}, {type: null}]}Literal[fast, deep]变成带枚举的字符串List[T]、Dict[K, V]、Enum 子类也各有对应。这意味着写好类型注解就等于给 LLM 写好了调用参数约束所以编写工具时务必为参数和返回值标注完整类型。最佳实践文档Documentation说明工具做什么、给什么输入、返回什么提供使用示例列出依赖与前置条件如 API Key、本地服务。错误处理Error Handling始终处理可能的异常返回有帮助的错误信息参考 searxng_tools 返回{error: ...}字典的做法绝不让工具崩溃中断整个 Agent 运行——safe_run()会在底层兜住异常并封装为ToolResult(successFalse, error...)。性能Performance保持高效不浪费资源适合时使用缓存股票工具记忆行情避免重复下载就是典型善用availability回调 TTL 缓存避免频繁探测不可用工具。用户友好User-Friendly让工具易于使用使用清晰的函数/方法命名name 会直接暴露给 LLM 作为调用标识保持简单不过度设计。需要帮助查看 tools 目录 下 60 个内置工具模块作为范例参考 examples/tools/example_tools_discover.py 了解如何枚举内置工具与外部工具包阅读 examples/tools/example_tools_resolve.py 与 examples/tools/example_tools_sources.py 学习工具名称解析与来源排查查阅 examples/tools/example_tools_discover.py 之外的工具示例文件理解常见用法查阅项目文档或查看官方 CLI 命令praisonai tools list的解析提示见 tools/resolver.py 中的_format_unknown。记住目标是做出易于使用、易于维护的工具。选择最适合你具体工具需求的方式让 Agent 的能力边界由你亲手定义。【免费下载链接】PraisonAIPraisonAI — Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous self-improving agents that research, plan, code, and execute tasks. Deployed in 5 lines of code with built-in memory, RAG, and support for 100 LLMs.项目地址: https://gitcode.com/GitHub_Trending/pr/PraisonAI创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表