genai-toolbox/docs/tools/README.md

Tools

Tools represent an action your agent can take, such as running a SQL statement. You can define Tools as a map in the sources section of your tools.yaml file. Typically, a tool will require a source to act on:

tools:
 search_flights_by_number:
    kind: postgres-sql
    source: my-pg-instance
    statement: |
      SELECT * FROM flights
      WHERE airline = $1
      AND flight_number = $2
      LIMIT 10
    description: |
      Use this tool to get information for a specific flight.
      Takes an airline code and flight number and returns info on the flight.
      Do NOT use this tool with a flight id. Do NOT guess an airline code or flight number.
      A airline code is a code for an airline service consisting of two-character
      airline designator and followed by flight number, which is 1 to 4 digit number.
      For example, if given CY 0123, the airline is "CY", and flight_number is "123".
      Another example for this is DL 1234, the airline is "DL", and flight_number is "1234".
      If the tool returns more than one option choose the date closes to today.
      Example:
      {{
          "airline": "CY",
          "flight_number": "888",
      }}
      Example:
      {{
          "airline": "DL",
          "flight_number": "1234",
      }}
    parameters:
      - name: airline
        type: string
        description: Airline unique 2 letter identifier
      - name: flight_number
        type: string
        description: 1 to 4 digit number

Kinds of Tools

We currently support the following types of kinds of tools:

• postgres-sql - Run a PostgreSQL statement against a PostgreSQL-compatible database.
• spanner - Run a Spanner (either googlesql or postgresql) statement againts Spanner database.

Specifying Parameters

Parameters for each Tool will define what inputs the Agent will need to provide to invoke them. Parameters should be pass as a list of Parameter objects:

    parameters:
      - name: airline
        type: string
        description: Airline unique 2 letter identifier
      - name: flight_number
        type: string
        description: 1 to 4 digit number

Basic Parameters

Basic parameters types include string, integer, float, boolean types. In most cases, the description will be provided to the LLM as context on specifying the parameter.

    parameters:
      - name: airline
        type: string
        description: Airline unique 2 letter identifier

field	type	required	description
name	string	true	Name of the parameter.
type	string	true	Must be one of "string", "integer", "float", "boolean" "array"
description	string	true	Natural language description of the parameter to describe it to the agent.

Array Parameters

The array type is a list of items passed in as a single parameter. This type requires another Parameter to be specified under the items field:

    parameters:
      - name: preffered_airlines
        type: array
        description: A list of airline, ordered by preference. 
        items:
          - name: name 
            type: string
            description: Name of the airline. 

field	type	required	description
name	string	true	Name of the parameter.
type	string	true	Must be "array"
description	string	true	Natural language description of the parameter to describe it to the agent.
items	parameter object	true	Specify a Parameter object for the type of the values in the array.

Authenticated Parameters

Authenticated parameters automatically populate their values with user information decoded from your ID tokens passed in from request headers. They do not take input values in request bodies like other parameters. Instead, specify your configured authSources and corresponding claim fields in ID tokens to tell Toolbox which values they should be auto-populated with.

  tools:
    search_flights_by_user_id:
        kind: postgres-sql
        source: my-pg-instance
        statement: |
          SELECT * FROM flights WHERE user_id = $1
        parameters:
          - name: user_id
            type: string
            description: Auto-populated from Google login
            authSources:
              # Refer to one of the `authSources` defined
              - name: my-google-auth
              # `sub` is the OIDC claim field for user ID
                field: sub

field	type	required	description
name	string	true	Name of the authSources used to verify the OIDC auth token.
field	string	true	Claim field decoded from the OIDC token used to auto-populate this parameter.

Authorized Tool Call

You can require an authorization check for any Tool invocation request by specifying an authRequired field. Specify a list of authSources defined in the previous section.

tools:
  search_all_flight:
      kind: postgres-sql
      source: my-pg-instance
      statement: |
        SELECT * FROM flights
      # A list of `authSources` defined previously
      authRequired:
        - my-google-auth
        - other-auth-service