OpenAPI-Tools

Ein Agent kann sich über ein OpenAPI-Tool mit einer externen API verbinden, wenn das OpenAPI-Schema bereitgestellt wird. Der KI-Agent ruft die API in Ihrem Namen auf.

Einschränkungen:

  • Ein 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. Weitere Informationen finden Sie unter Sitzungskontextvariablen.

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 verstehen, wie Berechtigungen gehandhabt werden:

  • Identität für die Toolausführung: 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 Agenten interagiert.
  • Risiko des transitiven Zugriffs: Wenn das CX Agent Studio-Dienstkonto Berechtigungen zum Aufrufen von Cloud Run Functions hat, kann das Tool potenziell jede Funktion aufrufen, auf die dieses Dienstkonto Zugriff hat, auch wenn der Endnutzer keinen direkten Zugriff hat.

So minimieren Sie potenzielle Risiken im Zusammenhang mit diesem Verhalten:

  1. Dedizierte Projekte verwenden: Wir empfehlen dringend, KI-Agentenanwendungen in einem dedizierten Projekt bereitzustellen, das von anderen kritischen Ressourcen oder sensiblen Funktionen getrennt ist. Durch diese Isolation wird der Umfang der Berechtigungen für das CX Agent Studio-Dienstkonto eingeschränkt.
  2. VPC Service Controls implementieren: Verwenden Sie VPC Service Controls, um einen Dienstperimeter für Ihre sensiblen Dienste zu definieren. So können Sie den Zugriff auf Dienste wie Cloud Run Functions steuern und unerwünschte Aufrufe über das CX Agent Studio-Dienstkonto verhindern.
  3. Prinzip der geringsten Berechtigung: Achten Sie darauf, dass dem CX Agent Studio-Dienstkonto nur die minimal erforderlichen Identity and Access Management-Rollen und -Berechtigungen zugewiesen werden, die für die vorgesehene Funktionalität erforderlich sind.

API-Authentifizierung

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

Dienst-Agent-ID-Token

CX Agent Studio kann mithilfe des Dienst-Agents der Customer Engagement Suite (Format: service-{PROJECT_NUMBER}@gcp-sa-ces.iam.gserviceaccount.com) ein ID-Token generieren. Das Token wird im HTTP-Header hinzugefügt, wenn CX Agent Studio eine externe API aufruft.

Wenn sich Cloud Run Functions 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 ein ID-Token für den Zugriff auf Cloud Run Functions und Cloud Run-Dienste verwendet 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 an alle 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 auf Ressourcen in Ihrem Projekt zugreifen, indem Sie ihnen 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 Toolanfrage 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, der das Tool hostet.

OAuth

Geben Sie die OAuth-Informationen für den von Ihnen 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 Speicherort der Anfrage (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-Version von Secret Manager an.

Secret Manager-Authentifizierung

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

  1. Erstellen Sie ein Secret, falls Sie noch keines haben.
  2. Weisen Sie dem Customer Engagement Suite-Dienst-Agenten die Rolle Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) für das neue Secret zu.
  3. Kopieren Sie Ihre Anmeldedaten in die Zwischenablage.
  4. Fügen Sie Ihrem Secret eine neue Secret-Version hinzu. Fügen Sie Ihre Anmeldedaten als Secret-Wert ein.
    • Lassen Sie am Ende alle Zeilenumbrüche 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.

Inhabertoken

Sie können die Inhabertoken-Authentifizierung so konfigurieren, dass ein in einer Sitzungskontextvariablen gespeichertes Inhabertoken im Authorization-Header der OpenAPI-Toolanfrage übergeben wird. Diese Option ist nützlich, wenn der KI-Agent ein vom Endnutzer erfasstes Token an eine andere API übergeben muss.

Geben Sie die Sitzungskontextvariable im folgenden Format an: $context.variables.VARIABLE_NAME, wobei VARIABLE_NAME der Name der Variablen ist, in der das Inhabertoken gespeichert wird.