Einige Produkte und Funktionen werden umbenannt. Außerdem werden die Funktionen für generative Playbooks und Flows zu einer einzigen konsolidierten Konsole migriert.

Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Playbook-Tools

Mit Tools können Sie Playbooks mit externen Systemen verbinden. Diese Systeme können das Wissen von Playbooks erweitern und sie in die Lage versetzen, komplexe Aufgaben effizient auszuführen.

Sie können integrierte Tools verwenden oder benutzerdefinierte Tools erstellen, die Ihren Anforderungen entsprechen.

Tooltests

Nachdem Sie ein Tool erstellt haben, können Sie mit der Tool-Testfunktion prüfen, ob es funktioniert. Klicken Sie beim Ansehen eines Tools auf den Button Testen über dem Toolbereich. Dadurch wird das Tool für die Eingabe im Simulator geöffnet. Geben Sie die Eingabe für das Tool an und klicken Sie dann auf Ausgabe ansehen, um die korrekte Ausgabe des Tools zu prüfen.

Sie können die Funktion zum Testen von Tools auch verwenden, wenn Sie einem Beispiel ein Tool hinzufügen.

Integrierte Tools

Integrierte Tools werden von Google gehostet. Sie können diese Tools in Agenten aktivieren, ohne dass eine manuelle Konfiguration erforderlich ist.

Folgende integrierte Tools werden unterstützt:

Code Interpreter: Ein Tool von Google, das die Funktionen der Codegenerierung und Codeausführung kombiniert und es Nutzern ermöglicht, verschiedene Aufgaben auszuführen, darunter Datenanalyse, Datenvisualisierung, Textverarbeitung, Lösen von Gleichungen oder Optimierungsproblemen.

Ihr Agent ist so optimiert, dass er bestimmt, wie und wann diese Tools aufgerufen werden sollen. Sie können jedoch zusätzliche Beispiele für Ihre Anwendungsfälle bereitstellen.

Beispiele sollten ein Schema wie das folgende haben:

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/df-code-interpreter-tool",
    "action": "generate_and_execute",
    "inputParameters": [
      {
        "name": "generate_and_execute input",
        "value": "4 + 4"
      }
    ],
    "outputParameters": [
      {
        "name": "generate_and_execute output",
        "value": {
          "output_files": [
            {
              "name": "",
              "contents": ""
            }
          ],
          "execution_result": "8",
          "execution_error": "",
          "generated_code": "GENERATED_CODE"
        }
      }
    ]
  }
}

OpenAPI-Tools

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

Mit der Funktion „Tool testen“ auf der Toolseite können Sie prüfen, ob das Tool richtig eingerichtet ist. Diese Funktion ist auch in der Beispielansicht verfügbar, wenn Sie dem Beispiel einen Toolaufruf hinzufügen.

Alternativ können Sie OpenAPI-Tools auf der Clientseite ausführen.

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: Dialogflow session id
          required: false
          schema:
            $ref: "@dialogflow/sessionId"
      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

Optional können Sie die interne Schemareferenz @dialogflow/sessionId als Parameterschematyp verwenden. Bei diesem Parameterschematyp wird die Dialogflow-Sitzungs-ID für die aktuelle Unterhaltung als Parameterwert angegeben.

Beispiel:

- name: X-SESSION
   in: header
   description: Dialogflow session id
   required: false
   schema:
     $ref: "@dialogflow/sessionId"

Einschränkungen von OpenAPI-Tools

Es gelten folgende Einschränkungen:

Unterstützte Parametertypen sind path, query und header. Der Parametertyp cookie wird nicht unterstützt.
Durch das OpenAPI-Schema definierte Parameter unterstützen die folgenden Datentypen: string, number, integer, boolean, array. Der Typ object wird nicht unterstützt.
Im Beispiel-Editor der Console können Sie keine Abfrageparameter angeben.
Anfrage- und Antworttext müssen leer oder im JSON-Format sein.

OpenAPI-Tool-Schemagenerierung

Wenn Sie ein Schema angeben, können Sie mit dem Button Gemini verwenden generative KI nutzen, um Ihr Schema zu erstellen.

Sie können Folgendes angeben, um die Generierung zu steuern:

