genai-toolbox/docs/en/getting-started/quickstart/shared/configure_toolbox.md at 1f9cd1b134dc60ea57a94cd72b93fabeffbefbe7

mirror of https://github.com/googleapis/genai-toolbox.git synced 2026-02-05 12:45:11 -05:00

Files

Yuan Teoh 293c1d6889 feat!: update configuration file v2 (#2369 )

This PR introduces a significant update to the Toolbox configuration
file format, which is one of the primary **breaking changes** required
for the implementation of the Advanced Control Plane.

# Summary of Changes
The configuration schema has been updated to enforce resource isolation
and facilitate atomic, incremental updates.
* Resource Isolation: Resource definitions are now separated into
individual blocks, using a distinct structure for each resource type
(Source, Tool, Toolset, etc.). This improves readability, management,
and auditing of configuration files.
* Field Name Modification: Internal field names have been modified to
align with declarative methodologies. Specifically, the configuration
now separates kind (general resource type, e.g., Source) from type
(specific implementation, e.g., Postgres).

# User Impact
Existing tools.yaml configuration files are now in an outdated format.
Users must eventually update their files to the new YAML format.

# Mitigation & Compatibility
Backward compatibility is maintained during this transition to ensure no
immediate user action is required for existing files.
* Immediate Backward Compatibility: The source code includes a
pre-processing layer that automatically detects outdated configuration
files (v1 format) and converts them to the new v2 format under the hood.
* [COMING SOON] Migration Support: The new toolbox migrate subcommand
will be introduced to allow users to automatically convert their old
configuration files to the latest format.

# Example
Example for config file v2:
```
kind: sources
name: my-pg-instance
type: cloud-sql-postgres
project: my-project
region: my-region
instance: my-instance
database: my_db
user: my_user
password: my_pass
---
kind: authServices
name: my-google-auth
type: google
clientId: testing-id
---
kind: tools
name: example_tool
type: postgres-sql
source: my-pg-instance
description: some description
statement: SELECT * FROM SQL_STATEMENT;
parameters:
- name: country
  type: string
  description: some description
---
kind: tools
name: example_tool_2
type: postgres-sql
source: my-pg-instance
description: returning the number one
statement: SELECT 1;
---
kind: toolsets
name: example_toolset
tools:
- example_tool
```

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Averi Kitsch <akitsch@google.com>

2026-01-27 16:58:43 -08:00

4.0 KiB

Raw Blame History

In this section, we will download Toolbox, configure our tools in a tools.yaml, and then run the Toolbox server.

Download the latest version of Toolbox as a binary:

{{< notice tip >}} Select the correct binary corresponding to your OS and CPU architecture. {{< /notice >}}

export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64
curl -O https://storage.googleapis.com/genai-toolbox/v0.26.0/$OS/toolbox

Make the binary executable:
```
chmod +x toolbox
```

Write the following into a tools.yaml file. Be sure to update any fields such as user, password, or database that you may have customized in the previous step.

{{< notice tip >}} In practice, use environment variable replacement with the format ${ENV_NAME} instead of hardcoding your secrets into the configuration file. {{< /notice >}}

kind: sources
name: my-pg-source
type: postgres
host: 127.0.0.1
port: 5432
database: toolbox_db
user: toolbox_user
password: my-password
---
kind: tools
name: search-hotels-by-name
type: postgres-sql
source: my-pg-source
description: Search for hotels based on name.
parameters:
  - name: name
    type: string
    description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';
---
kind: tools
name: search-hotels-by-location
type: postgres-sql
source: my-pg-source
description: Search for hotels based on location.
parameters:
  - name: location
    type: string
    description: The location of the hotel.
statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%';
---
kind: tools
name: book-hotel
type: postgres-sql
source: my-pg-source
description: >-
   Book a hotel by its ID. If the hotel is successfully booked, returns a NULL, raises an error if not.
parameters:
  - name: hotel_id
    type: string
    description: The ID of the hotel to book.
statement: UPDATE hotels SET booked = B'1' WHERE id = $1;
---
kind: tools
name: update-hotel
type: postgres-sql
source: my-pg-source
description: >-
  Update a hotel's check-in and check-out dates by its ID. Returns a message
  indicating  whether the hotel was successfully updated or not.
parameters:
  - name: hotel_id
    type: string
    description: The ID of the hotel to update.
  - name: checkin_date
    type: string
    description: The new check-in date of the hotel.
  - name: checkout_date
    type: string
    description: The new check-out date of the hotel.
statement: >-
  UPDATE hotels SET checkin_date = CAST($2 as date), checkout_date = CAST($3
  as date) WHERE id = $1;
---
kind: tools
name: cancel-hotel
type: postgres-sql
source: my-pg-source
description: Cancel a hotel by its ID.
parameters:
  - name: hotel_id
    type: string
    description: The ID of the hotel to cancel.
statement: UPDATE hotels SET booked = B'0' WHERE id = $1;
---
kind: toolsets
name: my-toolset
tools:
  - search-hotels-by-name
  - search-hotels-by-location
  - book-hotel
  - update-hotel
  - cancel-hotel

For more info on tools, check out the Resources section of the docs.

Run the Toolbox server, pointing to the tools.yaml file created earlier:
```
./toolbox --tools-file "tools.yaml"
```
{{< notice note >}} Toolbox enables dynamic reloading by default. To disable, use the --disable-reload flag. {{< /notice >}}

4.0 KiB Raw Blame History

4.0 KiB

Raw Blame History