三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

Agent Plugins 1.0.0 规范详解：从统一标准到插件开发实战

发布时间：2026/8/9 7:15:12 三亩地 编程学习日记
Agent Plugins 1.0.0 规范详解：从统一标准到插件开发实战

这类工具最值得先看的不是功能列表，而是能不能在普通环境里稳定跑起来。Agent Plugins 1.0.0 的发布，背后是谷歌、亚马逊、微软这些大厂在推动一个统一的智能体插件规范，这意味着什么？简单说，它想解决的是不同 AI 智能体（Agent）之间插件不通用、开发标准混乱的问题。如果你在开发或使用基于大语言模型的自动化流程、智能助手，或者想把一个智能体的能力接入到另一个平台，这个规范就是你接下来需要关注的重点。

它不是一个具体的软件或 SDK 下载下来就能跑，而是一套接口定义和协议标准。所以，这篇文章不会带你“安装并运行 Agent Plugins 1.0.0”，而是会拆解清楚：这个规范到底解决了什么痛点、它定义的核心能力是什么、作为开发者或使用者你需要准备什么、以及在实际项目中如何判断一个插件是否符合规范、如何开始适配。我会结合常见的智能体开发场景，把抽象的规范翻译成具体的环境准备、接口调用和验证步骤。

1. 先搞懂“统一插件规范”到底要解决什么问题

在深入任何代码或配置之前，必须明白我们为什么需要它。如果你自己写过或调用过不同平台的 AI 插件，肯定遇到过这些情况：为 OpenAI 的 ChatGPT 插件写了一套描述文件（ai-plugin.json），结果发现没法直接用在 LangChain 的 Agent 里；或者，自己公司内部的一个智能体工具，想接入外部的一个天气查询 API，发现两边对插件输入输出的格式要求完全不同，又得重新写一层适配层。

1.1 当前智能体插件的“碎片化”现状

现在的智能体生态，可以粗略分为几个阵营：

  • 闭源平台阵营：比如早期 OpenAI 的 ChatGPT 插件体系。它有自己严格的 manifest 文件格式、认证流程和运行沙箱。
  • 开源框架阵营：比如 LangChain、LlamaIndex、AutoGen 等。它们也提供了插件/工具（Tool）的定义方式，但每个框架的抽象层级和调用接口都有差异。
  • 云厂商阵营：各大云平台推出的 AI 服务（如 AWS Bedrock Agents, Google Cloud Vertex AI Agents）也都有自己的“技能”或“动作”定义方式。
  • 企业自研阵营：很多公司内部会基于开源模型自研智能体平台，插件标准更是“各自为政”。

这就导致了一个核心矛盾：一个开发者辛辛苦苦为某个智能体写的业务逻辑（比如“查询数据库并生成报表”），很难低成本地复用到另一个智能体环境中。每次切换平台或框架，都意味着额外的集成和适配成本。

1.2 Agent Plugins 1.0.0 带来的核心改变：互操作性

Agent Plugins 规范的目标就是成为智能体世界的“USB 标准”或“蓝牙协议”。它定义了一套与具体运行时（Runtime）和 AI 模型无关的插件描述、发现和调用机制。

它的核心价值在于“一次定义，多处运行”。具体来说：

  1. 统一的描述文件：插件提供者按照规范编写一个标准化的描述文件（通常是 OpenAPI Spec 的扩展），明确声明插件的功能、输入参数、输出格式、认证方式等。
  2. 标准的发现机制：智能体运行时（无论是本地框架还是云服务）可以通过一个固定的端点（如/.well-known/ai-plugin.json）来发现和加载插件。
  3. 一致的调用接口：智能体调用插件时，遵循统一的 HTTP 请求/响应格式，这使得插件背后的实际服务可以用任何语言编写，部署在任何地方。

对于开发者而言，最直接的好处是：你为一个符合此规范的智能体平台开发的插件，理论上可以无缝（或经过极少量配置）被另一个同样支持此规范的平台所使用。这极大地降低了生态锁定的风险，并鼓励了插件市场的形成。

2. 运行或使用一个“规范插件”需要什么条件

既然它是一套规范，那么“运行”它就意味着你需要一个支持该规范的“运行时环境”。同时，如果你想“提供”一个插件，也需要让你的服务符合规范。我们从使用者和提供者两个角度来拆解环境准备。

2.1 作为插件使用者（智能体开发者/运营者）

你的目标是让智能体能发现并调用外部插件。你需要准备的环境是：一个支持 Agent Plugins 规范的智能体框架或平台。

