通用工具调用协议 (UTCP)

简介

通用工具调用协议 (UTCP) 是一种安全、可扩展的标准，用于在多种通信协议中定义和交互工具。UTCP 1.0.0 引入了基于插件架构的模块化核心，使其更具扩展性、可测试性，并且更易于打包。

与其他协议相比，UTCP 强调以下几点：

• 可扩展性：UTCP 旨在处理大量工具和提供商，同时不降低性能。
• 可扩展性：可插拔的架构使开发者能够轻松添加新的通信协议、工具存储机制和搜索策略，而无需修改核心库。
• 互操作性：随着越来越多的协议插件（包括 HTTP、SSE、CLI 等）的出现，UTCP 可以与几乎任何现有服务或基础设施集成。
• 易用性：该协议基于简单且定义明确的 Pydantic 模型，使得开发者可以轻松实现和使用。

仓库结构

此仓库包含完整的 UTCP Python 实现：

• core/ - 核心 utcp 包，包含基础组件（README）
• plugins/communication_protocols/ - 协议特定插件：
  • http/ - HTTP/REST、SSE、流式传输、OpenAPI（README）
  • cli/ - 命令行工具（README）
  • mcp/ - 模型上下文协议（README）
  • text/ - 基于文件的工具（README）
  • socket/ - TCP/UDP（🚧 开发中）
  • gql/ - GraphQL（🚧 开发中）

架构概览

UTCP 采用模块化架构，由核心库和协议插件组成：

核心包 (utcp)

core/ 目录包含基础组件：

• 数据模型：用于 Tool、CallTemplate、UtcpManual 和 Auth 的 Pydantic 模型
• 客户端接口：用于工具交互的主要 UtcpClient
• 插件系统：用于协议、仓库和搜索的可扩展接口
• 默认实现：内置的工具存储和搜索策略

快速入门

安装

安装核心库和所需的任何协议插件：

# 安装核心 + HTTP 插件（最常用）
pip install utcp utcp-http

# 根据需要安装其他插件
pip install utcp-cli utcp-mcp utcp-text

基本用法

from utcp.utcp_client import UtcpClient

# 使用 HTTP API 创建客户端
client = await UtcpClient.create(config={
    "manual_call_templates": [{
        "name": "my_api",
        "call_template_type": "http",
        "url": "https://api.example.com/utcp"
    }]
})

# 调用工具
result = await client.call_tool("my_api.get_data", {"id": "123"})

协议插件

UTCP 通过专用插件支持多种通信协议：

插件	描述	状态	文档
utcp-http	HTTP/REST API、SSE、流式传输	✅ 稳定	HTTP 插件 README
utcp-cli	命令行工具	✅ 稳定	CLI 插件 README
utcp-mcp	模型上下文协议	✅ 稳定	MCP 插件 README
utcp-text	本地基于文件的工具	✅ 稳定	Text 插件 README
utcp-websocket	WebSocket 实时双向通信	✅ 稳定	WebSocket 插件 README
utcp-socket	TCP/UDP 协议	🚧 开发中	Socket 插件 README
utcp-gql	GraphQL API	🚧 开发中	GraphQL 插件 README

在开发过程中，您可以从克隆的仓库中以可编辑模式安装这些包：

# 克隆仓库
git clone https://github.com/universal-tool-calling-protocol/python-utcp.git
cd python-utcp

# 以可编辑模式安装核心包及其开发依赖项
pip install -e "core[dev]"

# 以可编辑模式安装特定的协议插件
pip install -e plugins/communication_protocols/http

从 0.x 迁移到 1.0.0 的迁移指南

版本 1.0.0 引入了多项破坏性变更。请按照以下步骤迁移您的项目。

1. 更新依赖：安装新的 utcp 核心包以及您使用的特定协议插件（例如 utcp-http、utcp-cli）。
2. 配置：
   • 配置对象：UtcpClient 现在通过一个 UtcpClientConfig 对象、字典或包含配置的 JSON 文件路径来初始化。
   • 手动调用模板：移除了 providers_file_path 选项。现在不再使用文件路径，而是直接在 UtcpClientConfig 中提供 manual_call_templates 列表。
   • 术语变化：provider 一词已被替换为 call_template，而 provider_type 现在称为 call_template_type。
   • 可流式 HTTP：call_template_type 中的 http_stream 已更名为 streamable_http。