Eine Anfrage-URL
Eine HTTP-Methode (GET, POST usw.)
Beispieleingabe
Beispielausgabe:
Ein Text-Prompt, der das Tool beschreibt

Nachdem sie generiert wurde, können Sie sie nach Bedarf bearbeiten und zusätzliche URLs und Methoden manuell hinzufügen.

API-Authentifizierung für OpenAPI-Tools

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

Authentifizierung des Dialogflow-Dienst-Agenten

Dialogflow kann mit dem Dialogflow-Dienst-Agenten ein ID-Token generieren. Das Token wird im HTTP-Header für die Autorisierung hinzugefügt, wenn Dialogflow eine externe API aufruft.

Ein ID-Token kann für den Zugriff auf Cloud Run-Funktionen und Cloud Run-Dienste verwendet werden, nachdem Sie die Rollen roles/cloudfunctions.invoker und roles/run.invoker dem Dienstkonto service-agent-project-number@gcp-sa-dialogflow. zugewiesen haben. Wenn sich die Cloud Run Functions-Funktionen und Cloud Run-Dienste im selben Ressourcenprojekt befinden, benötigen Sie keine zusätzliche Identity and Access Management-Berechtigung, um sie aufzurufen.

Dienstkonto-Authentifizierung

Dienstkonten können verwendet werden, um Toolanfragen an alle Google APIs zu authentifizieren, die dies unterstützen.

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 Dialogflow-Dienst-Agent 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.

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 Dialogflow den API-Schlüssel in der Anfrage übergibt.
Wir empfehlen, den API-Schlüssel über Secret Manager bereitzustellen. Nach dem 15. August 2025 enthalten exportierte Agenten keine API-Schlüssel mit Rohwerten mehr.

OAuth

Der OAuth-Vorgang für Clientanmeldedaten wird für die Server-zu-Server-Authentifizierung unterstützt:
- Dieser Ablauf kann verwendet werden, wenn der Generative AI App Builder der Ressourceninhaber ist und keine Endnutzerautorisierung erforderlich ist.
- Die Client-ID, der Clientschlüssel und der Token-Endpunkt eines OAuth-Anbieters müssen in Dialogflow konfiguriert werden.
- Wir empfehlen, den Clientschlüssel über Secret Manager bereitzustellen. Nach dem 15. August 2025 enthalten exportierte Agenten keine Clientschlüssel mit Rohwerten mehr.
- Dialogflow tauscht ein OAuth-Zugriffstoken von einem OAuth-Anbieter aus und übergibt es im Autorisierungsheader der Anfrage.

Inhabertoken

Sie können die Bearer-Authentifizierung so konfigurieren, dass das Inhabertoken dynamisch vom Client übergeben wird. Dieses Token ist im Autorisierungsheader der Anfrage enthalten.
Beim Einrichten der Toolauthentifizierung können Sie einen Sitzungsparameter als Inhabertoken festlegen. Verwenden Sie beispielsweise $session.params.<parameter-name-for-token>, um das Token anzugeben.

Weisen Sie das Inhabertoken zur Laufzeit dem Sitzungsparameter zu:

DetectIntentRequest {
  ...
  query_params {
    parameters {
      <parameter-name-for-token>: <the-auth-token>
    }
  }
  ...
}

Wenn Sie ein statisches Token konfigurieren müssen, anstatt das Token aus einem Sitzungsparameter abzurufen, empfehlen wir, das Token über Secret Manager bereitzustellen. Nach dem 15. August 2025 enthalten exportierte Agenten keine Inhabertoken mit Rohwerten mehr.

Gegenseitige TLS-Authentifizierung

Weitere Informationen finden Sie in der Dokumentation zur gegenseitigen TLS-Authentifizierung.
Benutzerdefinierte Clientzertifikate werden unterstützt. Sie können Clientzertifikate auf Agent-Ebene auf dem Tab „Sicherheit“ in den Agent-Einstellungen einrichten. Das Zertifikat (PEM-Format) und der private Schlüssel (PEM-Format) sind Pflichtfelder. Nachdem dieses Clientzertifikat festgelegt wurde, wird es während des gegenseitigen TLS für alle Tools und Webhooks verwendet.

