OpenAPI-Tools

Ein Agent kann über ein OpenAPI-Tool eine Verbindung zu einer externen API herstellen, indem er das OpenAPI-Schema bereitstellt. Der KI-Agent ruft die API in Ihrem Namen auf.

Einschränkungen:

  • Jedes OpenAPI-Tool kann nur einen Vorgang oder eine Funktion haben.

Beispielschema:

openapi: 3.0.0
info:
  title: Simple Pets API
  version: 1.0.0
servers:
  - url: 'https://api.pet-service-example.com/v1'
paths:
  /pets/{petId}:
    get:
      summary: Return a pet by ID.
      operationId: getPet
      parameters:
        - in: path
          name: petId
          required: true
          description: Pet id
          schema:
            type: integer
      responses:
        200:
          description: OK
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      parameters:
        - name: petName
          in: query
          required: false
          description: Pet name
          schema:
            type: string
        - name: label
          in: query
          description: Pet label
          style: form
          explode: true
          required: false
          schema:
            type: array
            items:
              type: string
        - name: X-OWNER
          in: header
          description: Optional pet owner provided in the HTTP header
          required: false
          schema:
            type: string
        - name: X-SESSION
          in: header
          description: session id
          required: true
          schema:
            type: string
          x-ces-session-context: $context.session_id
      responses:
        '200':
          description: An array of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
    post:
      summary: Create a new pet
      operationId: createPet
      requestBody:
        description: Pet to add to the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '201':
          description: Pet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        owner:
          type: string
        label:
          type: array
          items:
            type: string

Sitzungskontextvariablen einfügen

Sie können Variablen aus dem Sitzungskontext, z. B. die Sitzungs-ID, in Ihre OpenAPI-Anfragen einfügen. Verwenden Sie das Erweiterungsfeld x-ces-session-context in der Parameterdefinition. Der Wert sollte der Pfad zur Variablen im context-Objekt sein.

Beispiel:

      parameters:
        - name: X-SESSION
          in: header
          description: session id
          required: true
          schema:
            type: string
          # This extension injects the session ID
          x-ces-session-context: $context.session_id

Sicherheitsaspekte

Beim Konfigurieren von OpenAPI-Tools ist es wichtig zu wissen, wie Berechtigungen gehandhabt werden:

  • Identität für die Ausführung von Tools:Aktionen, die vom OpenAPI-Tool ausgeführt werden, werden mit den Berechtigungen des CX Agent Studio-Dienstkontos ausgeführt, nicht mit den direkten Berechtigungen des Endnutzers, der mit dem Agent interagiert.
  • Risiko des transitiven Zugriffs:Wenn das Dienstkonto von CX Agent Studio Berechtigungen zum Aufrufen von Cloud Run-Funktionen hat, kann das Tool potenziell jede Funktion aufrufen, auf die über dieses Dienstkonto zugegriffen werden kann, auch wenn der Endnutzer keinen direkten Zugriff hat.

So können Sie potenzielle Risiken im Zusammenhang mit diesem Verhalten mindern:

  1. Dedizierte Projekte verwenden:Wir empfehlen dringend, Agent-Anwendungen in einem dedizierten Projekt bereitzustellen, das von anderen wichtigen Ressourcen oder sensiblen Funktionen getrennt ist. Durch diese Isolation wird der Umfang der Berechtigungen, die für das Dienstkonto des CX Agent Studio-Dienst-Agents verfügbar sind, eingeschränkt.
  2. VPC Service Controls implementieren:Verwenden Sie VPC Service Controls, um einen Dienstperimeter für Ihre vertraulichen Dienste zu definieren. So können Sie den Zugriff auf Dienste wie Cloud Run Functions steuern und unerwünschte Aufrufe über das Dienstkonto des CX Agent Studio verhindern.
  3. Prinzip der geringsten Berechtigung anwenden:Das Dienstkonto von CX Agent Studio sollte nur die minimal erforderlichen Identity and Access Management-Rollen und -Berechtigungen erhalten, die für die beabsichtigte Funktion erforderlich sind.

