工具API

简介

AgentChat工具系统提供了一套完整的API接口，用于管理和配置Agent可用的工具集。该系统支持两种主要的工具类型：传统Python工具函数和基于Model Context Protocol (MCP) 的外部服务器工具。通过统一的API接口，开发者可以查询可用工具列表、创建自定义工具、配置工具参数，并将工具与Agent进行集成。

工具系统的核心设计理念是提供灵活的扩展机制，既支持内置的Python工具函数，也支持通过MCP协议集成外部服务。这种设计使得AgentChat能够无缝集成各种第三方服务，同时保持良好的可维护性和扩展性。

项目结构

工具系统的文件组织结构清晰地反映了其分层架构：

图表来源

章节来源

核心组件

工具系统由以下核心组件构成：

API路由器

负责处理HTTP请求和响应，提供RESTful接口。

工具服务层

包含业务逻辑处理，提供工具的增删改查功能。

数据访问对象

封装数据库操作，提供数据持久化能力。

工具模型

定义工具的数据结构和验证规则。

MCP服务器

支持外部服务集成，实现Model Context Protocol协议。

章节来源

架构概览

工具系统采用分层架构设计，确保了良好的可维护性和扩展性：

图表来源

详细组件分析

工具API端点

工具系统提供了完整的RESTful API接口，支持工具的全生命周期管理：

GET /api/v1/tool/all

获取所有可用工具的列表。

POST /api/v1/tool/create

创建新的自定义工具。

POST /api/v1/tool/own

获取当前用户创建的个人工具。

POST /api/v1/tool/visible

获取当前用户可见的所有工具。

PUT /api/v1/tool/update

更新现有工具的配置信息。

DELETE /api/v1/tool/delete

删除指定的工具。

图表来源

章节来源

工具数据模型

工具系统使用SQLModel框架定义数据模型，确保数据的一致性和完整性：

图表来源

章节来源

API端点文档

查询所有工具

端点: GET /api/v1/tool/all

功能: 获取系统中所有可用工具的完整列表。

请求参数: 无

响应格式:

json

{
  "status_code": 200,
  "status_message": "success",
  "data": [
    {
      "tool_id": "uuid",
      "zh_name": "天气查询",
      "en_name": "get_weather",
      "user_id": "0",
      "description": "查询指定城市的天气情况",
      "logo_url": "https://example.com/logo.png"
    }
  ]
}

状态码:

200: 成功获取工具列表
500: 服务器内部错误

创建自定义工具

端点: POST /api/v1/tool/create

功能: 创建新的自定义工具，供用户专用。

请求体:

json

{
  "zh_name": "中文名称",
  "en_name": "english_name",
  "description": "工具描述",
  "logo_url": "https://example.com/logo.png"
}

响应格式:

json

{
  "status_code": 200,
  "status_message": "success",
  "data": {
    "tool_id": "uuid"
  }
}

获取个人工具

端点: POST /api/v1/tool/own

功能: 获取当前登录用户创建的所有个人工具。

响应格式:

json

{
  "status_code": 200,
  "status_message": "success",
  "data": [
    {
      "tool_id": "uuid",
      "zh_name": "个人工具",
      "en_name": "personal_tool",
      "user_id": "user_uuid",
      "description": "个人专用工具",
      "logo_url": "https://example.com/logo.png"
    }
  ]
}

获取可见工具

端点: POST /api/v1/tool/visible

功能: 获取当前用户可见的所有工具，包括系统工具和个人工具。

响应格式:

json

{
  "status_code": 200,
  "status_message": "success",
  "data": [...]
}

更新工具配置

端点: PUT /api/v1/tool/update

功能: 更新现有工具的配置信息。

请求体:

json

{
  "tool_id": "uuid",
  "zh_name": "新中文名称",
  "en_name": "new_english_name",
  "description": "新描述",
  "logo_url": "https://example.com/new_logo.png"
}

删除工具

端点: DELETE /api/v1/tool/delete

功能: 删除指定的工具，仅限工具创建者或管理员操作。

请求参数:

json

{
  "tool_id": "uuid"
}

章节来源

工具元数据结构

工具系统定义了详细的元数据结构，用于描述工具的特性和行为：

基础元数据字段

字段名	类型	描述	必填
tool_id	string	工具唯一标识符	是
zh_name	string	工具中文名称，显示给用户	是
en_name	string	工具英文名称，大模型调用	是
user_id	string	工具对应的创建用户ID	是
logo_url	string	工具对应的Logo地址	是
description	string	大模型将根据此描述识别并调用该工具	是
create_time	datetime	创建时间	否
update_time	datetime	修改时间	否

输入参数Schema

工具系统支持复杂的输入参数Schema定义，用于描述工具的输入要求：

图表来源

tool.py

章节来源

MCP协议集成

AgentChat工具系统深度集成了Model Context Protocol (MCP)，实现了与外部服务的无缝连接：

MCP架构设计

图表来源

MCP工具实现示例

以天气查询工具为例，展示MCP协议的实现方式：

图表来源

mcp_weather.py

MCP服务器类型

系统支持多种MCP传输协议：

协议类型	描述	使用场景
stdio	标准输入输出模式	简单的命令行工具集成
websocket	WebSocket连接	实时双向通信
streamable-http	HTTP流模式	异步数据传输

