自定义工具开发规范 for AI Agent Harness

SuperAGI2025

80人浏览 · 2026-06-14 21:58:20

SuperAGI2025 · 2026-06-14 21:58:20 发布

1. 标题选项

《AI Agent 落地必看：自定义工具开发全规范（适配Harness框架）》
《从0到1写AI Agent可调用工具：符合Harness标准的开发最佳实践》
《避免90%的工具调用Bug：AI Agent Harness 自定义工具开发规范手册》
《让大模型100%正确调用你的工具：Harness框架工具开发官方级规范》

2. 引言

痛点引入

你有没有遇到过这些问题：自己花了半天写的工具，集成到AI Agent Harness里之后，大模型要么死活不调用，要么一调用就参数错误，要么返回的结果大模型根本读不懂？调试的时候翻遍日志，一会儿是工具元数据不符合要求，一会儿是参数没有类型标注，一会儿是敏感信息不小心暴露给了大模型，甚至出现过用户让Agent调用删除文件工具，直接把服务器的系统文件删掉的安全事故？
这些问题根本原因不是你写的代码逻辑有问题，而是你没有遵守AI Agent Harness的工具开发规范。AI Agent的工具和普通业务工具完全不一样：它既要被大模型理解，又要被Harness框架调度，还要兼顾安全性、可复用性，任何一个环节不达标，都会导致整个Agent的能力崩塌。

文章内容概述

本文是适配所有主流AI Agent Harness框架（包括LangChain、AutoGPT、LlamaIndex、自研Harness等）的自定义工具开发全规范，我们将从核心概念、结构设计、参数规范、安全校验、调试测试、部署监控全流程，手把手教你写出大模型爱用、Harness好调度、安全无风险的高质量工具。

读者收益

读完本文你将掌握：

AI Agent Harness工具的核心组成和运行逻辑
符合行业通用标准的工具开发流程和代码模板
99%避免工具调用Bug的参数设计和校验方法
工具的安全防护方案，杜绝敏感信息泄露和越权操作
兼容所有主流Agent框架的工具设计思路，一次开发多处使用

3. 准备工作

技术栈/知识要求

掌握Python 3.8+基础语法，熟悉面向对象编程
了解AI Agent的基本工作原理，知道什么是Function Call（工具调用）
理解Pydantic参数校验、HTTP请求、异常处理等基础后端开发知识

环境/工具要求

已安装Python 3.8+、pip/poetry包管理工具
拥有AI Agent Harness运行环境（可使用开源框架LangChain快速搭建测试环境）
安装工具开发SDK：pip install agent-harness-tool-sdk pydantic requests

4. 核心内容：手把手实战

步骤一：理解AI Agent Harness工具的核心概念

核心概念

首先我们要明确几个核心定义：

AI Agent Harness：Agent的执行调度引擎，核心职责是接收用户请求、调用大模型、解析大模型的工具调用指令、调度执行对应工具、将工具返回结果喂给大模型、最终生成回答返回给用户。Harness的核心组件包括：工具注册中心、调用解析器、执行调度器、结果处理器。
自定义工具：由开发者开发的、可供Agent调用的原子能力模块，比如天气查询、订单查询、邮件发送、数据库操作等，是Agent连接外部世界的核心入口。
工具元数据：专门给大模型和Harness看的工具描述信息，包括工具名称、功能描述、参数Schema、返回示例等，是大模型能不能正确调用工具的核心依据。

问题背景

在没有统一规范之前，工具开发是完全自由的：开发者随便写一个函数，把名字和参数随便填到Harness里，就想让大模型调用。但大模型不是人，它只能严格按照元数据的描述来理解工具的能力和参数要求，元数据写得不好，大模型100%会调用出错。

概念关系ER图

工具核心要素组成

工具调用成功率数学模型

工具调用的成功率由三个核心因素决定：
$\times P(依赖可用) \times P(逻辑正确)$
其中：