Benutzerdefiniertes CA-Zertifikat

Weitere Informationen finden Sie in der Dokumentation zu benutzerdefinierten CA-Zertifikaten.

Secret Manager-Authentifizierung

Wenn Sie OAuth, einen API-Schlüssel oder ein Inhabertoken verwenden, können Sie die Anmeldedaten mit Secret Manager als Secrets speichern. So authentifizieren Sie Ihr Tool mithilfe von Secrets:

Erstellen Sie ein Secret, falls Sie noch keines haben.
Weisen Sie dem Dialogflow-Dienst-Agenten die Rolle Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) für das neue Secret zu.
Kopieren Sie Ihre Anmeldedaten in die Zwischenablage.
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.
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}".
Öffnen Sie den Bearbeitungsbildschirm des Tools und gehen Sie dann so vor:
- Wenn Sie OAuth verwenden, wählen Sie OAuth als Authentifizierungstyp aus. Klicken Sie dann unter Clientschlüssel auf Secret-Version und fügen Sie den Namen der Secret-Version in das Eingabefeld Secret-Version ein.
- Wenn Sie einen API-Schlüssel verwenden, wählen Sie API-Schlüssel als Authentifizierungstyp aus und klicken Sie dann unter API-Schlüssel auf Secret-Version. Fügen Sie den Namen der Secret-Version in das Eingabefeld Secret-Version ein.
- Wenn Sie ein Inhabertoken verwenden, wählen Sie Inhabertoken als Authentifizierungstyp aus und klicken Sie dann unter Inhabertoken auf Secret-Version. Fügen Sie den Namen der Secret-Version in das Eingabefeld Secret-Version ein.
Klicken Sie auf Speichern.

Privater Netzwerkzugriff für OpenAPI-Tool

Das OpenAPI-Tool ist in den privaten Netzwerkzugriff von Service Directory eingebunden, sodass es eine Verbindung zu API-Zielen in Ihrem VPC-Netzwerk herstellen kann. Dadurch bleibt der Traffic im Google Cloud -Netzwerk und IAM und VPC Service Controls werden erzwungen.

So richten Sie ein OpenAPI-Tool ein, das auf ein privates Netzwerk ausgerichtet ist:

Folgen Sie der Anleitung unter Private Netzwerkkonfiguration für Service Directory, um Ihr VPC-Netzwerk und Ihren Service Directory-Endpunkt zu konfigurieren.
Das Dienstkonto Dialogflow-Dienst-Agent mit der folgenden Adresse muss für Ihr Agent-Projekt vorhanden sein:
```
service-agent-project-number@gcp-sa-dialogflow.
```
Weisen Sie dem Dienstkonto Dialogflow-Dienst-Agent die folgenden IAM-Rollen (Identity and Access Management) zu:
- servicedirectory.viewer des Service Directory-Projekts
- servicedirectory.pscAuthorizedService des Netzwerkprojekts
Geben Sie beim Erstellen des Tools den Service Directory-Dienst zusammen mit dem OpenAPI-Schema und optionalen Authentifizierungsinformationen an.

Zugriff auf Sitzungsparameter des OpenAPI-Tools

Die Eingaben für das Open API-Tool werden aus der Unterhaltung des Nutzers mit dem LLM abgeleitet, wobei das Schema als Leitfaden dient. In einigen Situationen müssen Eingaben möglicherweise von Sitzungsparametern abgeleitet werden, die während eines Ablaufs erfasst oder als Suchparameter zusammen mit der Nutzereingabe bereitgestellt werden.

Der Sitzungsparameter, der als Eingabe übergeben werden muss, kann so angegeben werden:

     parameters:
       - in: query
         name: petId
         required: true
         description: Pet id
         schema:
           type: integer
           x-agent-input-parameter: petId # Reads from the $session.params.petId
       - in: header
         name: X-other
         schema:
           type: string
           x-agent-input-parameter: $request.payload.header # Reads from the header specified in the request payload input
     requestBody:
       required: false
       content:
         application/json:
           schema:
             type: object
             properties:
               name:
                 type: string
                 x-agent-input-parameter: petName # Reads from the $session.params.petName
                 description: Name of the person to greet (optional).
               breed:
                 type: string
                 description: Bread of the pet.