目前，由于规范较新，完全原生支持的平台可能还在逐步增加。但许多主流框架已经开始跟进或提供了兼容层。你的准备工作通常包括：

  1. 选择或确认运行时：

    • 云服务：关注 Google Cloud Vertex AI Agents、Amazon Bedrock Agents、Microsoft Azure AI Agents 等服务的更新公告，查看是否已宣布支持 Agent Plugins 规范。
    • 开源框架：检查你使用的 LangChain、LlamaIndex、AutoGen 等框架的最新版本。它们可能会通过一个额外的库（如langchain-agent-plugins）或配置项来接入规范插件。
    • 自研平台：如果你在自研平台，则需要在自己的智能体调度模块中，集成规范的插件发现和调用逻辑。

  2. 配置插件源： 智能体运行时需要知道去哪里发现插件。规范通常支持多种方式：

    • 本地文件路径：指向一个本地的插件描述文件（ai-plugin.json）。
    • HTTP/HTTPS URL：指向一个远程服务提供的描述文件端点（如https://weather-service.example.com/.well-known/ai-plugin.json）。
    • 插件市场/目录：未来可能会有集中的目录服务，你可以配置一个目录地址，智能体会自动从中获取可用插件列表。

  3. 处理认证与安全： 插件可能需要 API Key、OAuth 等认证。规范定义了标准的认证字段（如auth配置）。你需要在智能体运行时中安全地配置这些凭据（如通过环境变量、密钥管理服务），确保在调用插件时能自动附加。

2.2 作为插件提供者（服务/API 开发者）