$P (参数正确)$ ：大模型传入的参数符合要求的概率，由参数Schema的描述清晰度和校验严格程度决定
$P (依赖可用)$ ：工具依赖的外部服务（API、数据库等）的可用性
$P (逻辑正确)$ ：工具自身业务代码无Bug的概率
按照我们的规范开发， $P (参数正确)$ 可以提升到99%以上，整体调用成功率可以稳定在95%以上。

步骤二：工具开发前置约束规范

命名规范

工具命名是大模型识别工具能力的第一入口，必须严格遵守以下规则：

统一使用蛇形小写命名，比如get_weather、query_user_order，禁止使用驼峰、拼音、缩写
名称必须精准描述工具能力，禁止使用模糊名称，比如禁止叫get_data，要叫get_user_order_by_order_id
名称长度控制在3-30个字符之间，过短语义不明，过长会浪费大模型Token

参数规范

参数分为初始化参数和调用参数两类，两者的区别如下表：

对比维度	初始化参数	调用参数
定义位置	工具类`__init__`方法的参数	工具参数Schema的字段、`_run`方法的参数
赋值时机	工具实例化时由开发者/运维赋值	工具调用时由Harness解析大模型输出赋值
是否暴露给大模型	绝对不暴露，不会出现在工具元数据中	完全暴露，大模型可以看到所有参数的类型、描述
用途	存储敏感配置、全局依赖，比如API密钥、数据库连接	传递每次调用的动态参数，比如城市名、订单ID
安全要求	必须加密存储，禁止硬编码在代码中	必须做严格校验，防止注入、越权攻击
调用参数的设计必须遵守以下规则：

所有参数必须添加类型标注，禁止使用Any类型
所有参数必须添加清晰的描述，包括：参数含义、取值范围、格式要求、示例，比如city的描述要写：字符串类型，要查询天气的中国大陆城市中文名，例如：北京、深圳，不支持英文或拼音
必填参数不要设置默认值，可选参数必须明确标注默认值
参数数量控制在10个以内，过多的参数会增加大模型的调用难度，复杂参数可以拆分为多个工具

返回值规范

返回值必须同时满足Harness的解析要求和大模型的理解要求：

必须返回可序列化的JSON格式，禁止返回Python对象、二进制数据
统一返回结构：{"code": 状态码, "msg": 消息, "data": 业务数据}，状态码定义参考HTTP状态码
正常返回时code为200，data只返回大模型需要的关键字段，禁止返回冗余信息浪费Token
异常返回时code为对应错误码，msg必须明确说明错误原因和修正方案，比如不要只返回参数错误，要返回参数错误：城市名Beijing不合法，请使用中文城市名

步骤三：工具的标准结构实现

我们基于agent-harness-tool-sdk提供的BaseTool基类，实现工具的标准结构，以下是完整的代码模板和说明：

基类定义（SDK内置，无需开发者编写）

from abc import ABC, abstractmethod
from typing import Any, Dict, Type
from pydantic import BaseModel

class BaseTool(ABC):
    # 工具元数据，子类必须覆写
    name: str  # 工具唯一名称
    description: str  # 工具功能描述
    args_schema: Type[BaseModel]  # 参数校验模型
    # 工具配置属性，子类可选覆写
    need_confirmation: bool = False  # 调用前是否需要用户确认（危险操作设为True）
    timeout: int = 30  # 调用超时时间，单位秒

    @abstractmethod
    def _run(self, **kwargs) -> Any:
        """同步执行逻辑，子类必须实现"""
        pass

    async def _arun(self, **kwargs) -> Any:
        """异步执行逻辑，子类可选实现，默认调用同步方法"""
        return self._run(**kwargs)

    def run(self, **kwargs) -> Dict[str, Any]:
        """Harness调用入口，禁止重写，内置参数校验、异常处理"""
        try:
            # 参数校验
            validated_args = self.args_schema(**kwargs).dict()
            # 执行核心逻辑
            result = self._run(**validated_args)
            # 结果序列化
            return self._serialize_result(result)
        except Exception as e:
            return self._handle_exception(e)

    async def arun(self, **kwargs) -> Dict[str, Any]:
        """异步调用入口，禁止重写"""
        try:
            validated_args = self.args_schema(**kwargs).dict()
            result = await self._arun(**validated_args)
            return self._serialize_result(result)
        except Exception as e:
            return self._handle_exception(e)

    def _serialize_result(self, result: Any) -> Dict[str, Any]:
        """结果序列化，可根据需求重写"""
        return {
            "code": 200,
            "msg": "success",
            "data": result
        }

    def _handle_exception(self, e: Exception) -> Dict[str, Any]:
        """异常处理，可根据需求重写"""
        return {
            "code": 500,
            "msg": f"tool {self.name} run error: {str(e)}",
            "data": None
        }