Wenn kein solcher Sitzungsparameter verfügbar ist, wird die vom LLM generierte Eingabe an das Tool übergeben.

Standardwerte für OpenAPI-Tools

Mit dem Open API-Schema können Standardwerte angegeben werden. Die Standardwerte werden nur verwendet, wenn für diesen Parameter oder diese Property kein vom LLM generierter Eingabewert oder sitzungsparameterbasierter Eingabewert vorhanden ist.

Die Standardwerte können im Schema so angegeben werden:

     parameters:
       - in: query
         name: zipcode
         required: true
         description: Zip code to search for
         schema:
           type: integer
           default: 94043
     requestBody:
       content:
         application/json:
           schema:
             type: object
             properties:
               breed:
                 type: string
                 description: Bread of the pet.
               page_size:
                 type: integer
                 description: Number of pets to return.
                 default: 10

Wenn kein LLM-generierter Wert, Sitzungsparameterwert oder Standardwert vorhanden ist, wird die Eingabe nicht angegeben.

Datenspeichertools

Informationen zur Verwendung von Datenspeichertools mit einem Playbook finden Sie in der Dokumentation zu Datenspeichertools.

Connector-Tools

Connector-Tools können von einem KI-Agenten verwendet werden, um Aktionen mit Ihren in Integration Connectors konfigurierten Verbindungen auszuführen. Jedes Connector-Tool wird mit einer Verbindung und einer oder mehreren Aktionen konfiguriert. Bei Bedarf können mehrere Tools für eine einzelne Verbindung erstellt werden, um verschiedene Aktionen zusammenzufassen, die Ihr KI-Agent verwenden soll.

Das Connector-Tool unterstützt die folgenden Connector-Typen:

Beispiele sollten verwendet werden, um die Nutzung von Connector-Tools durch den KI-Agenten zu verbessern. Dazu wird gezeigt, wie der KI-Agent das Tool aufrufen und die Antwort verwenden sollte.

Verbindung herstellen

Wenn Sie eine Verbindung erstellen und mit Ihrem Agenten verbinden möchten, rufen Sie Tools > Erstellen auf, wählen Sie den Tooltyp Connector und den gewünschten Connectortyp aus und klicken Sie auf den Button Verbindung erstellen. Sie werden zur Erstellung von Integration Connectors weitergeleitet, wobei einige Felder bereits vorausgefüllt sind.

Alternativ können Sie zu Integration Connectors wechseln und der Anleitung zum Erstellen einer Verbindung folgen.

Connector-Aktionen

Für jedes Connector-Tool gibt es zwei Arten von Aktionen, die Ihrem Agenten zur Verfügung gestellt werden können. Weitere Informationen finden Sie unter Entitäten, Vorgänge und Aktionen:

CRUD-Vorgänge für Entitäten

Jede Ihrer Verbindungen hat „Entitäten“, die den Objekten dieser Datenquelle entsprechen (für BigQuery sind dies Tabellen; für Salesforce sind dies Objekte wie „Bestellung“ oder „Fall“).

Sie können für jede Entität CRUD-Vorgänge ausführen:
- Erstellen: Erstellt eine Entität mit den angegebenen Feldwerten.
- Auflisten: filterbasierte Suche nach Entitätsinstanzen
- Update: filterbasierte Methode zum Ändern von Entitätsfeldwerten
- Löschen: Löscht eine Entität.
- Get ruft eine einzelne Entität anhand der entityId
  ab.
Hinweis: Der Get-Vorgang kann nur verwendet werden, um einen einzelnen Datensatz aus einer Entität mit einem Primärschlüssel abzurufen. Es ist oft praktischer, den List-Vorgang mit einer filterClause zu verwenden, um eine Entität abzurufen.

Weitere Informationen zu CRUD-Vorgängen für Entitäten finden Sie in der Connectors-Dokumentation.
Connectorspezifische Aktionen

Viele Connectors unterstützen die Aktion ExecuteCustomQuery, mit der eine SQL-Abfrage für die Datenquelle ausgeführt werden kann, wobei jede der Datenquellenentitäten als Tabelle referenziert werden kann. Eine Liste der unterstützten Connectors finden Sie hier.