3. 更新导入语句：更改您的导入语句以反映新的模块化结构。例如，from utcp.client.transport_interfaces.http_transport import HttpProvider 将变为 from utcp_http.http_call_template import HttpCallTemplate。
4. 工具搜索：如果您之前使用的是默认搜索策略，新的策略是 TagAndDescriptionWordMatchStrategy。这是新的默认设置，除非您实现了自定义策略，否则无需进行任何更改。
5. 工具命名：工具名称现在采用命名空间格式，即 manual_name.tool_name。客户端会自动处理这一点。
6. 变量替换命名空间：在不同 call_templates 中被替换的变量，首先会使用手册名称进行命名空间划分，并将 _ 重复一次。因此，在名为 manual_1 的手册中的工具调用模板里有一个键为 API_KEY 的变量，它会被转换为 manual__1_API_KEY。

使用示例

1. 使用 UTCP 客户端

config.json（可选）

您可以在一个 JSON 文件中定义全面的客户端配置。这些字段都是可选的。

{
  "variables": {
    "openlibrary_URL": "https://openlibrary.org/static/openapi.json"
  },
  "load_variables_from": [
    {
      "variable_loader_type": "dotenv",
      "env_file_path": ".env"
    }
  ],
  "tool_repository": {
    "tool_repository_type": "in_memory"
  },
  "tool_search_strategy": {
    "tool_search_strategy_type": "tag_and_description_word_match"
  },
  "manual_call_templates": [
    {
        "name": "openlibrary",
        "call_template_type": "http",
        "http_method": "GET",
        "url": "${URL}",
        "content_type": "application/json"
    }
  ]
}

client.py

import asyncio
from utcp.utcp_client import UtcpClient
from utcp.data.utcp_client_config import UtcpClientConfig

async def main():
    # UtcpClient 可以通过配置文件路径、字典或 UtcpClientConfig 对象来创建。

    # 选项 1：从配置文件路径初始化
    # client_from_file = await UtcpClient.create(config="./config.json")

    # 选项 2：从字典初始化
    client_from_dict = await UtcpClient.create(config={
        "variables": {
            "openlibrary_URL": "https://openlibrary.org/static/openapi.json"
        },
        "load_variables_from": [
            {
                "variable_loader_type": "dotenv",
                "env_file_path": ".env"
            }
        ],
        "tool_repository": {
            "tool_repository_type": "in_memory"
        },
        "tool_search_strategy": {
            "tool_search_strategy_type": "tag_and_description_word_match"
        },
        "manual_call_templates": [
            {
                "name": "openlibrary",
                "call_template_type": "http",
                "http_method": "GET",
                "url": "${URL}",
                "content_type": "application/json"
            }
        ],
        "post_processing": [
            {
                "tool_post_processor_type": "filter_dict",
                "only_include_keys": ["name", "key"],
                "only_include_tools": ["openlibrary.read_search_authors_json_search_authors_json_get"]
            }
        ]
    })

    # 选项 3：使用功能齐全的 UtcpClientConfig 对象初始化
    from utcp_http.http_call_template import HttpCallTemplate
    from utcp.data.variable_loader import VariableLoaderSerializer
    from utcp.interfaces.tool_post_processor import ToolPostProcessorConfigSerializer

    config_obj = UtcpClientConfig(
        variables={"openlibrary_URL": "https://openlibrary.org/static/openapi.json"},
        load_variables_from=[
            VariableLoaderSerializer().validate_dict({
                "variable_loader_type": "dotenv", "env_file_path": ".env"
            })
        ],
        manual_call_templates=[
            HttpCallTemplate(
                name="openlibrary",
                call_template_type="http",
                http_method="GET",
                url="${URL}",
                content_type="application/json"
            )
        ],
        post_processing=[
            ToolPostProcessorConfigSerializer().validate_dict({
                "tool_post_processor_type": "filter_dict",
                "only_include_keys": ["name", "key"],
                "only_include_tools": ["openlibrary.read_search_authors_json_search_authors_json_get"]
            })
        ]
    )
    client = await UtcpClient.create(config=config_obj)

    # 调用工具。工具名称采用命名空间格式：`manual_name.tool_name`
    result = await client.call_tool(
        tool_name="openlibrary.read_search_authors_json_search_authors_json_get",
        tool_args={"q": "J. K. Rowling"}
    )

    print(result)

