> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# OpenAPI - AI代理的工具接口
- URL: https://www.hubwiz.com/blog/openapi-tool-interface-for-ai-agent/
- Published: 2025-01-03T03:06:57.000Z
- Updated: 2025-01-03T03:06:57.000Z
- Description: OpenAPI 规范是一个标准化的、与语言无关的框架，用于定义 HTTP API。它使人类和机器都能发现和理解服务的功能，而无需访问其源代码、详细文档或网络流量检查。
- Author: admin
- Tags: LIBRARY, OPENAPI, AGENT, #Import 2026-10-14 14:41

我最近探索了如何利用 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 检索付款状态。

![](https://www.hubwiz.com/blog/content/images/2025/01/image-18.png)

基于代理的示例应用程序

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

### 2.1 为支付服务设置 OpenAPI 规范

确保你的支付服务公开 OpenAPI 规范。我在 .net 中执行此操作，因此在 .net 中，你可以使用 Swagger 公开 OpenAPI 规范。完整指南可在[此处](https://learn.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-8.0&ref=hubwiz.com)找到。

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

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

点击[这里](https://aka.ms/aspnetcore/swashbuckle?ref=hubwiz.com)了解有关配置 Swagger/OpenAPI 的更多信息

这应该会创建输出 [http://localhost:5272/swagger/v1/swagger.json](http://localhost:5272/swagger/v1/swagger.json%E3%80%82?ref=hubwiz.com)：

```
{
  "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”

![](https://www.hubwiz.com/blog/content/images/2025/01/image-19.png)

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

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

![](https://www.hubwiz.com/blog/content/images/2025/01/image-20.png)

### 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 已成功集成。

![](https://www.hubwiz.com/blog/content/images/2025/01/image-21.png)

### 2.4 运行应用程序

现在一切都已设置完毕，请部署你的应用程序并开始与语义内核代理交互。该系统旨在无缝处理各种任务。

## 3、示例应用程序概述

以下是我创建的示例应用程序的简要概述。它包括两个关键插件：

- `Inventory`插件。检索最新的库存详细信息。此插件位于 SalesAgent 服务内
- `PaymentProcessor` 插件。此插件托管在另一个服务上。进行托管在 `PaymentProcessor` 服务上的 API 调用以处理交易。

![](https://www.hubwiz.com/blog/content/images/2025/01/image-22.png)

![](https://www.hubwiz.com/blog/content/images/2025/01/image-23.png)

![](https://www.hubwiz.com/blog/content/images/2025/01/image-24.png)

交易 ID 确认我们的 AI 代理已成功调用 InventoryService 的两个 API！！

## 4、结束语

OpenAPI 规范以及Semantic Kernel和 Azure OpenAI 提供了一种引人注目的解决方案，可以为 AI 代理提供现实世界的功能。这种组合提供了几个关键优势：

- 简化的 AI 集成：OpenAPI 规范为 AI 代理提供了一种标准化的方式来理解和与现有 API 交互，从而无需进行复杂的自定义集成。
- 增强的代理功能：通过利用现有 API，AI 代理可以执行更广泛的任务，例如处理付款或管理库存。这带来了更多功能和更有用的 AI 体验。
- 改进的可扩展性：随着应用程序的增长，你可以使用 OpenAPI 轻松集成新 API，让你的 AI 代理跟上不断发展的功能。

本博客提供了有关使用Semantic Kernel代理和 Azure OpenAI 的 OpenAPI 规范的分步指南。通过遵循这些步骤并采用这种强大的组合，可以让你的 AI 代理提供更全面、更有价值的用户体验。

---

原文链接：[Empowering AI Agents with Tools via OpenAPI Specification: A Step-by-Step Guide Using Microsoft’s Semantic Kernel Agent Framework](https://medium.com/@akshaykokane09/empowering-ai-agents-with-tools-via-openapi-specification-a-step-by-step-guide-using-microsofts-16ec3459ab3c?ref=hubwiz.com)

汇智网翻译整理，转载请标明出处