github/genai-toolbox
1
0
Fork 0
mirror of https://github.com/googleapis/genai-toolbox.git synced 2026-02-11 23:55:07 -05:00
Code Issues Packages Projects Releases 14 Wiki Activity

docs: add documentation for tools (#40)

Browse Source 
Adds more detailed documentation on tools and parameters.
This commit is contained in:
Kurtis Van Gent
2024-11-01 17:03:51 -06:00
committed by GitHub
parent efe9e8bc97
commit 0a0d206efd
2 changed files with 176 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
docs/tools/README.md Normal file
View File

@@ -0,0 +1,116 @@
# 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:
```yaml
tools:
search_flights_by_number:
kind: cloud-sql-postgres-generic
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:
* [alloydb-postgres](./alloydb-pg.md) - Run a SQL statement against an AlloyDB
for PostgreSQL instance.
* [cloud-sql-postgres](./cloud-sql-pg.md) - Run a SQL statement against a Cloud
SQL for PostgreSQL instance.
* [postgres-generic](./postgres.md) - Run a PostgreSQL statement against a
PostgreSQL-compatible 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:
```yaml
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.
```yaml
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:
```yaml
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. |

60
docs/tools/postgres-generic.md Normal file
View File

@@ -0,0 +1,60 @@
# PostgreSQL Generic Tool
The "postgres-generic" tool executes a pre-defined SQL statement.
## Requirements
PostgreSQL Generic Tools require one of the following sources:
- [postgres](../sources/postgres.md)
## Example
```yaml
tools:
search_flights_by_number:
kind: postgres-generic
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
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------------------------------------------:|:------------:|-----------------------------------------------------------------------------------------------------|
| kind | string | true | Must be "postgres-generic". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | true | Port to connect to (e.g. "5432") |
| statement | string | true | SQL statement to execute on. |
| parameters | [parameter](README.md#specifying-parameters) | true | List of [parameters](README.md#specifying-parameters) that will be inserted into the SQL statement. |