API-Authentifizierung

Die folgenden Authentifizierungsoptionen werden beim Aufrufen einer externen API unterstützt:

Dienst-Agent-ID-Token

CX Agent Studio kann mit dem Service-Agent der Customer Engagement Suite ein ID-Token generieren. Das Token wird dem HTTP-Autorisierungsheader hinzugefügt, wenn CX Agent Studio eine externe API aufruft.

Wenn sich Cloud Run-Funktionen und Cloud Run-Dienste im selben Projekt wie der Agent befinden, benötigen Sie keine zusätzlichen IAM-Berechtigungen, um sie aufzurufen. Wenn sie sich in verschiedenen Projekten befinden, kann mit einem ID-Token auf Cloud Run-Funktionen und Cloud Run-Dienste zugegriffen werden, nachdem Sie der Dienst-Agent-Adresse die Rollen roles/cloudfunctions.invoker und roles/run.invoker zugewiesen haben.

Dienstkonto-Authentifizierung

Dienstkonten können verwendet werden, um Toolanfragen bei allen Google-APIs zu authentifizieren, die dies unterstützen. Geben Sie die E‑Mail-Adresse Ihres Dienstkontos an.

Erstellen Sie ein Dienstkonto, falls noch nicht geschehen.

Da es sich bei Dienstkonten um Hauptkonten handelt, können Sie einem Dienstkonto Zugriff auf Ressourcen in Ihrem Projekt gewähren, indem Sie ihm eine Rolle zuweisen, wie Sie es auch für jedes andere Hauptkonto tun würden. Die E-Mail-Adresse des Dienstkontos wird verwendet, um ein Zugriffstoken zu generieren, das im Authorization-Header der Tool-Anfrage gesendet wird.

Der Nutzer, der das Tool für die Verwendung von Dienstkonten konfiguriert, muss die folgenden Berechtigungen haben:

  • roles/iam.serviceAccountUser

Damit Dialogflow CX Tokens generieren kann, muss der Dienst-Agent der Customer Engagement Suite die folgenden Berechtigungen haben:

  • roles/iam.serviceAccountTokenCreator

Das Dienstkonto muss außerdem Berechtigungen für den Zugriff auf den Dienst haben, auf dem das Tool gehostet wird.

OAuth

Geben Sie die OAuth-Informationen für den verwendeten Dienst an.

Wenn Sie OAuth für einen Google-Dienst verwenden, müssen Sie OAuth für den Dienst konfigurieren.

API-Schlüssel

Sie können die API-Schlüsselauthentifizierung konfigurieren, indem Sie den Schlüsselnamen, den Anfragespeicherort (Header oder Abfragestring) und den API-Schlüssel angeben, damit CX Agent Studio den API-Schlüssel in der Anfrage übergibt. Geben Sie Ihren API-Schlüssel mit der Secret Manager-Secret-Version an.

Secret Manager-Authentifizierung

Sie können Anmeldedaten als Secrets mit Secret Manager speichern. So authentifizieren Sie Ihr Tool mit Secrets:

  1. Erstellen Sie ein Secret, falls Sie noch keines haben.
  2. Weisen Sie dem Customer Engagement Suite-Dienst-Agenten die Rolle Zugriffsperson für Secret Manager-Secret (roles/secretmanager.secretAccessor) für das neue Secret zu.
  3. Kopieren Sie die Anmeldedaten in die Zwischenablage.
  4. Fügen Sie Ihrem Secret eine neue Secret-Version hinzu. Fügen Sie die Anmeldedaten als Secret-Wert ein.
    • Lassen Sie am Ende alle Zeilenumbruchzeichen weg.
  5. Kopieren Sie den Namen der Secret-Version, die Sie gerade hinzugefügt haben. Das Namensformat ist projects/{project_id}/secrets/{secret_id}/versions/{version_id}. Verwenden Sie diese Secret-Version für die Toolkonfiguration.