自定义工具实现示例（天气查询工具）

import requests
from pydantic import BaseModel, Field, validator
from typing import Optional
from agent_harness_tool_sdk import BaseTool

# 1. 定义参数校验模型
class GetWeatherArgs(BaseModel):
    city: str = Field(description="要查询天气的中国大陆城市中文名，例如：北京、深圳，不支持英文/拼音")
    days: Optional[int] = Field(default=1, description="要查询未来几天的天气，取值范围1-7，默认1")

    # 参数自定义校验
    @validator("city")
    def check_city_is_chinese(cls, v):
        if not all('\u4e00' <= char <= '\u9fff' for char in v):
            raise ValueError("城市名必须为中文，请输入正确的中文城市名")
        return v

    @validator("days")
    def check_days_range(cls, v):
        if v < 1 or v > 7:
            raise ValueError("查询天数只能在1-7之间")
        return v

# 2. 实现工具类
class GetWeatherTool(BaseTool):
    # 元数据配置
    name = "get_weather"
    description = """
    查询指定城市的实时或未来天气信息，适用场景：
    1. 用户询问某个城市的当前天气
    2. 用户询问未来几天某个城市会不会下雨、降温
    不适用场景：
    1. 查询国外城市的天气
    2. 查询历史天气
    返回信息包含：温度范围、天气状况、风力风向
    """
    args_schema = GetWeatherArgs
    need_confirmation = False
    timeout = 10

    # 3. 初始化方法：传入敏感参数，初始化依赖
    def __init__(self, weather_api_key: str):
        self.api_key = weather_api_key
        self.base_url = "https://api.weather.example.com/query"

    # 4. 核心执行逻辑：实现业务功能
    def _run(self, city: str, days: int = 1) -> Dict[str, Any]:
        params = {
            "city": city,
            "days": days,
            "key": self.api_key
        }
        # 发起HTTP请求
        response = requests.get(self.base_url, params=params, timeout=self.timeout)
        response.raise_for_status()
        raw_data = response.json()
        # 过滤冗余字段，只返回大模型需要的信息
        return {
            "city": city,
            "days": days,
            "weather_list": [
                {
                    "date": item["date"],
                    "temperature": f"{item['min_temp']}°C ~ {item['max_temp']}°C",
                    "weather": item["weather"],
                    "wind": f"{item['wind_direction']}{item['wind_level']}级"
                } for item in raw_data["data"]
            ]
        }

    # 5. 可选：实现异步执行逻辑，提升并发性能
    async def _arun(self, city: str, days: int = 1) -> Dict[str, Any]:
        import aiohttp
        params = {
            "city": city,
            "days": days,
            "key": self.api_key
        }
        async with aiohttp.ClientSession() as session:
            async with session.get(self.base_url, params=params, timeout=self.timeout) as response:
                response.raise_for_status()
                raw_data = await response.json()
                return {
                    "city": city,
                    "days": days,
                    "weather_list": [
                        {
                            "date": item["date"],
                            "temperature": f"{item['min_temp']}°C ~ {item['max_temp']}°C",
                            "weather": item["weather"],
                            "wind": f"{item['wind_direction']}{item['wind_level']}级"
                        } for item in raw_data["data"]
                    ]
                }

