将 API 工具 (插件) 添加到代理

代理开发人员通常需要发出 HTTP 请求来生成完整的用例。

此示例演示如何创建一个代理，该代理利用插件和 API 工具连接到名为 的 freeipapi.comREST API 服务，该服务提供异地 IP 查找功能。

整个过程如下：

1. 步骤 1：创建并发布定义 API 的 OpenAPI 规范

2. 步骤 2：创建清单文件并将其上传到Security Copilot

3. 步骤 3：创建并上传使用该插件的代理

4. 步骤 4：将包发布到安全存储 (仅适用于合作伙伴代理)

   注意

   有关使用 API 工具 (技能) 的清单 YAML 示例，请参阅 使用多个工具生成代理。 它提供有关如何上传代理、设置和运行在“活动代理”页上发布的代理的说明。

步骤 1：创建和发布 OpenAPI 规范

该示例与免费 IP REST API 集成以执行 IP 地址地理位置查找。 必须在线发布此规范 (GitHub gist) 运行良好。 请参阅以下示例来创建和托管规范。 有关身份验证的示例，请参阅 身份验证类型。

openapi: 3.0.0

info:
    title: Free IP API
    description: A free IP lookup API
    version: "v1"

servers:
    - url: https://freeipapi.com/api/

paths:
    /json/{ipaddress}:
        get: 
            operationId: lookupIpAddressGeolocation
            summary: Lookup IP Address Geolocation information
            parameters:
                - in: path
                  name: ipaddress
                  schema:
                      type: string
                  required: true
                  description: The ip address to lookup
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/lookupIpAddressGeolocationResponse"

components:
    schemas:
        lookupIpAddressGeolocationResponse:
            type: object
            properties:
                ipVersion:
                    type: integer
                    description: The IP address version
                ipAddress:
                    type: string
                    description: The IP address
                latitude:
                    type: number
                    description: The latutude
                longitude:
                    type: number
                    description: The longitude
                countryName:
                    type: string
                    description: The country
                zipCode:
                    type: string
                    description: The zip code
                cityName:
                    type: string
                    description: The city
                regionName:
                    type: string
                    description: The region
                continent:
                    type: string
                    description: The continent

步骤 2： (插件) 创建并上传 API 清单

1. 创建名为 http_manifest.yaml 的文件，该文件采用工具格式 API。

       Descriptor:
         Name: DCA_SampleAPIPlugin
         DisplayName: TESTDCA_Free IP API
         Description: Skills for looking up geolocation information for an IP address using the Free IP API
   
       SkillGroups:
         - Format: API
           Settings:
             OpenApiSpecUrl: <Reference to your openapispec.yaml schema created in Step 1>
             EndpointUrl: https://sampleurl <The server endpoint that is hosting the API>
   

2. 将 yaml 上传到 Security Copilot。 有关上传 YAML 的说明，请参阅 生成代理清单。

   注意

   需要完成插件的安装步骤才能使用并显示在 “自定义 ”部分中。 仅当清单 YAML 具有代理定义 () AgentDefinitions 定义时，上传的 YAML 或清单才会作为代理发布到 Active 代理。

3. 可以通过导航到 提示 中的“系统功能”来测试此工具或插件，然后搜索 lookupIpAddressGeolocation，这是operationId在步骤 1 中定义的 API 规范中的值。

   

   显示执行该工具后的响应。

   

步骤 3：创建并上传使用 API 插件的代理

现在，上传使用 API 插件的代理。

1. 上传代理时，请确保在“添加插件”屏幕中选择“此工作区中的任何人”。

2. 将代理 YAML 上传到Security Copilot。

步骤 4： (可选的) 将包发布到安全存储

此步骤仅适用于开发必须发布到安全存储的代理的合作伙伴。

将 API 清单发布到安全存储的重要注意事项：

• 将包发布到安全存储时， openapispec.yaml 包中必须包含 。

• 必须 OpenApiSpecUrl 引用包中的本地文件路径。

• EndpointUrl是 OpenAPI 规范的公开托管终结点。

• ChildSkills如果在 Open API 规范中引用 ，请确保 OpenAPISpec 和本地 OpenAPISpec yaml 的全局 URL 是最新的。

• openapispec.yaml必须与代理清单 yaml () http_manifest.yaml 位于同一文件夹中，并且必须遵循命名约定：openapispec_<number>.yaml。