Zusätzliche Aktionen unterscheiden sich je nach Connector-Typ. Weitere Informationen finden Sie beispielsweise unter BigQuery-Connector-Aktionen oder Salesforce-Connector-Aktionen.

Eingabe-/Ausgabefelder für CRUD-Vorgänge konfigurieren

Wenn Sie bestimmte Eingabe- oder Ausgabefelder für die Aktion des Connector-Tools auswählen, können Sie die Komplexität dieser Aktionen für den Agenten begrenzen.

Wenn Sie beispielsweise nur eine Entität mit einer Teilmenge ihrer Felder erstellen müssen, vereinfacht die Konfiguration dieser Felder in Ihrer Aktion die Aktion für den Agenten.

Wenn Sie eine Reihe von Ausgabefeldern angeben, wird die Größe der Toolantwort reduziert (hilfreich, wenn Tokenlimits ein Problem darstellen) und die Verarbeitung der Ausgabe durch den Agenten vereinfacht, da nur die relevanten Felder angezeigt werden.

Authentifizierung

Wenn für die von Ihnen verwendete Verbindung festgelegt ist, dass die Authentifizierung überschrieben werden darf, kann das Tool so konfiguriert werden, dass Anmeldedaten aus angegebenen Sitzungsparametern übergegeben werden.

Sie als Agenten-Builder sind dafür verantwortlich, wie diese Anmeldedaten in die Sitzungsparameter eingefügt werden. Das Tool übergibt sie automatisch an die Datenquelle, um sie für die Authentifizierung zu verwenden, wenn die Aktionen des Tools aufgerufen werden.

Funktionstools

Wenn Sie Funktionen haben, auf die Ihr Clientcode zugreifen kann, OpenAPI-Tools aber nicht, können Sie Funktionstools verwenden. Funktionstools werden immer clientseitig ausgeführt, nicht vom Agenten.

So läuft der Vorgang ab:

Ihr Clientcode sendet eine Intent-Erkennungsanfrage.
Der Agent erkennt, dass ein Funktionstool erforderlich ist, und die Antwort zur Intent-Erkennung enthält den Namen des Tools sowie Eingabeargumente. Diese Sitzung wird pausiert, bis eine weitere Intent-Erkennungsanfrage mit dem Tool-Ergebnis eingeht.
Ihr Clientcode ruft das Tool auf.
Ihr Clientcode sendet eine weitere Intent-Erkennungsanfrage, die das Tool-Ergebnis als Ausgabeargumente bereitstellt.

Das folgende Beispiel zeigt das Eingabe- und Ausgabeschema eines Funktionstools:

{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "The city and state, for example, San Francisco, CA"
    }
  },
  "required": [
    "location"
  ]
}

{
  "type": "object",
  "properties": {
    "temperature": {
      "type": "number",
      "description": "The temperature"
    }
  }
}

Das folgende Beispiel zeigt die erste Intent-Erkennungsanfrage und die Antwort mit REST:

HTTP method and URL:
POST https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent
{
  "queryInput": {
    "text": {
      "text": "what is the weather in Mountain View"
    },
    "languageCode": "en"
  }
}

{
  "queryResult": {
    "text": "what is the weather in Mountain View",
    "languageCode": "en",
    "responseMessages": [
      {
        "source": "VIRTUAL_AGENT",
        "toolCall": {
          "tool": "<tool-resource-name>",
          "action": "get-weather-tool",
          "inputParameters": {
            "location": "Mountain View"
          }
        }
      }
    ]
  }
}

Das folgende Beispiel zeigt die zweite Intent-Erkennungsanfrage, die das Tool-Ergebnis liefert:

{
  "queryInput": {
    "toolCallResult": {
      "tool": "<tool-resource-name>",
      "action": "get-weather-tool",
      "outputParameters": {
        "temperature": 28.0
      }
    },
    "languageCode": "en"
  }
}

Clientseitige Ausführung

Wie Funktionstools können auch OpenAPI- und Datenspeichertools clientseitig ausgeführt werden, indem bei der Interaktion mit der Sitzung ein API-Überschreiben angewendet wird.