次の方法で共有

エージェントに API ツール (プラグイン) を追加する

重要

この記事の一部の情報は、市販される前に大幅に変更される可能性があるプレリリース製品に関するものです。 Microsoft は、ここに記載された情報に関して、明示または黙示を問わず、いかなる保証も行いません。

エージェント開発者は、多くの場合、完全なユース ケースを構築するために HTTP 要求を行う必要があります。

この例では、API ツールを使用してプラグインを利用して freeipapi.com という REST API サービスに接続するエージェントを作成し、geo-IP ルックアップ機能を提供する例を示します。

全体的なプロセスは次のとおりです。

  1. 手順 1: API を定義する OpenAPI 仕様を作成して発行する

  2. 手順 2: マニフェスト ファイルを作成してSecurity Copilotにアップロードする

  3. 手順 3: プラグインを使用するエージェントを作成してアップロードする

  4. 手順 4: パッケージを Security Store に発行する (パートナー エージェントにのみ適用)

    注:

    API ツール (スキル) を使用するマニフェスト YAML サンプルについては、「複数のツールを 使用したエージェントのビルド」を参照してください。 エージェントをアップロードし、[アクティブなエージェント] ページで発行されたエージェントを設定して実行する方法について説明します。

手順 1: OpenAPI 仕様を作成して発行する

この例では、Free 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 またはマニフェストは、マニフェスト YAML にエージェント定義 (AgentDefinitions) が定義されている場合にのみ、エージェントとして Active エージェントに発行されます。

  3. このツールまたはプラグインをテストするには、プロンプトのシステム機能に移動し、手順 1 で定義した API 仕様のoperationId値であるlookupIpAddressGeolocationを検索します。

    Security Copilotのツール参照の画像

    ツールの実行後の応答が表示されます。

    Security Copilotのツール実行応答の画像

手順 3: API プラグインを使用するエージェントを作成してアップロードする

次に、API プラグインを使用するエージェントをアップロードします。

  1. エージェントをアップロードするときは、[プラグインの追加] 画面で [このワークスペースの [すべてのユーザー] を選択していることを確認します。

  2. エージェント YAML をSecurity Copilotにアップロードします。

手順 4: (省略可能) セキュリティ ストアにパッケージを発行する

この手順は、Security Store に発行する必要があるエージェントを開発しているパートナーにのみ適用されます。

API マニフェストを Security Store に発行する際の重要な考慮事項:

  • パッケージを Security Store に発行する場合は、 openapispec.yaml をパッケージに含める必要があります。

  • OpenApiSpecUrlは、パッケージ内のローカル ファイル パスを参照する必要があります。

  • EndpointUrlは、OpenAPI 仕様のパブリックにホストされるエンドポイントです。

  • ChildSkillsが Open API 仕様で参照されている場合は、OpenAPISpec とローカルの OpenAPISpec yaml のグローバル URL が最新の状態であることを確認します。

  • openapispec.yamlは、エージェント マニフェスト yaml(http_manifest.yaml) と同じフォルダー内にあり、名前付け規則である openapispec_<number>.yaml に従う必要があります。

  • Last updated on