alloydb-ai-nl
The “alloydb-ai-nl” tool leverages AlloyDB AI next-generation Natural Language support to provide the ability to query the database directly using natural language.
Tools
Tools define actions an agent can take – such as reading and writing to a source.
A tool represents an action your agent can take, such as running a SQL
statement. You can define Tools as a map in the tools 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.
An airline code is a code for an airline service consisting of a two-character
airline designator and followed by a flight number, which is a 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 closest 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
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.
To use the array type, you must also specify what kind of items are
in the list using 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 are automatically populated with user information decoded from ID tokens that are passed in request headers. They do not take input values in request bodies like other parameters. To use authenticated parameters, you must configure the tool to map the required authServices to specific claims within the user’s ID token.
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
authServices:
# Refer to one of the `authServices` 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 authServices used to verify the OIDC auth token. |
| field | string | true | Claim field decoded from the OIDC token used to auto-populate this parameter. |
Authorized Invocations
You can require an authorization check for any Tool invocation request by
specifying an authRequired field. Specify a list of
authServices defined in the previous section.
tools:
search_all_flight:
kind: postgres-sql
source: my-pg-instance
statement: |
SELECT * FROM flights
# A list of `authServices` defined previously
authRequired:
- my-google-auth
- other-auth-service
Kinds of tools
BigQuery-sql
A “bigquery-sql” tool executes a pre-defined SQL statement.
bigtable-sql
A “bigtable-sql” tool executes a pre-defined SQL statement against a Google Cloud Bigtable instance.
dgraph-dql
A “dgraph-dql” tool executes a pre-defined DQL statement against a Dgraph database.
http
A “http” tool sends out an HTTP request to an HTTP endpoint.
mssql-sql
A “mssql-sql” tool executes a pre-defined SQL statement against a SQL Server database.
mysql-sql
A “mysql-sql” tool executes a pre-defined SQL statement against a SQL Server database.
neo4j-cypher
A “neo4j-cypher” tool executes a pre-defined cypher statement against a Neo4j database.
postgres-sql
A “postgres-sql” tool executes a pre-defined SQL statement against a Postgres database.
spanner-sql
A “spanner-sql” tool executes a pre-defined SQL statement against a Google Cloud Spanner database.
SQLite SQL
Execute SQL statements against a SQLite database.