Some products and features are in the process of being renamed. Generative playbook and flow features are also being migrated to a single consolidated console.

Playbook tools

Using tools, you can connect playbooks to external systems. These systems can augment the knowledge of playbooks and empower them to execute complex tasks efficiently.

You can use built-in tools or build customized tools to suit your requirements.

Tool testing

Once you have created a tool, you can use the tool testing feature to verify that it works. When viewing a tool, click the Test button above the tool pane. This opens the tool for input in the simulator. Provide tool input, then click View Output to verify the correct tool output.

You can also use the tool testing feature when you add a tool to an example.

Built-in tools

Built-in tools are hosted by Google. You can activate these tools in agents without the need for manual configuration.

The supported built-in tools are:

Code Interpreter: A Google first-party tool that combines the capability of code generation and code execution and lets you perform various tasks, including data analysis, data visualization, text processing, and solving equations or optimization problems.

Your agent is optimized to determine how and when these tools should be invoked, but you can provide additional examples to fit your use cases.

Example schema:

{
  "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

An agent can connect to an external API using an OpenAPI tool by providing the OpenAPI schema. By default, the agent will call the API on your behalf.

You can test that the tool is set up correctly using the Test tool feature available on the tool page. This feature is also available in the example view when you add a tool invocation to the example.

Alternatively, you can execute OpenAPI tools on the client side.

Example schema:

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

You can use the internal schema reference @dialogflow/sessionId as a parameter schema type. With this parameter schema type, the Dialogflow CX session ID for the current conversation is supplied as a parameter value.

For example:

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

OpenAPI tool limitations

The following limitations apply:

The supported parameter types are path, query, and header. The cookie parameter type isn't supported.
Parameters defined by OpenAPI schema support the following data types: string, number, integer, boolean, and array. The object type isn't supported.
You can't specify query parameters in the console example editor.
The request and response bodies must be empty or use the application/json format.

OpenAPI tool schema generation

When you provide a schema, click Use Gemini to create your schema using generative AI.

Provide the following details to guide the generation:

A request URL.
An HTTP method, such as GET or POST.
Sample input.
Sample output.
A text prompt describing the tool.

After you generate the schema, you can edit it as needed and add additional URLs and methods manually.

OpenAPI tool API authentication

You can use the following authentication options when calling an external API.

Dialogflow CX Service Agent authentication

Dialogflow CX can generate an ID token using the Dialogflow CX Service Agent. The token is added in the authorization HTTP header when Dialogflow CX calls an external API.

You can use an ID token to access Cloud Run functions and Cloud Run services after you grant the roles/cloudfunctions.invoker and roles/run.invoker roles to service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.

If the Cloud Run functions and Cloud Run services are in the same resource project, you don't need additional Identity and Access Management (IAM) permission to call them.

Service account authentication

Service accounts can authenticate tool requests to any Google APIs that support it.

If you haven't already, create a service account. Because service accounts are principals, you can grant them roles to access resources in your project, just as you can for any other principal. You can use the service account email to generate an access token that you send in the Authorization header of the tool request.

If you configure the tool to use service accounts, you must have the following permissions:

roles/iam.serviceAccountUser

To let Dialogflow CX generate tokens, grant the Dialogflow CX Service Agent the following permissions:

roles/iam.serviceAccountTokenCreator

The service account must also have permissions to access the service that is hosting the tool.

API key authentication

You can configure API key authentication by providing the key name, request location (header or query string), and API key so that Dialogflow CX passes the API key in the request.
We recommend supplying your API key by using Secret Manager.
After Aug 15, 2025, exported agents will no longer contain raw value API keys.

OAuth

The OAuth client credentials flow is supported for server-to-server authentication:

You can use this flow if the Generative AI App Builder is the resource owner and you don't need end-user authorization.
You must configure the client ID, client secret, and token endpoint from an OAuth provider in Dialogflow CX.
We recommend supplying your client secret by using Secret Manager. Exported agents don't contain raw value client secrets after Aug 15, 2025.
Dialogflow CX exchanges an OAuth access token from an OAuth provider and passes it in the authorization header of the request.

Bearer Token

You can configure Bearer authentication to dynamically pass the Bearer token from the client. This token is included in the authorization header of the request.
When setting up tool authentication, you can designate a session parameter to act as the Bearer token. For example, use $session.params.<parameter-name-for-token> to specify the token.

At runtime, assign the Bearer token to the session parameter:

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

If you need to configure a static token instead of fetching the token from a session parameter, we recommend supplying your token by using Secret Manager. After Aug 15, 2025, exported agents won't contain raw value Bearer tokens.

Mutual TLS authentication

For more information, see Mutual TLS authentication.
Custom client certificates are supported. You can set up client certificates at the agent level under the Security tab in agent settings.
The certificate (PEM format) and private key (PEM format) are required fields. Once set, this client certificate will be used during mutual TLS for all tools and webhooks.

Custom CA certificate

For more information, see Custom CA certificates.

Secret Manager authentication

If you use OAuth, API key, or Bearer token, you can store the credentials as secrets using Secret Manager.

Authenticate your tool using secrets by following these steps:

Create your secret if you don't have one already.
Grant Dialogflow Service Agent the Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) role on the new secret.
Copy your credential into the clipboard.
Add a new secret version to your secret. Paste your credential as the secret value.
- Omit any newline character at the end of the secret value.
Copy the name of the secret version you just added. The name format is projects/{project_id}/secrets/{secret_id}/versions/{version_id}.
Open the tool edit screen, then:
- If you use OAuth, select OAuth as the Authentication type, then click Secret version under Client secret and paste the secret version name to the Secret version input box.
- If you use API key, select API key as the Authentication type, then click Secret version under API key. Paste the secret version name to the Secret version input box.
- If you use Bearer token, select Bearer token as the Authentication type, then click Secret version under Bearer token. Paste the secret version name to the Secret version input box.
Click Save.