你的目标是让自己的服务（如一个内部订单查询 API 或一个公开的汇率转换服务）能够被任何支持该规范的智能体调用。你需要让你的服务“看起来”像一个标准插件。

  1. 服务本身：你首先得有一个正常运行的 HTTP/HTTPS API 服务。它可以用任何语言（Python, Node.js, Go, Java等）和任何框架（Flask, FastAPI, Express, Spring Boot等）编写。
  2. 编写 OpenAPI 规范文件：这是最关键的一步。你需要为你的 API 编写一个详细的 OpenAPI Specification (OAS) 文件（通常是openapi.yaml或openapi.json）。这个文件要清晰描述所有端点、参数、请求/响应体结构。
  3. 创建插件描述清单：在 OAS 文件同级目录，创建一个ai-plugin.json文件。这个文件是插件的“身份证”，它基于 OAS，但增加了插件特有的元数据。其核心结构通常包括：
    { "schema_version": "v1", "name_for_human": "天气查询插件", "name_for_model": "weather_query_tool", "description_for_human": "一个可以查询全球城市当前天气的插件。", "description_for_model": "当用户需要查询某个城市的当前天气、温度、湿度等信息时，使用此插件。需要提供城市名称。", "auth": { "type": "none" // 或 "service_http", "oauth" 等 }, "api": { "type": "openapi", "url": "https://your-service.com/openapi.yaml" }, "logo_url": "https://your-service.com/logo.png", "contact_email": "dev@example.com", "legal_info_url": "https://your-service.com/terms" }
  4. 暴露发现端点：你的服务需要在根路径或指定路径下（通常是/.well-known/ai-plugin.json）提供上述ai-plugin.json文件的内容。这样，智能体运行时就能通过访问这个固定 URL 来发现你的插件。
  5. 确保 API 符合描述：你的实际 API 实现必须严格遵循你在 OpenAPI 文件中定义的接口。任何不一致都可能导致调用失败。

3. 从零开始：将一个现有 API 包装成规范插件的实操步骤

假设你有一个用 Python FastAPI 编写的简单天气查询服务，现在想让它成为符合 Agent Plugins 1.0.0 规范的插件。下面是一套可落地的操作流程。

3.1 第一步：确认现有 API 服务

假设你的服务已经运行在http://localhost:8000，有一个查询天气的端点：

  • GET/weather?city={city_name}
  • 响应：{“city”: “Beijing”, “temperature”: 22, “condition”: “Sunny”}

首先，确保这个服务本身是稳定可用的。用curl或 Postman 测试一下：

curl “http://localhost:8000/weather?city=Beijing”

3.2 第二步：编写 OpenAPI 规范文件

在项目根目录创建openapi.yaml文件。这是让机器理解你 API 的契约。

openapi: 3.0.0 info: title: 天气查询服务 API description: 提供全球主要城市的实时天气信息查询。 version: 1.0.0 servers: - url: http://localhost:8000 paths: /weather: get: operationId: getWeather summary: 根据城市名称查询天气 description: 返回指定城市的当前温度、天气状况等信息。 parameters: - name: city in: query description: 城市名称，支持中文或英文。 required: true schema: type: string example: “北京” responses: ‘200’: description: 成功返回天气信息 content: application/json: schema: $ref: ‘#/components/schemas/WeatherResponse’ ‘404’: description: 未找到该城市 content: application/json: schema: $ref: ‘#/components/schemas/ErrorResponse’ components: schemas: WeatherResponse: type: object properties: city: type: string description: 城市名 temperature: type: integer description: 温度，单位摄氏度 condition: type: string description: 天气状况，如 Sunny, Rainy ErrorResponse: type: object properties: error: type: string description: 错误信息

这个文件定义了 API 的详细信息。你可以使用 Swagger UI 或 Redoc 工具来验证和可视化这个文件。

3.3 第三步：创建插件描述清单ai-plugin.json

在项目根目录创建ai-plugin.json文件。这个文件是给智能体“看”的，告诉它这个插件是什么、能干什么、怎么用。

{ “schema_version”: “v1”, “name_for_human”: “天气查询”, “name_for_model”: “weather_query”, “description_for_human”: “查询全球城市的实时天气，包括温度和天气状况。”, “description_for_model”: “当用户询问某个地方的天气、温度、是否下雨下雪时，使用此工具。你需要向用户询问城市名称，然后调用此工具。工具的输入是城市名（字符串）。输出包含城市、温度（摄氏度）和天气状况。”, “auth”: { “type”: “none” }, “api”: { “type”: “openapi”, “url”: “http://localhost:8000/openapi.yaml” }, “logo_url”: “http://localhost:8000/static/logo.png”, “contact_email”: “support@example.com”, “legal_info_url”: “http://localhost:8000/terms” }

关键字段解释：

  • description_for_model：这是给 AI 模型看的提示词，至关重要。它需要清晰、无歧义地说明在什么场景下触发这个插件，以及如何准备输入参数。写得好能极大提升智能体调用插件的准确率。
  • api.url：指向你上一步创建的 OpenAPI 文件。智能体会读取这个文件来了解具体的调用方式。
  • auth.type:none表示无需认证。如果是service_http，则需要配置Authorization头；如果是oauth，则配置更复杂。先从简单的none开始测试。

3.4 第四步：暴露发现端点并重启服务

你需要让智能体能通过固定 URL 访问到ai-plugin.json文件。在 FastAPI 中，可以简单添加一个路由：

from fastapi import FastAPI from fastapi.responses import FileResponse from fastapi.staticfiles import StaticFiles import os app = FastAPI() # ... 你原有的 /weather 路由 ... @app.get(“/.well-known/ai-plugin.json”) async def get_ai_plugin(): # 直接返回 ai-plugin.json 文件的内容 return FileResponse(‘./ai-plugin.json’) # 如果需要，挂载静态文件目录用于 logo app.mount(“/static”, StaticFiles(directory=“static”), name=“static”)

重启你的 FastAPI 服务。然后，用浏览器或curl访问http://localhost:8000/.well-known/ai-plugin.json，确认能正确返回 JSON 内容。

3.5 第五步：在支持规范的智能体运行时中测试

这是验证环节。你需要一个支持 Agent Plugins 规范的智能体环境。由于规范较新，你可以采取以下方式之一进行测试：

  1. 使用早期适配的框架：查找 LangChain 等社区是否有实验性的支持库。例如，可能会有一个AgentPluginTool类，你可以这样使用：

    from langchain.agents import AgentExecutor, create_openai_functions_agent from langchain_community.tools.agent_plugins import AgentPluginTool from langchain_openai import ChatOpenAI # 通过插件描述文件的 URL 创建工具 weather_tool = AgentPluginTool.from_plugin_url( “http://localhost:8000/.well-known/ai-plugin.json” ) llm = ChatOpenAI(model=“gpt-4”, temperature=0) tools = [weather_tool] agent = create_openai_functions_agent(llm, tools, prompt) agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True) # 测试 result = agent_executor.invoke({“input”: “北京现在天气怎么样？”}) print(result[“output”])

    注意：以上代码为示意，具体类名和用法需根据实际可用的库进行调整。

  2. 手动模拟智能体调用：如果暂时没有现成的运行时，你可以手动验证插件的“可发现性”和“可调用性”。

    • 发现测试：访问/.well-known/ai-plugin.json成功，且内容符合规范。
    • 契约测试：智能体会读取api.url指向的 OpenAPI 文件。你可以用 OpenAPI 校验工具检查该文件的有效性。
    • 调用测试：完全按照 OpenAPI 文件中定义的/weather接口，用curl或 Postman 发起一次真实调用，确保返回预期结果。

如果以上步骤全部通过，那么你的服务就已经是一个符合 Agent Plugins 1.0.0 规范的插件了。

4. 关键细节与生产环境考量：不止于“跑通”

把单个插件跑通只是第一步。当你想在团队内推广，或者准备对外提供插件服务时，以下几个方面的细节决定了它的可用性和稳定性。

4.1 认证与安全：从none到生产级

在测试时我们用auth.type: “none”。在生产环境中，这几乎不可行。规范支持几种认证方式：

  • service_http：适用于 API Key 或 Bearer Token 认证。你需要在ai-plugin.json的auth部分配置authorization_type(如Bearer) 和verification_tokens。智能体运行时负责在请求头中注入令牌。

    “auth”: { “type”: “service_http”, “authorization_type”: “bearer”, “verification_tokens”: { “openai”: “your-secret-token-here” // 这个 key 因平台而异 } }

    关键点：verification_tokens是一个对象，不同的智能体平台（如 OpenAI, Google等）可能需要不同的 key。你的服务需要验证请求头中的Authorization: Bearer <token>是否与配置的 token 匹配。

  • oauth：适用于更复杂的用户级授权流程。配置非常复杂，涉及client_url,scope,authorization_url,authorization_content_type等。除非你的插件需要访问用户私有数据（如读取用户邮箱），否则建议先从service_http开始。

安全建议：

  1. 永远不要将硬编码的密钥或令牌提交到代码仓库。使用环境变量或密钥管理服务。
  2. 在生产环境中，务必使用HTTPS。
  3. 在插件服务的 API 实现中，实施速率限制（Rate Limiting）和请求验证，防止滥用。

4.2description_for_model的撰写艺术

这个字段是插件能否被智能体准确调用的关键。写得太笼统，智能体不知道该什么时候用；写得太具体，又可能限制其泛化能力。一些经验法则：

  • 明确触发场景：用自然语言描述“当用户问什么问题时，使用此工具”。例如：“当用户需要将一段文字从一种语言翻译成另一种语言时，使用此工具。”
  • 明确输入要求：说明工具需要什么参数，以及参数的类型和格式。“需要提供两个参数：text（要翻译的文本，字符串）和target_language（目标语言代码，如 ‘zh-CN’, ‘en’，字符串）。”
  • 描述输出内容：告诉智能体工具会返回什么，方便它组织回答。“工具将返回翻译后的文本（字符串）。如果出错，会返回错误信息。”
  • 避免歧义：不要用“它”、“这个”等指代不清的词。
  • 示例很有用：虽然规范字段不一定支持，但在描述中隐含一个示例通常效果更好。“例如，用户说‘把Hello world翻译成中文’，你应该调用此工具，参数为{“text”: “Hello world”, “target_language”: “zh-CN”}。”

4.3 错误处理与健壮性

智能体不像人类，它可能以各种意想不到的方式调用你的插件。你的 API 必须健壮。

  1. 输入验证：即使 OpenAPI 定义了required: true，你的代码也要对参数做校验。城市名不存在怎么办？参数为空怎么办？返回清晰、结构化的错误信息，而不是堆栈跟踪。
  2. 标准化错误响应：遵循你在 OpenAPI 中定义的错误模式（如上面的ErrorResponse）。智能体运行时可能会解析错误信息并尝试恢复或告知用户。
  3. 超时与重试：你的服务应设置合理的超时。同时，作为调用方（智能体运行时），也应配置对插件调用的超时和重试策略，避免一个缓慢的插件拖垮整个智能体会话。
  4. 可观测性：为你的插件服务添加详细的日志记录（请求、响应、耗时、错误），并考虑集成监控和告警。当智能体调用失败时，你需要能快速定位问题是出在插件服务还是网络或智能体本身。

4.4 版本管理与兼容性

随着业务发展，你的插件 API 可能会升级。如何管理？

  • 在 OpenAPIinfo.version和 URL 中体现版本：例如，将 API 路径设计为/v1/weather，并在openapi.yaml的servers.url和info.version中明确版本。
  • 谨慎对待破坏性变更：修改参数名、删除字段、改变响应结构都是破坏性变更。尽量通过添加新字段、新端点来扩展功能，保持旧版本的兼容性。
  • 在ai-plugin.json中声明依赖：虽然规范可能还未完全定义，但可以考虑在描述文件中添加api_version: “v1”之类的信息，让智能体运行时知晓。

5. 常见问题排查：当插件“不工作”时

即使按照步骤操作，你也可能会遇到插件无法被智能体发现或调用的情况。以下是典型的排查路径。

5.1 智能体无法发现插件

  • 症状：配置了插件 URL，但智能体运行时报告“未找到插件”或“插件加载失败”。
  • 排查步骤：
    1. 检查发现端点：直接在浏览器中打开https://your-plugin.com/.well-known/ai-plugin.json。是否能正常返回 JSON？返回的 HTTP 状态码必须是 200，且Content-Type应为application/json。
    2. 检查 CORS：如果你的插件服务和智能体运行时不在同一个域名下，浏览器（或某些运行时）可能会因 CORS 策略而阻止请求。确保你的插件服务在响应头中包含Access-Control-Allow-Origin: *或允许智能体所在域。
    3. 检查 JSON 格式：将返回的 JSON 内容粘贴到 JSONLint 等在线验证器，确保没有语法错误。
    4. 检查必填字段：核对你的ai-plugin.json是否包含了规范要求的所有必填字段（如schema_version,name_for_model,api等）。
    5. 检查api.url可达性：智能体会尝试读取api.url指向的 OpenAPI 文件。确保这个 URL 也能公开访问，并且内容有效。

5.2 智能体发现插件但调用失败

  • 症状：插件出现在智能体的工具列表中，但调用时返回错误。
  • 排查步骤：
    1. 查看智能体日志：这是第一手信息。错误可能是“无效的认证”、“请求超时”、“响应格式不符”等。
    2. 手动测试 API：完全绕过智能体，用curl或 Postman，按照 OpenAPI 描述，构造一个完全相同的请求（包括 URL、方法、Headers、Body），发送到你的插件服务。能成功吗？
      curl -X GET “http://localhost:8000/weather?city=London” \ -H “Authorization: Bearer your-token-if-any”
    3. 对比 OpenAPI 与实际 API：确保你的实际实现与openapi.yaml文件 100% 一致。一个常见的错误是：文档写了某个参数是integer，但 API 实际接收的是string。
    4. 检查认证：如果使用了service_http认证，确认智能体运行时是否正确注入了Authorization头，以及你的服务端是否正确验证了这个令牌。
    5. 检查网络与防火墙：确保智能体运行时所在的网络环境能够访问你的插件服务地址和端口。

5.3 智能体调用插件但结果不符合预期

  • 症状：调用成功（返回 200），但智能体没有正确使用返回的结果，或者给出了错误解读。
  • 排查步骤：
    1. 审查description_for_model：这是最可能的原因。描述是否足够清晰、无歧义？是否准确说明了工具的用途、输入和输出？尝试用更直白、更详细的语言重写。
    2. 审查 API 响应格式：智能体期望的响应格式是否与 OpenAPI 中定义的schema完全一致？多一个字段或少一个字段都可能导致解析问题。确保响应是标准的 JSON，并且字段名、类型完全匹配。
    3. 测试不同的输入：用一些边界或模糊的输入测试你的 API（如空城市、超长字符串、特殊字符），看响应是否依然结构良好。智能体可能会生成各种输入。

6. 总结与展望：现在该做什么？

Agent Plugins 1.0.0 的发布，是智能体走向标准化和互操作性的重要一步。对于开发者和企业来说，现在投入时间理解并尝试这套规范，是有长期价值的。

如果你是一个智能体应用开发者，我建议：

  1. 不要急于重构：先在你当前使用的框架（LangChain等）中，寻找对 Agent Plugins 规范的支持或兼容方案。用一个简单的、非核心的插件做技术验证。
  2. 关注运行时生态：密切关注 Google Cloud、Amazon Bedrock、Azure AI 以及主流开源框架的官方公告，看它们何时、以何种方式原生支持此规范。
  3. 设计时预留接口：在设计新的插件时，可以同时编写符合此规范的ai-plugin.json和 OpenAPI 文件，即使暂时用不上。这为未来的迁移降低了成本。

如果你是一个 API 服务提供者，我建议：

  1. 评估暴露为插件的价值：你的服务是否适合被 AI 智能体调用？如果能显著扩展你的服务使用场景，那么值得投入。
  2. 从“只读”服务开始：优先将查询类、信息获取类的 API 包装成插件。涉及写操作、交易或敏感数据的 API，要慎重考虑安全和权限模型。
  3. 准备好 OpenAPI 文档：无论是否立即支持 Agent Plugins，拥有一份完整、准确的 OpenAPI 规范文件，对你的 API 治理、测试和开发者体验都有好处。

这个规范的成熟和普及需要时间，但方向是明确的：一个更加开放、可组合的智能体生态。作为一线的开发者，更务实的做法是理解其原理，掌握将现有能力“封装”成标准插件的方法，然后保持关注，在生态成熟时平滑地融入进去。

编程学习 学习日记 实战经验
← 返回列表