章节来源

工具函数编写规范

AgentChat提供了标准化的工具函数编写规范，确保工具的一致性和可维护性：

工具函数模板

图表来源

action.py

工具函数特征

装饰器使用: 使用@tool(parse_docstring=True)装饰器
参数类型注解: 明确的参数类型定义
文档字符串: 详细的函数说明和参数描述
错误处理: 完善的异常处理机制
响应格式: 标准化的返回值格式

工具函数示例

天气查询工具展示了完整的工具函数实现：

图表来源

action.py

章节来源

自定义工具扩展

内置工具扩展

系统提供了丰富的内置工具，涵盖了常见的业务场景：

工具类别	工具名称	功能描述
信息查询	get_weather	查询指定城市的天气情况
搜索工具	tavily_search	基于Tavily的网页搜索
搜索工具	google_search	Google搜索引擎集成
文档处理	convert_to_pdf	文档格式转换
文档处理	convert_to_docx	Word文档处理
图像处理	text_to_image	文本转图像生成
图像处理	image_to_text	图像内容识别
邮件服务	send_email	邮件发送功能
物流查询	get_delivery_info	物流信息追踪

自定义工具开发流程

工具注册机制

系统通过模块导入自动发现和注册工具：

图表来源

init.py

章节来源

init.py

故障排除指南

常见问题及解决方案

工具调用失败

问题: 工具调用返回错误或超时

排查步骤:

检查工具函数的参数格式是否正确
验证外部API的可用性和认证信息
查看服务器日志获取详细错误信息
确认网络连接和防火墙设置

MCP服务器连接问题

问题: 无法连接到MCP服务器

排查步骤:

验证MCP服务器是否正常启动
检查端口配置和网络可达性
确认传输协议设置正确
查看MCP服务器的日志输出

权限验证失败

问题: 用户无法访问某些工具

排查步骤:

检查用户的权限级别
验证工具的创建者信息
确认工具的可见性设置
检查用户认证状态

性能优化建议

缓存机制: 对频繁调用的工具结果进行缓存
异步处理: 使用异步方式处理耗时的工具调用
批量操作: 尽可能使用批量API减少网络开销
资源监控: 监控工具的资源使用情况

章节来源

结论

AgentChat工具系统提供了一个完整、灵活且可扩展的工具管理平台。通过统一的API接口，开发者可以轻松地查询、创建、配置和管理各种类型的工具。系统支持传统的Python工具函数和基于MCP协议的外部服务集成，为构建智能Agent提供了强大的基础设施。

工具系统的设计充分考虑了可维护性、可扩展性和易用性，通过清晰的分层架构和标准化的开发规范，确保了系统的稳定性和可靠性。无论是内置工具还是自定义扩展，都能通过统一的接口进行管理，大大简化了Agent的功能扩展过程。

随着AI技术的不断发展，工具系统将继续演进，支持更多的集成方式和更丰富的功能特性，为构建更加智能和实用的AI应用提供坚实的基础。

工具API ​

目录 ​

简介 ​

项目结构 ​

核心组件 ​

API路由器 ​

工具服务层 ​

数据访问对象 ​

工具模型 ​

MCP服务器 ​

架构概览 ​

详细组件分析 ​

工具API端点 ​

GET /api/v1/tool/all ​

POST /api/v1/tool/create ​

POST /api/v1/tool/own ​

POST /api/v1/tool/visible ​

PUT /api/v1/tool/update ​

DELETE /api/v1/tool/delete ​

工具数据模型 ​

API端点文档 ​

查询所有工具 ​

创建自定义工具 ​

获取个人工具 ​

获取可见工具 ​

更新工具配置 ​

删除工具 ​

工具元数据结构 ​

基础元数据字段 ​

输入参数Schema ​

MCP协议集成 ​

MCP架构设计 ​

MCP工具实现示例 ​

MCP服务器类型 ​

工具函数编写规范 ​

工具函数模板 ​

工具函数特征 ​

工具函数示例 ​

自定义工具扩展 ​

内置工具扩展 ​

自定义工具开发流程 ​

工具注册机制 ​

故障排除指南 ​

常见问题及解决方案 ​

工具调用失败 ​

MCP服务器连接问题 ​

权限验证失败 ​

性能优化建议 ​

结论 ​

工具API

目录

简介

项目结构

核心组件

API路由器

工具服务层

数据访问对象

工具模型

MCP服务器

架构概览

详细组件分析

工具API端点

GET /api/v1/tool/all

POST /api/v1/tool/create

POST /api/v1/tool/own

POST /api/v1/tool/visible

PUT /api/v1/tool/update

DELETE /api/v1/tool/delete

工具数据模型

API端点文档

查询所有工具

创建自定义工具

获取个人工具

获取可见工具

更新工具配置

删除工具

工具元数据结构

基础元数据字段

输入参数Schema

MCP协议集成

MCP架构设计

MCP工具实现示例

MCP服务器类型

工具函数编写规范

工具函数模板

工具函数特征

工具函数示例

自定义工具扩展

内置工具扩展

自定义工具开发流程

工具注册机制

故障排除指南

常见问题及解决方案

工具调用失败

MCP服务器连接问题

权限验证失败

性能优化建议

结论