if __name__ == "__main__":
    asyncio.run(main())

2. 提供 UTCP 手册

UTCPManual 描述了您提供的工具。关键变化是将 tool_provider 替换为 tool_call_template。

server.py

使用 UTCP 装饰器的版本：

from fastapi import FastAPI
from utcp_http.http_call_template import HttpCallTemplate
from utcp.data.utcp_manual import UtcpManual
from utcp.python_specific_tooling.tool_decorator import utcp_tool

app = FastAPI()

# 发现端点返回工具手册
@app.get("/utcp")
def utcp_discovery():
    return UtcpManual.create_from_decorators(manual_version="1.0.0")

# 实际的工具端点
@utcp_tool(tool_call_template=HttpCallTemplate(
    name="get_weather",
    url=f"https://example.com/api/weather",
    http_method="GET"
), tags=["weather"])
@app.get("/api/weather")
def get_weather(location: str):
    return {"temperature": 22.5, "conditions": "Sunny"}

不使用 UTCP 依赖的服务器版本：

from fastapi import FastAPI

app = FastAPI()

# 发现端点返回工具手册
@app.get("/utcp")
def utcp_discovery():
    return {
        "manual_version": "1.0.0",
        "utcp_version": "1.0.2",
        "tools": [
            {
                "name": "get_weather",
                "description": "获取某个地点的当前天气",
                "tags": ["weather"],
                "inputs": {
                    "type": "object",
                    "properties": {
                        "location": {"type": "string"}
                    }
                },
                "outputs": {
                    "type": "object",
                    "properties": {
                        "temperature": {"type": "number"},
                        "conditions": {"type": "string"}
                    }
                },
                "tool_call_template": {
                    "call_template_type": "http",
                    "url": "https://example.com/api/weather",
                    "http_method": "GET"
                }
            }
        ]
    }

# 实际的工具端点
@app.get("/api/weather")
def get_weather(location: str):
    return {"temperature": 22.5, "conditions": "Sunny"}

3. 完整示例

您可以在 examples repository 中找到完整的示例。

协议规范

UtcpManual 和 Tool 模型

Tool 中的 tool_provider 对象已被 tool_call_template 替代。

{
  "manual_version": "string",
  "utcp_version": "string",
  "tools": [
    {
      "name": "string",
      "description": "string",
      "inputs": { ... },
      "outputs": { ... },
      "tags": ["string"],
      "tool_call_template": {
        "call_template_type": "http",
        "url": "https://...",
        "http_method": "GET"
      }
    }
  ]
}

调用模板配置示例

针对每种协议的配置示例。请记住将 provider_type 替换为 call_template_type。

HTTP 调用模板

{
  "name": "my_rest_api",
  "call_template_type": "http", // 必需
  "url": "https://api.example.com/users/{user_id}", // 必需
  "http_method": "POST", // 必需，默认值为 "GET"
  "content_type": "application/json", // 可选，默认值为 "application/json"
  "allowed_communication_protocols": ["http"], // 可选，默认为 [call_template_type]。限制工具可以使用的通信协议。
  "auth": { // 可选，用于 HTTP 请求的身份验证（例如使用 ApiKeyAuth 提供 Bearer 令牌）
    "auth_type": "api_key",
    "api_key": "Bearer $API_KEY", // 必需
    "var_name": "Authorization", // 可选，默认值为 "X-Api-Key"
    "location": "header" // 可选，默认值为 "header"
  },
  "auth_tools": { // 可选，用于转换后的工具的身份验证，如果此调用模板指向一个应自动转换为 utcp 手册的 openapi 规范（仅适用于按 OpenAPI 规范需要身份验证的端点）
    "auth_type": "api_key",
    "api_key": "Bearer $TOOL_API_KEY", // 必需
    "var_name": "Authorization", // 可选，默认值为 "X-Api-Key"
    "location": "header" // 可选，默认值为 "header"
  },
  "headers": { // 可选
    "X-Custom-Header": "value"
  },
  "body_field": "body", // 可选，默认值为 "body"
  "header_fields": ["user_id"] // 可选
}

