genai-toolbox

🧰 Toolbox

[!CAUTION] Toolbox is experimental and not an official Google product. This is an early access project, intended to be shared under NDA to gather feedback validate direction. You should not share or discuss this project with anyone not under NDA.

Toolbox is an open source server that enables developers to build production-grade, agent-based generative AI applications that connect to databases via tools. It enables you to create database-focused tools easier, faster, and more securely by handling the complexities around connection pooling, authentication, and more.

Toolbox also helps simplifies the management of your tools by allowing you to add, remove, or update tools without necessarily redeploying your application. It sits between your application's orchestration framework (such as LangChain and LlamaIndex) and your database, providing a control plane that is used to modify, distribute, and invoke tools.

Table of Contents

• Getting Started
  • Installing the server
  • Running the server
  • Using with Client SDKs
• Configuration
  • Sources
  • Tools
  • Toolsets
• Versioning
• Contributing

Getting Started

Installing the server

For the latest version, check the releases page and use the following instructions for your OS and CPU architecture.

# see releases page for other versions
curl -O https://storage.googleapis.com/genai-toolbox/v0.0.1/linux/amd64/toolbox
chmod +x toolbox

# see releases page for other versions
docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION

go install github.com/googleapis/genai-toolbox@v0.0.1

Running the server

Configure a tools.yaml to define your tools, and then execute toolbox to start the server:

./toolbox --tools_file "tools.yaml"

You can use toolbox help for a full list of flags! To stop the server, send a terminate signal (ctrl+c on most platforms).

For more detailed documentation on deploying to different environments, check out the following in the /docs/deploy folder:

• Cloud Run.

Using with Client SDKs

Once your server is up and running, you can load the tools into your application. See below the list of Client SDKs for using various frameworks:

from toolbox_langchain_sdk import ToolboxClient

# update the url to point to your server
client = ToolboxClient("http://127.0.0.1:5000")

# these tools can be passed to your application! 
tools = await client.load_toolset()

from toolbox_llamaindex_sdk import ToolboxClient

# update the url to point to your server
client = ToolboxClient("http://127.0.0.1:5000")

# these tools can be passed to your application! 
tools = await client.load_toolset()

Configuration

You can configure what tools are available by updating the tools.yaml file. If you have multiple files, you can tell toolbox which to load with the --tools_file tools.yaml flag.

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.

sources:
    # This tool kind has some requirements. 
    # See https://github.com/googleapis/genai-toolbox/blob/main/docs/sources/cloud-sql-pg.md#requirements
    my-cloud-sql-source:
        kind: cloud-sql-postgres
        project: my-project-id
        region: us-central1
        instance: my-instance-name
        user: my-user
        password: my-password
        database: my_db

Example for Neo4j

sources:
    my-neo4j-source:
        kind: neo4j
        uri: neo4j+s://my-neo4j-host:7687
        user: neo4j
        password: my-password
        database: my_db

For more details on configuring different types of sources, see the Source documentation.

Tools

The tools section of your tools.yaml define your tools: what kind of tool it is, which source it affects, what parameters it takes, etc.

tools:
    get_flight_by_id:
        kind: postgres-sql
        source: my-cloud-sql-source
        description: >
            Use this tool to lookup a flight by its unique identifier.
        statement: "SELECT * FROM flights WHERE id = $1"
        parameters:
        - name: id
          type: integer
          description: 'id' represents the unique ID for each flight. 

Neo4j-Cypher Example

tools:
    get_movies_in_year:
        kind: neo4j-cypher
        source: my-neo4j-instance
        description: >
            Use this tool to list all movies titles in a given year. 
        statement: "MATCH (m:Movie) WHERE m.year = $year RETURN m.title"
        parameters:
          - name: "year"
            type: integer
            description: 'year' represents a 4 digit year since 1900 up to the current year 

For more details on configuring different types of tools, see the Tool documentation.

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 groups based on agent or application.

toolsets:
    my_first_toolset:
        - my_first_tool
        - my_second_tool
    my_second_toolset:
        - my_second_tool
        - my_third_tool

You can load toolsets by name:

# This will load all tools
all_tools = await client.load_toolset()

# This will only load the tools listed in 'my_second_toolset'
my_second_toolset = await client.load_toolset("my_second_toolset")

AuthSources

The authSources section of your tools.yaml defines what authentication sources your Toolbox should interact with.

authSources:
  my-google-auth:
    kind: google
    clientId: YOUR_GOOGLE_CLIENT_ID

For more details on configuring different types of sources, see the AuthSources documentation.

Versioning

This project uses semantic versioning, and uses the following lifecycle regarding support for a major version.

Contributing

Contributions are welcome. Please, see the CONTRIBUTING to get started.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See Contributor Code of Conduct for more information.