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

chore: migrate tools to docsite (#235)

Browse Source 
This migrates the 'tools' documentation to the new docsite.
This commit is contained in:
Kurtis Van Gent
2025-02-04 12:18:35 -07:00
committed by GitHub
parent 69395fa637
commit 77a9999a24
9 changed files with 310 additions and 245 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/tools/README.md → docs/en/resources/tools/_index.md
View File

@@ -1,8 +1,16 @@
# Tools
---
title: "Tools"
type: docs
weight: 2
description: >
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 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:
@@ -42,24 +50,11 @@ tools:
description: 1 to 4 digit number
```
## Kinds of Tools
We currently support the following types of kinds of tools:
* [postgres-sql](./postgres-sql.md) - Run a PostgreSQL statement against a
PostgreSQL-compatible database.
* [spanner](./spanner.md) - Run a Spanner (either googlesql or postgresql)
statement againts Spanner database.
* [neo4j-cypher](./neo4j-cypher.md) - Run a Cypher statement against a
Neo4j database.
* [dgraph-dql](./dgraph-dql.md) - Run a DQL statement against a
Dgraph database.
## Specifying Parameters
Parameters for each Tool will define what inputs the Agent will need to provide
to invoke them. Parameters should be passed as a list of Parameter objects.
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:
@@ -141,12 +136,12 @@ specific claims within the user's ID token.
field: sub
```
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|----------------------------------------------------------------------------|
| name | string | true | Name of the [authSources](../authSources/README.md) used to verify the OIDC auth token. |
| field | string | true | Claim field decoded from the OIDC token used to auto-populate this parameter.|
| **field** | **type** | **required** | **description** |
|-----------|:--------:|:------------:|-----------------------------------------------------------------------------------------|
| name | string | true | Name of the [authSources](../authSources/README.md) 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
## Authorized Invocations
You can require an authorization check for any Tool invocation request by
specifying an `authRequired` field. Specify a list of
@@ -164,3 +159,5 @@ tools:
- my-google-auth
- other-auth-service
```
## Kinds of tools

116
docs/en/resources/tools/dgraph-dql.md Normal file
View File

@@ -0,0 +1,116 @@
---
title: "dgraph-dql"
type: docs
weight: 1
description: >
A "dgraph-dql" tool executes a pre-defined DQL statement against a Dgraph
database.
---
## About
A ` dgraph-dql` tool executes a pre-defined DQL statement against a Dgraph
database. It's compatible with any of the following sources:
- [dgraph](../sources/dgraph.md)
To run a statement as a query, you need to set the config `isQuery=true`. For
upserts or mutations, set `isQuery=false`. You can also configure timeout for a
query.
## Example
{{< tabpane >}}
{{< tab header="Query" lang="yaml" >}}
tools:
search_user:
kind: dgraph-dql
source: my-dgraph-source
statement: |
query all($role: string){
users(func: has(name)) @filter(eq(role, $role) AND ge(age, 30) AND le(age, 50)) {
uid
name
email
role
age
}
}
isQuery: true
timeout: 20s
description: |
Use this tool to retrieve the details of users who are admins and are between 30 and 50 years old.
The query returns the user's name, email, role, and age.
This can be helpful when you want to fetch admin users within a specific age range.
Example: Fetch admins aged between 30 and 50:
[
{
"name": "Alice",
"role": "admin",
"age": 35
},
{
"name": "Bob",
"role": "admin",
"age": 45
}
]
parameters:
- name: $role
type: string
description: admin
{{< /tab >}}
{{< tab header="Mutation" lang="yaml" >}}
tools:
dgraph-manage-user-instance:
kind: dgraph-dql
source: my-dgraph-source
isQuery: false
statement: |
{
set {
_:user1 <name> $user1 .
_:user1 <email> $email1 .
_:user1 <role> "admin" .
_:user1 <age> "35" .
_:user2 <name> $user2 .
_:user2 <email> $email2 .
_:user2 <role> "admin" .
_:user2 <age> "45" .
}
}
description: |
Use this tool to insert or update user data into the Dgraph database.
The mutation adds or updates user details like name, email, role, and age.
Example: Add users Alice and Bob as admins with specific ages.
parameters:
- name: user1
type: string
description: Alice
- name: email1
type: string
description: alice@email.com
- name: user2
type: string
description: Bob
- name: email2
type: string
description: bob@email.com
{{< /tab >}}
{{< /tabpane >}}
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:------------------------------------------:|:------------:|----------------------------------------------------------------------------------------------|
| kind | string | true | Must be "dgraph-dql". |
| source | string | true | Name of the source the dql query should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
| statement | string | true | dql statement to execute |
| isQuery | boolean | false | To run statment as query set true otherwise false |
| timeout | string | false | To set timout for query |
| parameters | [parameters](_index#specifying-parameters) | false | List of [parameters](_index#specifying-parameters) that will be used with the dql statement. |

34
docs/tools/mssql-sql.md → docs/en/resources/tools/mssql-sql.md
View File

@@ -1,16 +1,24 @@
# SQL Server Tool
---
title: "mssql-sql"
type: docs
weight: 1
description: >
A "mssql-sql" tool executes a pre-defined SQL statement against a SQL Server
database.
---
A "mssql-sql" tool executes a pre-defined SQL statement against a SQL Server
## About
A `mssql-sql` tool executes a pre-defined SQL statement against a SQL Server
database. It's compatible with any of the following sources:
- [cloud-sql-mssql](../sources/cloud-sql-mssql.md)
- [mssql](../sources/mssql.md)
Toolbox supports the [prepare statement syntax][prepare-statement] of MS SQL
Server and expects parameters in the SQL query to be in the form of either @Name
or @p1 to @pN (ordinal position).
Server and expects parameters in the SQL query to be in the form of either
`@Name` or `@p1` to `@pN` (ordinal position).
```sql
```go
db.QueryContext(ctx, `select * from t where ID = @ID and Name = @p2;`, sql.Named("ID", 6), "Bob")
```
@@ -58,10 +66,10 @@ tools:
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------------------------------------------:|:------------:|-----------------------------------------------------------------------------------------------------|
| kind | string | true | Must be "mssql-sql". |
| source | string | true | Name of the source the T-SQL statement should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
| statement | string | true | SQL statement to execute. |
| parameters | [parameter](README.md#specifying-parameters) | true | List of [parameters](README.md#specifying-parameters) that will be inserted into the SQL statement. |
| **field** | **type** | **required** | **description** |
|-------------|:------------------------------------------:|:------------:|--------------------------------------------------------------------------------------------------|
| kind | string | true | Must be "mssql-sql". |
| source | string | true | Name of the source the T-SQL statement should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
| statement | string | true | SQL statement to execute. |
| parameters | [parameters](_index#specifying-parameters) | false | List of [parameters](_index#specifying-parameters) that will be inserted into the SQL statement. |

28
docs/tools/mysql-sql.md → docs/en/resources/tools/mysql-sql.md
View File

@@ -1,8 +1,18 @@
# MySQL Tool
---
title: "mysql-sql"
type: docs
weight: 1
description: >
A "mysql-sql" tool executes a pre-defined SQL statement against a SQL Server
database.
---
A "mysql-sql" tool executes a pre-defined SQL statement against a mysql
## About
A `mysql-sql` tool executes a pre-defined SQL statement against a mysql
database. It's compatible with any of the following sources:
- [cloud-sql-mysql](../sources/cloud-sql-mysql.md)
- [mysql](../sources/mysql.md)
The specified SQL statement is executed as a [prepared statement][mysql-prepare],
and expects parameters in the SQL query to be in the form of placeholders `?`.
@@ -51,12 +61,12 @@ tools:
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------------------------------------------:|:------------:|-----------------------------------------------------------------------------------------------------|
| kind | string | true | Must be "mysql-sql". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
| 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. |
| **field** | **type** | **required** | **description** |
|-------------|:------------------------------------------:|:------------:|--------------------------------------------------------------------------------------------------|
| kind | string | true | Must be "mysql-sql". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
| statement | string | true | SQL statement to execute on. |
| parameters | [parameters](_index#specifying-parameters) | false | List of [parameters](_index#specifying-parameters) that will be inserted into the SQL statement. |

71
docs/en/resources/tools/neo4j-cypher.md Normal file
View File

@@ -0,0 +1,71 @@
---
title: "neo4j-cypher"
type: docs
weight: 1
description: >
A "neo4j-cypher" tool executes a pre-defined cypher statement against a Neo4j
database.
---
## About
A `neo4j-cypher` tool executes a pre-defined Cypher statement against a Neo4j
database. It's compatible with any of the following sources:
- [neo4j](../sources/neo4j.md)
The specified Cypher statement is executed as a [parameterized
statement][neo4j-parameters], and specified parameters will be used according to
their name: e.g. `$id`.
[neo4j-parameters]:
https://neo4j.com/docs/cypher-manual/current/syntax/parameters/
## Example
```yaml
tools:
search_movies_by_actor:
kind: neo4j-cypher
source: my-neo4j-movies-instance
statement: |
MATCH (m:Movie)<-[:ACTED_IN]-(p:Person)
WHERE p.name = $name AND m.year > $year
RETURN m.title, m.year
LIMIT 10
description: |
Use this tool to get a list of movies for a specific actor and a given minium release year.
Takes an full actor name, e.g. "Tom Hanks" and a year e.g 1993 and returns a list of movie titles and release years.
Do NOT use this tool with a movie title. Do NOT guess an actor name, Do NOT guess a year.
A actor name is a fully qualified name with first and last name separated by a space.
For example, if given "Hanks, Tom" the actor name is "Tom Hanks".
If the tool returns more than one option choose the most recent movies.
Example:
{{
"name": "Meg Ryan",
"year": 1993
}}
Example:
{{
"name": "Clint Eastwood",
"year": 2000
}}
parameters:
- name: name
type: string
description: Full actor name, "firstname lastname"
- name: year
type: integer
description: 4 digit number starting in 1900 up to the current year
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:------------------------------------------:|:------------:|-------------------------------------------------------------------------------------------------|
| kind | string | true | Must be "neo4j-cypher". |
| source | string | true | Name of the source the Cypher query should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
| statement | string | true | Cypher statement to execute |
| parameters | [parameters](_index#specifying-parameters) | false | List of [parameters](_index#specifying-parameters) that will be used with the Cypher statement. |

31
docs/tools/postgres-sql.md → docs/en/resources/tools/postgres-sql.md
View File

@@ -1,14 +1,23 @@
# Postgres SQL Tool
---
title: "postgres-sql"
type: docs
weight: 1
description: >
A "postgres-sql" tool executes a pre-defined SQL statement against a Postgres
database.
---
A "postgres-sql" tool executes a pre-defined SQL statement against a postgres
## About
A `postgres-sql` tool executes a pre-defined SQL statement against a Postgres
database. It's compatible with any of the following sources:
- [alloydb-postgres](../sources/alloydb-pg.md)
- [cloud-sql-postgres](../sources/cloud-sql-pg.md)
- [postgres](../sources/postgres.md)
The specified SQL statement is executed as a [prepared statement][pg-prepare],
and specified parameters will inserted according to their position: e.g. "$1"
will be the first parameter specified, "$@" will be the second parameter, and so
and specified parameters will inserted according to their position: e.g. `1`
will be the first parameter specified, `$@` will be the second parameter, and so
on.
@@ -56,12 +65,12 @@ tools:
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------------------------------------------:|:------------:|-----------------------------------------------------------------------------------------------------|
| kind | string | true | Must be "postgres-sql". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
| 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. |
| **field** | **type** | **required** | **description** |
|-------------|:------------------------------------------:|:------------:|--------------------------------------------------------------------------------------------------|
| kind | string | true | Must be "postgres-sql". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
| statement | string | true | SQL statement to execute on. |
| parameters | [parameters](_index#specifying-parameters) | false | List of [parameters](_index#specifying-parameters) that will be inserted into the SQL statement. |

66
docs/tools/spanner.md → docs/en/resources/tools/spanner-sql.md
View File

@@ -1,27 +1,43 @@
# Spanner Tool
---
title: "spanner-sql"
type: docs
weight: 1
description: >
A "spanner-sql" tool executes a pre-defined SQL statement against a Google
Cloud Spanner database.
---
A "spanner-sql" tool executes a pre-defined SQL statement (either
`googlesql` or `postgresql`) against Spanner database. It's
compatible with any of the following sources:
## About
A `spanner-sql` tool executes a pre-defined SQL statement (either `googlesql` or
`postgresql`) against a Cloud Spanner database. It's compatible with any of the
following sources:
- [spanner](../sources/spanner.md)
For `googlesql` dialect, the specified SQL statement is executed
as a [data manipulation language (DML)][gsql-dml] statements, and specified parameters will inserted
according to their name: e.g. "@name".
For `postgresql` dialect, the specified SQL statement is executed as a
[prepared statement][pg-prepare], and specified parameters will inserted according
to their position: e.g. "$1" will be the first parameter specified, "$@" will be the
second parameter, and so on.
### GoogleSQL
For the `googlesql` dialect, the specified SQL statement is executed as a [data
manipulation language (DML)][gsql-dml] statements, and specified parameters will
inserted according to their name: e.g. `@name`.
[gsql-dml]: https://cloud.google.com/spanner/docs/reference/standard-sql/dml-syntax
### PostgreSQL
For the `postgresql` dialect, the specified SQL statement is executed as a [prepared
statement][pg-prepare], and specified parameters will inserted according to
their position: e.g. `$1` will be the first parameter specified, `$@` will be
the second parameter, and so on.
[pg-prepare]: https://www.postgresql.org/docs/current/sql-prepare.html
## Example
For `googlesql` dialect:
```yaml
{{< tabpane >}}
{{< tab header="GoogleSQL" lang="yaml" >}}
tools:
search_flights_by_number:
kind: spanner
@@ -57,10 +73,10 @@ tools:
- name: flight_number
type: string
description: 1 to 4 digit number
```
For `postgresql` dialect:
```yaml
{{< /tab >}}
{{< tab header="PostgreSQL" lang="yaml" >}}
tools:
search_flights_by_number:
kind: spanner
@@ -96,15 +112,17 @@ tools:
- name: flight_number
type: string
description: 1 to 4 digit number
```
{{< /tab >}}
{{< /tabpane >}}
## 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. |
| **field** | **type** | **required** | **description** |
|-------------|:------------------------------------------:|:------------:|--------------------------------------------------------------------------------------------------|
| kind | string | true | Must be "spanner-sql". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
| statement | string | true | SQL statement to execute on. |
| parameters | [parameters](_index#specifying-parameters) | false | List of [parameters](_index#specifying-parameters) that will be inserted into the SQL statement. |

105
docs/tools/dgraph-dql.md
View File

@@ -1,105 +0,0 @@
# Dgraph DQL Tool
A "dgraph-dql" tool executes a pre-defined DQL statement against a Dgraph database. It's compatible with any of the following
sources:
- [dgraph](../sources/dgraph.md)
To run a statement as a query, you need to set the config isQuery=true. For upserts or mutations, set isQuery=false.
You can also configure timeout for a query.
## Example
### Query:
```yaml
tools:
search_user:
kind: dgraph-dql
source: my-dgraph-source
statement: |
query all($role: string){
users(func: has(name)) @filter(eq(role, $role) AND ge(age, 30) AND le(age, 50)) {
uid
name
email
role
age
}
}
isQuery: true
timeout: 20s
description: |
Use this tool to retrieve the details of users who are admins and are between 30 and 50 years old.
The query returns the user's name, email, role, and age.
This can be helpful when you want to fetch admin users within a specific age range.
Example: Fetch admins aged between 30 and 50:
[
{
"name": "Alice",
"role": "admin",
"age": 35
},
{
"name": "Bob",
"role": "admin",
"age": 45
}
]
parameters:
- name: $role
type: string
description: admin
```
### Mutation:
```yaml
tools:
dgraph-manage-user-instance:
kind: dgraph-dql
source: my-dgraph-source
isQuery: false
statement: |
{
set {
_:user1 <name> $user1 .
_:user1 <email> $email1 .
_:user1 <role> "admin" .
_:user1 <age> "35" .
_:user2 <name> $user2 .
_:user2 <email> $email2 .
_:user2 <role> "admin" .
_:user2 <age> "45" .
}
}
description: |
Use this tool to insert or update user data into the Dgraph database.
The mutation adds or updates user details like name, email, role, and age.
Example: Add users Alice and Bob as admins with specific ages.
parameters:
- name: user1
type: string
description: Alice
- name: email1
type: string
description: alice@email.com
- name: user2
type: string
description: Bob
- name: email2
type: string
description: bob@email.com
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|----------:|:------------:|----------------------------------------------------------------------------------------------------|
| kind | string | true | Must be "dgraph-dql". |
| source | string | true | Name of the source the dql query should execute on. |
| description | string | true | Description of the tool |
| statement | string | true | dql statement to execute |
| isQuery | boolean | false | To run statment as query set true otherwise false |
| timeout | string | false | To set timout for query |
| parameters | parameter | true | List of [parameters](README.md#specifying-parameters) that will be used with the dql statement. |

59
docs/tools/neo4j-cypher.md
View File

@@ -1,59 +0,0 @@
# Neo4j Cypher Tool
A "neo4j-cypher" tool executes a pre-defined Cypher statement against a Neo4j database. It's compatible with any of the following sources:
- [neo4j](../sources/neo4j.md)
The specified Cypher statement is executed as a [parameterized statement][neo4j-parameters],
and specified parameters will be used according to their name: e.g. `$id`.
[neo4j-parameters]: https://neo4j.com/docs/cypher-manual/current/syntax/parameters/
## Example
```yaml
tools:
search_movies_by_actor:
kind: neo4j-cypher
source: my-neo4j-movies-instance
statement: |
MATCH (m:Movie)<-[:ACTED_IN]-(p:Person)
WHERE p.name = $name AND m.year > $year
RETURN m.title, m.year
LIMIT 10
description: |
Use this tool to get a list of movies for a specific actor and a given minium release year.
Takes an full actor name, e.g. "Tom Hanks" and a year e.g 1993 and returns a list of movie titles and release years.
Do NOT use this tool with a movie title. Do NOT guess an actor name, Do NOT guess a year.
A actor name is a fully qualified name with first and last name separated by a space.
For example, if given "Hanks, Tom" the actor name is "Tom Hanks".
If the tool returns more than one option choose the most recent movies.
Example:
{{
"name": "Meg Ryan",
"year": 1993
}}
Example:
{{
"name": "Clint Eastwood",
"year": 2000
}}
parameters:
- name: name
type: string
description: Full actor name, "firstname lastname"
- name: year
type: integer
description: 4 digit number starting in 1900 up to the current year
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|----------:|:------------:|----------------------------------------------------------------------------------------------------|
| kind | string | true | Must be "neo4j-cypher". |
| source | string | true | Name of the source the Cypher query should execute on. |
| description | string | true | Description of the tool |
| statement | string | true | Cypher statement to execute |
| parameters | parameter | true | List of [parameters](README.md#specifying-parameters) that will be used with the Cypher statement. |