SSE（服务器发送事件）调用模板

{
  "name": "my_sse_stream",
  "call_template_type": "sse", // 必需
  "url": "https://api.example.com/events", // 必需
  "event_type": "message", // 可选
  "reconnect": true, // 可选，默认值为 true
  "retry_timeout": 30000, // 可选，默认值为 30000 毫秒
  "auth": { // 可选，示例使用 BasicAuth
    "auth_type": "basic",
    "username": "${USERNAME}", // 必需
    "password": "${PASSWORD}" // 必需
  },
  "headers": { // 可选
    "X-Client-ID": "12345"
  },
  "body_field": null, // 可选
  "header_fields": [] // 可选
}

流式 HTTP 调用模板

请注意名称已从 http_stream 更改为 streamable_http。

{
  "name": "streaming_data_source",
  "call_template_type": "streamable_http", // 必需
  "url": "https://api.example.com/stream", // 必需
  "http_method": "POST", // 可选，默认值为 "GET"
  "content_type": "application/octet-stream", // 可选，默认值为 "application/octet-stream"
  "chunk_size": 4096, // 可选，默认值为 4096
  "timeout": 60000, // 可选，默认值为 60000 毫秒
  "auth": null, // 可选
  "headers": {}, // 可选
  "body_field": "data", // 可选
  "header_fields": [] // 可选
}

CLI 调用模板

{
  "name": "multi_step_cli_tool",
  "call_template_type": "cli", // 必需
  "commands": [ // 必需——按顺序执行命令
    {
      "command": "git clone UTCP_ARG_repo_url_UTCP_END temp_repo",
      "append_to_final_output": false
    },
    {
      "command": "cd temp_repo && find . -name '*.py' | wc -l"
      // 默认返回最后一道命令的输出
    }
  ],
  "env_vars": { // 可选
    "GIT_AUTHOR_NAME": "UTCP Bot",
    "API_KEY": "${MY_API_KEY}"
  },
  "working_dir": "/tmp", // 可选
  "auth": null // 可选（CLI 始终为 null）
}

CLI 协议特性：

• 多命令执行：命令在单个子进程中按顺序运行
• 跨平台：Windows 上使用 PowerShell，Unix/Linux/macOS 上使用 Bash
• 状态保留：目录更改（cd）在各命令之间保持有效
• 参数占位符：UTCP_ARG_argname_UTCP_END 格式
• 输出引用：可通过 $CMD_0_OUTPUT、$CMD_1_OUTPUT 访问先前的输出
• 灵活的输出控制：可选择将哪些命令的输出包含在最终结果中

文本调用模板

{
  "name": "my_text_manual",
  "call_template_type": "text", // 必需
  "file_path": "./manuals/my_manual.json", // 必需
  "auth": null, // 可选（文本始终为 null）
  "auth_tools": { // 可选，用于从 OpenAPI 规范生成的工具的身份验证
    "auth_type": "api_key",
    "api_key": "Bearer ${API_TOKEN}",
    "var_name": "Authorization",
    "location": "header"
  }
}

MCP（模型上下文协议）调用模板

{
  "name": "my_mcp_server",
  "call_template_type": "mcp", // 必需
  "config": { // 必需
    "mcpServers": {
      "server_name": {
        "transport": "stdio",
        "command": ["python", "-m", "my_mcp_server"]
      }
    }
  },
  "auth": { // 可选，示例使用 OAuth2
    "auth_type": "oauth2",
    "token_url": "https://auth.example.com/token", // 必需
    "client_id": "${CLIENT_ID}", // 必需
    "client_secret": "${CLIENT_SECRET}", // 必需
    "scope": "read:tools" // 可选
  }
}

安全性：协议限制

UTCP 通过 allowed_communication_protocols 字段，对每个手册可使用的通信协议提供细粒度控制。这可以防止潜在的危险协议升级（例如，基于 HTTP 的手册意外调用 CLI 工具）。

默认行为（默认安全）

当 allowed_communication_protocols 未设置或为空时，手册只能注册和调用与手册本身使用 相同协议类型 的工具：

from utcp_http.http_call_template import HttpCallTemplate

