Freigeben über

Hinzufügen eines API-Tools (Plug-Ins) zu Ihrem Agent

Wichtig

Einige Informationen in diesem Artikel beziehen sich auf ein vorab veröffentlichtes Produkt, das vor der kommerziellen Veröffentlichung möglicherweise erheblich geändert wird. Microsoft übernimmt mit diesen Informationen keinerlei Gewährleistung, sei sie ausdrücklich oder konkludent.

Agent-Entwickler müssen häufig HTTP-Anforderungen stellen, um vollständige Anwendungsfälle zu erstellen.

In diesem Beispiel wird das Erstellen eines Agents veranschaulicht, der ein Plug-In mit einem API-Tool nutzt, um eine Verbindung mit einem REST-API-Dienst namens freeipapi.comherzustellen, der Geo-IP-Suchfunktionen bereitstellt.

Der gesamte Prozess sieht wie folgt aus:

  1. Schritt 1: Erstellen und Veröffentlichen einer OpenAPI-Spezifikation, die die API definiert

  2. Schritt 2: Erstellen und Hochladen der Manifestdatei in Security Copilot

  3. Schritt 3: Erstellen und Hochladen eines Agents, der das Plug-In verwendet

  4. Schritt 4: Veröffentlichen des Pakets im Sicherheitsspeicher (gilt nur für Partner-Agents)

    Hinweis

    Ein YAML-Manifestbeispiel, das das API-Tool (Skill) verwendet, finden Sie unter Erstellen eines Agents mit mehreren Tools. Es enthält Anweisungen zum Hochladen des Agents, zum Einrichten und Ausführen des Agents, der auf der Seite Aktive Agents veröffentlicht wurde.

Schritt 1: Erstellen und Veröffentlichen einer OpenAPI-Spezifikation

Das Beispiel wird in die REST-API für kostenlose IP-Adressen integriert, um Nachschlagevorgänge für die Geolocation von IP-Adressen durchzuführen. Sie müssen diese Spezifikation online veröffentlichen (ein GitHub-Gist funktioniert gut). Lesen Sie das folgende Beispiel, um Ihre Spezifikation zu erstellen und zu hosten. Beispiele zur Authentifizierung finden Sie unter Authentifizierungstypen.

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

Schritt 2: Erstellen und Hochladen des API-Manifests (Plug-Ins)

  1. Erstellen Sie eine Datei namens http_manifest.yaml im Toolformat 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. Laden Sie yaml in Security Copilot hoch. Die Anweisungen zum Hochladen des YAML finden Sie unter Build-Agent-Manifest.

    Hinweis

    Sie müssen die Einrichtungsschritte ausführen, damit das Plug-In zur Verwendung verfügbar ist und im Abschnitt Benutzerdefiniert angezeigt wird. Das hochgeladene YAML oder Manifest wird nur dann als Agent für aktive Agents veröffentlicht, wenn für das Manifest-YAML eine Agentdefinition (AgentDefinitions) definiert ist.

  3. Sie können dieses Tool oder Plug-In testen, indem Sie zu Systemfunktionen in Prompts navigieren und nach lookupIpAddressGeolocationsuchen. Dies ist der operationId Wert aus der API-Spezifikation, die Sie in Schritt 1 definiert haben.

    Abbildung der Toolsuche in Security Copilot

    Die Antwort nach dem Ausführen des Tools wird angezeigt.

    Abbildung der Antwort der Toolausführung in Security Copilot

Schritt 3: Erstellen und Hochladen eines Agents, der das API-Plug-In verwendet

Laden Sie nun den Agent hoch, der das API-Plug-In verwendet.

  1. Wenn Sie einen Agent hochladen, stellen Sie sicher, dass Sie im Bildschirm Plug-In hinzufügen die Option Jeder in diesem Arbeitsbereich auswählen.

  2. Laden Sie den YAML-Agent in Security Copilot hoch.

Schritt 4: (optional) Veröffentlichen des Pakets im Sicherheitsspeicher

Dieser Schritt gilt nur für Partner, die ihren Agent entwickeln, der im Sicherheitsspeicher veröffentlicht werden muss.

Wichtige Überlegungen zum Veröffentlichen eines API-Manifests im Sicherheitsspeicher:

  • Wenn Sie Ihr Paket im Sicherheitsspeicher veröffentlichen, muss im openapispec.yaml Paket enthalten sein.

  • Der OpenApiSpecUrl muss auf den lokalen Dateipfad innerhalb des Pakets verweisen.

  • ist EndpointUrl der öffentlich gehostete Endpunkt für die OpenAPI-Spezifikation.

  • ChildSkills Wenn in einer Open API-Spezifikation auf verwiesen wird, stellen Sie sicher, dass die globale URL für Ihre OpenAPISpec und die lokale OpenAPISpec-YAML-Datei auf dem neuesten Stand sind.

  • muss openapispec.yaml sich im selben Ordner wie das Agent-Manifest yaml(http_manifest.yaml) befinden und muss der Namenskonvention folgen: openapispec_<number>.yaml.

  • Last updated on