OpenAPI tool private network access

The OpenAPI tool integrates with Service Directory private network access to connect to API targets in your VPC network. This keeps the traffic within the Google Cloud network and enforces IAM and VPC Service Controls.

To set up an OpenAPI tool targeting a private network:

Follow Service Directory private network configuration to configure your VPC network and Service Directory endpoint.
Make sure that the Dialogflow CX Service Agent service account with the following address exists for your agent project:
```
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
```
Grant the Dialogflow CX Service Agent service account the following IAM roles:
- servicedirectory.viewer of the Service Directory project
- servicedirectory.pscAuthorizedService of the network project
Provide Service Directory Service along with the OpenAPI schema and optional authentication information when you create the tool.

OpenAPI tool session parameter access

The OpenAPI tool inputs are derived from the user's conversation with the LLM using the schema as a guide. In some situations, inputs might need to be derived from session parameters collected during a flow or provided as a query parameter input along with the user input.

You can specify session parameters that you need to pass as an input by using the following format:

     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: Breed of the pet.

If no such session parameters are available, the LLM-generated input is passed to the tool.

OpenAPI tool default values

You can use the OpenAPI schema to specify default values. These default values apply only when an LLM-generated input value or session parameter-based input value isn't available for that parameter or property.

You can specify default values as part of the schema as follows:

     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: Breed of the pet.
               page_size:
                 type: integer
                 description: Number of pets to return.
                 default: 10

If no LLM-generated value, session parameter value, or default value is present, the input will be unspecified.

Data store tools

For more information about using data store tools with a playbook, see the data store tools.

Connector tools

Connector tools let you configure an agent to perform actions by using your connections configured in Integration Connectors. Each connector tool is configured with a single connection and one or more actions. You can create multiple tools for a single connection to group different actions together for your agent to use.

The connector tool supports the following Connector types:

You can use examples to help agents use connector tools effectively by demonstrating how to call the tools and use responses.

Create a connection

To create a connection and connect it to your agent, go to Tools > Create, select the Connector tool type and your chosen connector type, and click Create Connection. This opens Integration Connectors creation with several fields pre-filled.

Alternatively, you can go to Integration Connectors and follow the instructions to create a connection.

Connector actions

You can make two types of actions available to your agent for each connector tool. For more information, see Entities, operations, and actions.

Entity CRUD operations:

Each connection has entities corresponding to the objects of that data source (for BigQuery, these are tables; for Salesforce, these are objects, like Order or Case).

You can perform CRUD operations on each entity:
- Create: Validates and creates an entity with specified field values.
- List: Filter-based search of entity instances.
- Update: Filter-based method for altering entity field values.
- Delete: Deletes an entity.
- Get: Retrieves a single entity using the entityId.
Note: The Get operation can only be used to fetch a single record from an entity that has a primary key. It's often more practical to use the List operation with a filterClause to retrieve an entity.

For more information about entity CRUD operations, see the Connectors documentation.
Connector-specific actions:

Many Connectors support an ExecuteCustomQuery action, which lets you execute a SQL query against the data source, where each of the data source entities can be referenced as tables. For more information, see the list of supported connectors.

Additional actions differ based on the connector type. For example, see the BigQuery connector actions or the Salesforce connector actions.

Configure input/output fields for CRUD operations

By selecting specific input or output fields for your connector tool action, you can limit the complexity of these actions for the agent.

For example, if you only need to create an entity with a subset of its fields, configuring this set of fields in your action simplifies the action for the agent.

Specifying a set of output fields reduces the tool response size to mitigate token limits. This lets the agent handle the output by exposing only the relevant fields.

Authentication

If the connection you're using allows authentication override, configure the tool to pass through credentials from specified session parameters.

Populate these credentials in the session parameters. The tool then passes them through automatically to the data source for authentication when calling actions.

Function tools

If you have capabilities accessible by your client code, but not accessible by OpenAPI tools, you can use function tools. The client side always executes function tools rather than the agent.

The process is as follows:

Your client code sends a detect intent request.
The agent detects that a function tool is required, and the detect intent response contains the name of the tool along with input arguments. This session is paused until another detect intent request is received with the tool result.
Your client code calls the tool.
Your client code sends another detect intent request that provides the tool result as output arguments.

The following example demonstrates the input and output schema of a function tool:

{
  "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"
    }
  }
}

The following example shows the initial detect intent request and response using 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"
          }
        }
      }
    ]
  }
}

The following example shows the second detect intent request that provides the tool result:

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

Client-side execution

You can execute OpenAPI and data store tools on the client side, much like function tools, by applying an API override when you interact with the session.