代码关键说明

为什么要把weather_api_key放在__init__里？因为这是敏感信息，绝对不能暴露给大模型，否则会出现密钥泄露的风险
为什么description要写适用和不适用场景？大模型的工具选择能力有限，明确的场景说明可以大幅降低大模型选错工具的概率
为什么要过滤返回字段？大模型的上下文窗口是有限的，冗余信息会浪费Token，还会干扰大模型的判断，只返回必要字段可以提升回答质量

步骤四：工具安全与校验规范

工具是Agent连接外部世界的入口，一旦出现安全问题，会造成严重的损失，必须严格遵守以下安全规范：

参数校验

所有调用参数必须经过两层校验：

Pydantic自动校验：校验参数类型、必填性、取值范围等基础规则
业务逻辑校验：校验参数的业务合法性，比如查询订单时校验当前用户是否有订单的访问权限
示例（订单查询工具的权限校验）：

def _run(self, order_id: str, user_id: str) -> Dict[str, Any]:
    # 业务校验：订单是否存在
    order = db.query(Order).filter(Order.id == order_id).first()
    if not order:
        raise ValueError(f"订单{order_id}不存在")
    # 业务校验：用户是否有权限访问订单
    if order.user_id != user_id:
        raise ValueError(f"你没有权限查看订单{order_id}")
    return order.to_dict()

注意：这里的user_id是Harness传入的上下文参数，不是大模型传入的，不会被篡改，保证了权限校验的安全性。

风险操作控制

涉及以下风险操作的工具，必须将need_confirmation设为True，Harness会在调用前询问用户确认：

数据删除、修改操作（比如删除订单、修改用户信息）
支付、扣费操作
邮件、短信发送操作
系统命令执行操作

调用频率限制

每个工具必须设置合理的QPS限制，避免被恶意调用导致外部服务被刷，示例：

from limits import Limiter, MemoryStorage, RateLimitItemPerMinute

limiter = Limiter(storage=MemoryStorage())

class GetWeatherTool(BaseTool):
    # ... 其他配置
    rate_limit = RateLimitItemPerMinute(100)  # 每分钟最多调用100次

    def _run(self, city: str, days: int = 1) -> Dict[str, Any]:
        if not limiter.check(self.rate_limit, "get_weather"):
            raise ValueError("调用频率过高，请1分钟后再试")
        # ... 业务逻辑

敏感信息过滤

工具返回结果中如果包含敏感信息（比如用户手机号、身份证号、密钥），必须进行脱敏处理：

def _desensitize_phone(phone: str) -> str:
    return phone[:3] + "****" + phone[7:] if phone else ""

步骤五：工具调试与测试规范

本地单测

每个工具开发完成后，必须先本地测试，覆盖以下场景：

正常场景：传入合法参数，验证返回结果是否符合预期
异常参数场景：传入非法参数，验证是否返回明确的错误信息
依赖失败场景：模拟外部服务不可用，验证是否返回正确的错误信息
测试代码示例：

if __name__ == "__main__":
    # 初始化工具
    tool = GetWeatherTool(weather_api_key="your_api_key")
    # 测试正常场景
    res1 = tool.run(city="北京", days=3)
    print("正常调用结果：", res1)
    assert res1["code"] == 200
    # 测试异常参数：城市名是英文
    res2 = tool.run(city="Beijing", days=3)
    print("异常参数结果：", res2)
    assert res2["code"] == 500
    assert "中文" in res2["msg"]
    # 测试异常参数：天数超过7
    res3 = tool.run(city="上海", days=10)
    print("天数异常结果：", res3)
    assert res3["code"] == 500
    assert "1-7" in res3["msg"]

Harness联调

本地测试通过后，需要和Harness联调，验证以下内容：

工具元数据是否被Harness正确解析，生成的Function Call Schema是否符合要求
大模型是否能正确识别工具的能力，在合适的场景发起调用
工具返回结果是否能被大模型正确理解，生成准确的回答
联调时打开Harness的调试日志，查看每一步的调用参数和返回结果，快速定位问题。

