mirror of
https://github.com/googleapis/genai-toolbox.git
synced 2026-04-09 03:02:26 -04:00
293c1d6889
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>
122 lines
2.9 KiB
Markdown
122 lines
2.9 KiB
Markdown
---
|
|
title: "Configuration"
|
|
type: docs
|
|
weight: 6
|
|
description: >
|
|
How to configure Toolbox's tools.yaml file.
|
|
---
|
|
|
|
The primary way to configure Toolbox is through the `tools.yaml` file. If you
|
|
have multiple files, you can tell toolbox which to load with the `--tools-file
|
|
tools.yaml` flag.
|
|
|
|
You can find more detailed reference documentation to all resource types in the
|
|
[Resources](../resources/).
|
|
|
|
### Using Environment Variables
|
|
|
|
To avoid hardcoding certain secret fields like passwords, usernames, API keys
|
|
etc., you could use environment variables instead with the format `${ENV_NAME}`.
|
|
|
|
```yaml
|
|
user: ${USER_NAME}
|
|
password: ${PASSWORD}
|
|
```
|
|
|
|
A default value can be specified like `${ENV_NAME:default}`.
|
|
|
|
```yaml
|
|
port: ${DB_PORT:3306}
|
|
```
|
|
|
|
### Sources
|
|
|
|
The `sources` section of your `tools.yaml` defines what data sources your
|
|
Toolbox should have access to. Most tools will have at least one source to
|
|
execute against.
|
|
|
|
```yaml
|
|
kind: sources
|
|
name: my-pg-source
|
|
type: postgres
|
|
host: 127.0.0.1
|
|
port: 5432
|
|
database: toolbox_db
|
|
user: ${USER_NAME}
|
|
password: ${PASSWORD}
|
|
```
|
|
|
|
For more details on configuring different types of sources, see the
|
|
[Sources](../resources/sources/).
|
|
|
|
### Tools
|
|
|
|
The `tools` section of your `tools.yaml` defines the actions your agent can
|
|
take: what type of tool it is, which source(s) it affects, what parameters it
|
|
uses, etc.
|
|
|
|
```yaml
|
|
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 || '%';
|
|
```
|
|
|
|
For more details on configuring different types of tools, see the
|
|
[Tools](../resources/tools/).
|
|
|
|
### Toolsets
|
|
|
|
The `toolsets` section of your `tools.yaml` allows you to define groups of tools
|
|
that you want to be able to load together. This can be useful for defining
|
|
different sets for different agents or different applications.
|
|
|
|
```yaml
|
|
kind: toolsets
|
|
name: my_first_toolset
|
|
tools:
|
|
- my_first_tool
|
|
- my_second_tool
|
|
---
|
|
kind: toolsets
|
|
name: my_second_toolset
|
|
tools:
|
|
- my_second_tool
|
|
- my_third_tool
|
|
```
|
|
|
|
You can load toolsets by name:
|
|
|
|
```python
|
|
# This will load all tools
|
|
all_tools = client.load_toolset()
|
|
|
|
# This will only load the tools listed in 'my_second_toolset'
|
|
my_second_toolset = client.load_toolset("my_second_toolset")
|
|
```
|
|
|
|
### Prompts
|
|
|
|
The `prompts` section of your `tools.yaml` defines the templates containing
|
|
structured messages and instructions for interacting with language models.
|
|
|
|
```yaml
|
|
kind: prompts
|
|
name: code_review
|
|
description: "Asks the LLM to analyze code quality and suggest improvements."
|
|
messages:
|
|
- content: "Please review the following code for quality, correctness, and potential improvements: \n\n{{.code}}"
|
|
arguments:
|
|
- name: "code"
|
|
description: "The code to review"
|
|
```
|
|
|
|
For more details on configuring different types of prompts, see the
|
|
[Prompts](../resources/prompts/).
|