# 此手册仅能注册/调用 HTTP 工具（默认限制）
http_manual = HttpCallTemplate(
    name="my_api",
    call_template_type="http",
    url="https://api.example.com/utcp"
    # allowed_communication_protocols 未设置 → 默认为 ["http"]
)

允许多种协议

若要允许手册使用来自多种协议的工具，请显式设置 allowed_communication_protocols：

from utcp_http.http_call_template import HttpCallTemplate

# 此手册可以注册/调用 HTTP 和 CLI 工具
multi_protocol_manual = HttpCallTemplate(
    name="flexible_manual",
    call_template_type="http",
    url="https://api.example.com/utcp",
    allowed_communication_protocols=["http", "cli"]  # 显式允许两种协议
)

JSON 配置

{
  "name": "my_api",
  "call_template_type": "http",
  "url": "https://api.example.com/utcp",
  "allowed_communication_protocols": ["http", "cli", "mcp"]
}

行为总结

allowed_communication_protocols	手册类型	允许的工具协议
未设置 / null	"http"	仅 "http"
[]（空）	"http"	仅 "http"
["http", "cli"]	"http"	"http" 和 "cli"
["http", "cli", "mcp"]	"cli"	"http"、"cli" 和 "mcp"

注册时的过滤

在 register_manual() 过程中，不符合允许协议的工具会被自动过滤掉，并发出警告：

WARNING - 工具 'dangerous_tool' 使用通信协议 'cli'，该协议不在手册 'my_api' 的允许协议 ['http'] 中。该工具将不会被注册。

调用时的验证

即使工具以某种方式存在于仓库中，如果其协议未被允许，调用也会失败：

# 抛出 ValueError：工具 'my_api.some_cli_tool' 使用通信协议 'cli'，而该协议不被手册 'my_api' 允许。允许的协议：['http']
await client.call_tool("my_api.some_cli_tool", {"arg": "value"})

测试

测试结构已更新，以反映新的核心与插件分离。

运行测试

要运行核心库和所有插件的所有测试：

# 确保已安装所有开发依赖项
python -m pytest

要运行特定包的测试（例如，核心库）：

python -m pytest core/tests/

要运行特定插件的测试（例如，HTTP）：

python -m pytest plugins/communication_protocols/http/tests/ -v

要运行带有覆盖率的测试：

python -m pytest --cov=utcp --cov-report=xml

构建

构建过程现在涉及单独构建每个包（core 和 plugins），尽管它们是独立发布到 PyPI 的。

1. 创建并激活虚拟环境。
2. 安装构建依赖项：pip install build。
3. 导航到包目录（例如，cd core）。
4. 运行构建：python -m build。
5. 可分发文件（.whl 和 .tar.gz）将位于 dist/ 目录中。

OpenAPI 摄取——零基础设施工具集成

🚀 无需修改服务器即可将任何现有 REST API 转换为 UTCP 工具！

UTCP 的 OpenAPI 摄取功能会自动将 OpenAPI 2.0/3.0 规范转换为 UTCP 工具，使 AI 代理能够直接与现有 API 交互——无需包装服务器、无需更改 API、无需额外基础设施。

使用 OpenAPI 快速入门

from utcp_http.openapi_converter import OpenApiConverter
import aiohttp

# 将任意 OpenAPI 规范转换为 UTCP 工具
async def convert_api():
    async with aiohttp.ClientSession() as session:
        async with session.get("https://api.github.com/openapi.json") as response:
            openapi_spec = await response.json()
    
    converter = OpenApiConverter(openapi_spec)
    manual = converter.convert()
    
    print(f"从 GitHub API 生成了 {len(manual.tools)} 个工具！")
    return manual

# 或使用 UTCP 客户端配置进行自动检测
from utcp.utcp_client import UtcpClient

client = await UtcpClient.create(config={
    "manual_call_templates": [{
        "name": "github",
        "call_template_type": "http", 
        "url": "https://api.github.com/openapi.json",
        "auth_tools": {  # 为需要认证的生成工具添加认证
            "auth_type": "api_key",
            "api_key": "Bearer ${GITHUB_TOKEN}",
            "var_name": "Authorization",
            "location": "header"
        }
    }]
})

主要优势