5. 进阶探讨

组合工具开发

当需要多个原子工具配合完成复杂任务时，可以开发组合工具，将多个工具的能力整合，减少大模型的调用次数，提升效率，示例（旅行规划组合工具）：

class TravelPlanArgs(BaseModel):
    departure_city: str = Field(description="出发城市中文名")
    destination_city: str = Field(description="目的地城市中文名")
    travel_date: str = Field(description="旅行日期，格式YYYY-MM-DD")

class TravelPlanTool(BaseTool):
    name = "generate_travel_plan"
    description = "根据出发地、目的地和日期生成旅行计划，包含天气、机票推荐、注意事项"
    args_schema = TravelPlanArgs

    def __init__(self, weather_api_key: str, flight_api_key: str):
        self.weather_tool = GetWeatherTool(weather_api_key)
        self.flight_tool = GetFlightTool(flight_api_key)

    def _run(self, departure_city: str, destination_city: str, travel_date: str) -> Dict[str, Any]:
        # 调用天气工具
        weather_res = self.weather_tool.run(city=destination_city, days=1)
        if weather_res["code"] != 200:
            raise ValueError(f"查询天气失败：{weather_res['msg']}")
        weather = weather_res["data"]["weather_list"][0]
        # 调用机票工具
        flight_res = self.flight_tool.run(departure=departure_city, destination=destination_city, date=travel_date)
        if flight_res["code"] != 200:
            raise ValueError(f"查询机票失败：{flight_res['msg']}")
        flights = flight_res["data"]["flight_list"][:3]
        # 生成计划
        return {
            "weather": weather,
            "recommended_flights": flights,
            "notes": "带好雨伞" if "雨" in weather["weather"] else "无特殊注意事项"
        }

性能优化

缓存：对于不常变化的数据（比如天气、公共信息），使用Redis缓存查询结果，减少重复的外部调用
异步实现：IO密集型工具（比如HTTP请求、数据库查询）实现_arun方法，Harness异步调度时可以大幅提升并发性能
结果裁剪：返回结果只保留大模型需要的字段，减少Token消耗

通用工具封装

可以封装常用的通用工具模板，减少重复开发，比如：

HTTP请求工具：支持GET/POST请求，自动处理参数和返回值
数据库查询工具：支持SQL查询，自动做SQL注入防护
文件处理工具：支持文件读写、格式转换，自动做路径校验防止目录遍历

6. 行业发展与未来趋势

时间	阶段	工具开发特点	代表产品/框架
2022年之前	早期探索阶段	工具和Agent强绑定，没有统一规范，开发者自由发挥	早期AutoGPT
2022-2023年	规范萌芽阶段	各框架推出自己的工具规范，跨框架复用性差	LangChain、LlamaIndex
2023-2024年	通用规范阶段	跨框架的通用工具规范出现，兼容OpenAI Function Call标准	OpenAI GPTs Actions、字节Coze
2024年之后	标准化市场化阶段	工具市场成熟，开发者开发的工具可以在所有Agent平台直接使用，不需要修改	各大厂的Agent工具市场

7. 最佳实践Tips

单一职责原则：一个工具只做一件事，不要开发万能工具，大模型的选择能力有限，工具越精准，调用成功率越高
描述越详细越好：工具的description要尽可能详细，包括适用场景、不适用场景、参数示例、返回示例，不要怕浪费Token，这会大幅降低调用错误率
错误信息要友好：异常返回的msg要明确告诉大模型哪里错了，怎么修正，比如参数错误：日期格式不对，应该是YYYY-MM-DD，例如2024-05-20，大模型可以自动修正参数重新调用
定期清理无用工具：Agent的工具列表不要超过20个，太多的工具会增加大模型的选择难度，长时间没人调用的工具要及时下线
监控工具运行状态：每个工具都要监控调用次数、成功率、响应时间、错误率，及时发现和修复问题，可用性要达到99.9%以上才能用于生产环境