OpenAPI - AI代理的工具接口

LIBRARY Jan 3, 2025

推荐： ComfyUI-PandasAI | ComfyUI-Autodistill | ComfyUI节点速查手册

我最近探索了如何利用 OpenAPI 规范为 AI 代理提供可操作的功能。在这篇博客中，我旨在分享我的见解并展示这个过程。

1、OpenAPI规范简介

让我们从基础开始。

什么是 OpenAPI 规范？

OpenAPI 规范是一个标准化的、与语言无关的框架，用于定义 HTTP API。它使人类和机器都能发现和理解服务的功能，而无需访问其源代码、详细文档或网络流量检查。正确定义的 OpenAPI 规范允许消费者以最少的实现逻辑与远程服务交互。在此处了解更多信息。

应该何时使用 OpenAPI 规范？

当你想将 AI 功能整合到现有 API 中时，OpenAPI 特别有用。许多企业已经拥有正在运行的 API。在当前的 AI 浪潮中，将 AI 集成到应用程序中已成为保持竞争力的关键。使用基于 OpenAPI 的插件和语义内核可以轻松使用现有 API 为 AI 代理提供支持。

2、OpenAPI规范电商实例

OpenAPI 规范为 AI 提供了理解和与 API 交互所需的所有信息。它提供：

端点及其参数的语义描述。
参数的数据类型。
预期响应的详细信息。

让我们考虑一个例子：假设你已经在使用电子商务平台的支付服务。该服务公开两个 API：

payment/accept：此 API 接受信用卡信息、处理付款并返回 transactionId。
payment/status：此 API 使用 transactionId 检索付款状态。

现在，电子商务网站计划推出新功能“ShopeChat.AI”，你可以在其中与 AI 代理进行交互，就像你与实际店主交互以找到最佳产品并购买该产品一样。

2.1 为支付服务设置 OpenAPI 规范

确保你的支付服务公开 OpenAPI 规范。我在 .net 中执行此操作，因此在 .net 中，你可以使用 Swagger 公开 OpenAPI 规范。完整指南可在此处找到。

这是使用 SwagsBuckler 包，我将添加此服务

builder.Services.AddSwaggerGen(options =>
{
    var xmlFile = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    options.IncludeXmlComments(xmlPath);
});

点击这里了解有关配置 Swagger/OpenAPI 的更多信息

这应该会创建输出 http://localhost:5272/swagger/v1/swagger.json：

{
  "openapi": "3.0.1",
  "info": {
    "title": "PaymentProcessor",
    "version": "1.0"
  },
  "paths": {
    "/api/Payments/status": {
      "get": {
        "tags": [
          "Payments"
        ],
        "summary": "Retrieves the status of a specific payment.",
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/Payments/process": {
      "post": {
        "tags": [
          "Payments"
        ],
        "summary": "Processes a payment request.",
        "requestBody": {
          "description": "The payment request details.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PaymentRequest": {
        "required": [
          "transactionId"
        ],
        "type": "object",
        "properties": {
          "transactionId": {
            "minLength": 1,
            "type": "string"
          },
          "amount": {
            "minimum": 0.01,
            "type": "number",
            "format": "double"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

为了确保正确调用支付服务 API，我添加了一个常量静态交易 ID 以用于验证目的：
TransactionId = “TestService123”

2.2 将应用程序部署到 Azure App (可选)

如果你计划在云中托管应用程序，请将其部署到 Azure 以实现可访问性和可扩展性。虽然是可选的，但此步骤可确保无缝集成和可用性以进行测试和部署。

2.3 设置Semantic Kernel代理

我们将设置一个Semantic Kernel代理，我们将其称为“SalesAgent”。以下是配置方法：

在你的项目中添加所需的包
从你的 OpenAPI 规范导入 paymentProcessor 插件：

<PackageReference Include="Microsoft.SemanticKernel.Plugins.OpenApi" Version="1.32.0-preview" />

await kernel.ImportPluginFromOpenApiAsync(
               pluginName: "paymentProcessor",
               uri: new Uri("http://payment-backend-f4bjgseugsdhddb4.eastus-01.azurewebsites.net/swagger/v1/swagger.json."),
               executionParameters: new OpenApiFunctionExecutionParameters()
                {
                      EnablePayloadNamespacing = true
                }
            );

一旦你的应用程序启动，Kernel 对象应显示 paymentProcessor 插件。这确认 API 已成功集成。