• ✅ 零基础设施：无需部署或维护服务器
• ✅ 直接 API 调用：原生性能，无代理开销
• ✅ 自动转换：OpenAPI 模式 → UTCP 工具
• ✅ 选择性认证：仅受保护的端点需要认证，公开端点仍可访问
• ✅ 保留认证信息：支持 API 密钥、OAuth2、Basic 认证
• ✅ 多格式支持：JSON、YAML、OpenAPI 2.0/3.0
• ✅ 批量处理：可同时转换多个 API

多种摄取方法

1. 直接转换器：OpenApiConverter 类，提供完全控制
2. 远程 URL：从任意 URL 获取并转换规范
3. 客户端配置：直接在 UTCP 配置中包含规范
4. 批量处理：以编程方式处理多个规范
5. 基于文件：转换本地 JSON/YAML 规范

📖 完整的 OpenAPI 摄取指南 —— 详细示例和高级用法

---

贡献者

python-utcp 快速上手指南

Universal Tool Calling Protocol (UTCP) 是一个安全、可扩展的标准，用于定义和交互各种通信协议下的工具。它采用模块化核心与插件化架构，强调高扩展性、互操作性及易用性。

环境准备

• 系统要求：支持 Python 3.8+ 的操作系统（Linux, macOS, Windows）。
• 前置依赖：
  • Python 3.8 或更高版本。
  • pip 包管理工具。
  • （可选）git，用于克隆源码进行开发。

安装步骤

UTCP 采用核心库与协议插件分离的设计。请根据需求安装核心库及对应的协议插件。

1. 通过 PyPI 安装（推荐）

安装核心库及最常用的 HTTP 插件：

pip install utcp utcp-http

如需其他协议支持，可按需安装：

# 命令行工具插件
pip install utcp-cli

# Model Context Protocol 插件
pip install utcp-mcp

# 本地文件工具插件
pip install utcp-text

# WebSocket 插件
pip install utcp-websocket

国内加速建议：如遇网络问题，可使用清华或阿里云镜像源：

pip install utcp utcp-http -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 开发模式安装（可选）

如需修改源码或贡献代码，可克隆仓库并以可编辑模式安装：

git clone https://github.com/universal-tool-calling-protocol/python-utcp.git
cd python-utcp

# 安装核心库（含开发依赖）
pip install -e "core[dev]"

# 安装特定插件（例如 HTTP）
pip install -e plugins/communication_protocols/http

基本使用

以下示例展示如何通过 Python 代码初始化客户端并调用一个远程 HTTP 工具。

1. 最小化代码示例

import asyncio
from utcp.utcp_client import UtcpClient

async def main():
    # 创建客户端，配置手动调用模板
    client = await UtcpClient.create(config={
        "manual_call_templates": [{
            "name": "my_api",
            "call_template_type": "http",
            "url": "https://api.example.com/utcp"
        }]
    })

    # 调用工具
    # 注意：工具名称格式为 "manual_name.tool_name"
    result = await client.call_tool("my_api.get_data", {"id": "123"})
    
    print(result)

if __name__ == "__main__":
    asyncio.run(main())

2. 使用配置文件初始化

对于复杂场景，可以使用 JSON 文件或字典配置变量、存储策略和后处理逻辑。

config.json

{
  "variables": {
    "base_url": "https://openlibrary.org/static/openapi.json"
  },
  "manual_call_templates": [
    {
      "name": "openlibrary",
      "call_template_type": "http",
      "http_method": "GET",
      "url": "${base_url}",
      "content_type": "application/json"
    }
  ]
}

client.py

import asyncio
from utcp.utcp_client import UtcpClient

async def main():
    # 从配置文件路径初始化
    client = await UtcpClient.create(config="./config.json")

    # 调用工具
    result = await client.call_tool(
        tool_name="openlibrary.search", 
        tool_args={"q": "J. K. Rowling"}
    )
    print(result)

if __name__ == "__main__":
    asyncio.run(main())

关键特性提示

• 命名空间：工具调用时名称需遵循 manual_name.tool_name 格式（如 my_api.get_data），客户端会自动处理。
• 变量替换：在配置中使用 ${variable_name} 语法引用变量，支持从 .env 文件加载。
• 插件扩展：更换 call_template_type 即可切换到底层不同的通信协议（如 cli, mcp, text 等），无需修改核心逻辑。