diff --git a/.github/release-please.yml b/.github/release-please.yml index c9c58f9b64..6f0530cee7 100644 --- a/.github/release-please.yml +++ b/.github/release-please.yml @@ -20,7 +20,8 @@ extraFiles: [ "README.md", "docs/en/getting-started/introduction/_index.md", "docs/en/getting-started/local_quickstart.md", - "docs/en/getting-started/local_quickstart_bigquery.md", "docs/en/getting-started/mcp_quickstart/_index.md", "docs/en/how-to/deploy_gke.md", + "docs/en/samples/bigquery/local_quickstart.md", + "docs/en/samples/bigquery/mcp_quickstart.md", ] diff --git a/docs/en/about/_index.md b/docs/en/about/_index.md index 0196a69797..cc78c4b047 100644 --- a/docs/en/about/_index.md +++ b/docs/en/about/_index.md @@ -1,6 +1,6 @@ --- title: "About" type: docs -weight: 5 +weight: 6 description: A list of other information related to Toolbox. --- diff --git a/docs/en/samples/_index.md b/docs/en/samples/_index.md new file mode 100644 index 0000000000..3e4d96068c --- /dev/null +++ b/docs/en/samples/_index.md @@ -0,0 +1,6 @@ +--- +title: "Samples" +type: docs +weight: 5 +description: Samples and guides for using Toolbox. +--- diff --git a/docs/en/samples/bigquery/_index.md b/docs/en/samples/bigquery/_index.md new file mode 100644 index 0000000000..561afa8a4c --- /dev/null +++ b/docs/en/samples/bigquery/_index.md @@ -0,0 +1,7 @@ +--- +title: "Getting Started" +type: docs +weight: 1 +description: > + How to get started with Toolbox using BigQuery. +--- diff --git a/docs/en/getting-started/colab_quickstart_bigquery.ipynb b/docs/en/samples/bigquery/colab_quickstart_bigquery.ipynb similarity index 100% rename from docs/en/getting-started/colab_quickstart_bigquery.ipynb rename to docs/en/samples/bigquery/colab_quickstart_bigquery.ipynb diff --git a/docs/en/getting-started/local_quickstart_bigquery.md b/docs/en/samples/bigquery/local_quickstart.md similarity index 95% rename from docs/en/getting-started/local_quickstart_bigquery.md rename to docs/en/samples/bigquery/local_quickstart.md index 4f79ca4bbb..94577eeb4a 100644 --- a/docs/en/getting-started/local_quickstart_bigquery.md +++ b/docs/en/samples/bigquery/local_quickstart.md @@ -1,13 +1,13 @@ --- title: "Quickstart (Local with BigQuery)" type: docs -weight: 2 +weight: 1 description: > How to get started running Toolbox locally with Python, BigQuery, and LangGraph, LlamaIndex, or ADK. --- -[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/googleapis/genai-toolbox/blob/main/docs/en/getting-started/colab_quickstart_bigquery.ipynb) +[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/googleapis/genai-toolbox/blob/main/docs/en/samples/bigquery/colab_quickstart_bigquery.ipynb) ## Before you begin This guide assumes you have already done the following: @@ -74,7 +74,7 @@ In this section, we will create a BigQuery dataset and a table, then insert some For a real application, ensure that the service account or user running Toolbox has the necessary IAM permissions (e.g., BigQuery Data Editor, BigQuery User) on the dataset or project. For this local quickstart with user credentials, your own permissions will apply. {{< /notice >}} -2. The hotels table needs to be defined in your new dataset for use with the bq query command. First, create a file named `create_hotels_table.sql` with the following content: +1. The hotels table needs to be defined in your new dataset for use with the bq query command. First, create a file named `create_hotels_table.sql` with the following content: ```sql CREATE TABLE IF NOT EXISTS `YOUR_PROJECT_ID.YOUR_DATASET_NAME.hotels` ( @@ -95,7 +95,7 @@ In this section, we will create a BigQuery dataset and a table, then insert some ``` -3. Next, populate the hotels table with some initial data. To do this, create a file named `insert_hotels_data.sql` and add the following SQL INSERT statement to it. +1. Next, populate the hotels table with some initial data. To do this, create a file named `insert_hotels_data.sql` and add the following SQL INSERT statement to it. ```sql INSERT INTO `YOUR_PROJECT_ID.YOUR_DATASET_NAME.hotels` (id, name, location, price_tier, checkin_date, checkout_date, booked) @@ -135,16 +135,17 @@ In this section, we will download Toolbox, configure our tools in a `tools.yaml` curl -O https://storage.googleapis.com/genai-toolbox/v0.4.0/$OS/toolbox ``` - 2. Make the binary executable: + +1. Make the binary executable: ```bash chmod +x toolbox ``` -3. Write the following into a `tools.yaml` file. The `project` in the `sources` section will use the `GOOGLE_CLOUD_PROJECT` environment variable you set earlier. You must replace the `YOUR_DATASET_NAME` placeholder in the SQL `statement` fields with your actual BigQuery dataset name (e.g., the value of `$BQ_DATASET_NAME` from Step 1). The table name `hotels` is used directly in the statements. +1. Write the following into a `tools.yaml` file. You must replace the `YOUR_PROJECT_ID` and `YOUR_DATASET_NAME` placeholder in the config with your actual BigQuery project and dataset name. The `location` field is optional; if not specified, it defaults to 'us'. The table name `hotels` is used directly in the statements. {{< notice tip >}} - Authentication with BigQuery is handled via Application Default Credentials (ADC). Ensure you have run `gcloud auth application-default login`. Avoid hardcoding secrets. + Authentication with BigQuery is handled via Application Default Credentials (ADC). Ensure you have run `gcloud auth application-default login`. {{< /notice >}} ```yaml @@ -152,6 +153,7 @@ In this section, we will download Toolbox, configure our tools in a `tools.yaml` my-bigquery-source: kind: bigquery project: YOUR_PROJECT_ID + location: us tools: search-hotels-by-name: kind: bigquery-sql @@ -223,9 +225,9 @@ In this section, we will download Toolbox, configure our tools in a `tools.yaml` ``` Alternatively, you can modify the agent code to load tools individually (e.g., using `await toolbox_client.load_tool("search-hotels-by-name")`). - For more info on tools, check out the [Resources](../resources/) section of the docs. + For more info on tools, check out the [Resources](../../resources/) section of the docs. -4. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: +1. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: ```bash ./toolbox --tools_file "tools.yaml" diff --git a/docs/en/samples/bigquery/mcp_quickstart.md b/docs/en/samples/bigquery/mcp_quickstart.md new file mode 100644 index 0000000000..0f067c2d45 --- /dev/null +++ b/docs/en/samples/bigquery/mcp_quickstart.md @@ -0,0 +1,211 @@ +--- +title: "Quickstart (MCP with BigQuery)" +type: docs +weight: 2 +description: > + How to get started running Toolbox with MCP Inspector and BigQuery as the source. +--- + +## Overview + +[Model Context Protocol](https://modelcontextprotocol.io) is an open protocol +that standardizes how applications provide context to LLMs. Check out this page +on how to [connect to Toolbox via MCP](../../how-to/connect_via_mcp.md). + +## Step 1: Set up your BigQuery Dataset and Table + +In this section, we will create a BigQuery dataset and a table, then insert some data that needs to be accessed by our agent. + +1. Create a new BigQuery dataset (replace `YOUR_DATASET_NAME` with your desired dataset name, e.g., `toolbox_mcp_ds`, and optionally specify a location like `US` or `EU`): + + ```bash + export BQ_DATASET_NAME="YOUR_DATASET_NAME" + export BQ_LOCATION="US" + + bq --location=$BQ_LOCATION mk $BQ_DATASET_NAME + ``` + You can also do this through the [Google Cloud Console](https://console.cloud.google.com/bigquery). + +1. The `hotels` table needs to be defined in your new dataset. First, create a file named `create_hotels_table.sql` with the following content: + + + ```sql + CREATE TABLE IF NOT EXISTS `YOUR_PROJECT_ID.YOUR_DATASET_NAME.hotels` ( + id INT64 NOT NULL, + name STRING NOT NULL, + location STRING NOT NULL, + price_tier STRING NOT NULL, + checkin_date DATE NOT NULL, + checkout_date DATE NOT NULL, + booked BOOLEAN NOT NULL + ); + ``` + > **Note:** Replace `YOUR_PROJECT_ID` and `YOUR_DATASET_NAME` in the SQL with your actual project ID and dataset name. + + Then run the command below to execute the sql query: + ```bash + bq query --project_id=$GOOGLE_CLOUD_PROJECT --dataset_id=$BQ_DATASET_NAME --use_legacy_sql=false < create_hotels_table.sql + ``` + +1. . Next, populate the hotels table with some initial data. To do this, create a file named `insert_hotels_data.sql` and add the following SQL INSERT statement to it. + + ```sql + INSERT INTO `YOUR_PROJECT_ID.YOUR_DATASET_NAME.hotels` (id, name, location, price_tier, checkin_date, checkout_date, booked) + VALUES + (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-20', '2024-04-22', FALSE), + (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', FALSE), + (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', FALSE), + (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-05', '2024-04-24', FALSE), + (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-01', '2024-04-23', FALSE), + (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', FALSE), + (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-02', '2024-04-27', FALSE), + (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-09', '2024-04-24', FALSE), + (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', FALSE), + (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', FALSE); + ``` + > **Note:** Replace `YOUR_PROJECT_ID` and `YOUR_DATASET_NAME` in the SQL with your actual project ID and dataset name. + + Then run the command below to execute the sql query: + ```bash + bq query --project_id=$GOOGLE_CLOUD_PROJECT --dataset_id=$BQ_DATASET_NAME --use_legacy_sql=false < insert_hotels_data.sql + ``` + +## Step 2: Install and configure Toolbox + +In this section, we will download Toolbox, configure our tools in a `tools.yaml`, and then run the Toolbox server. + +1. Download the latest version of Toolbox as a binary: + + {{< notice tip >}} + Select the + [correct binary](https://github.com/googleapis/genai-toolbox/releases) + corresponding to your OS and CPU architecture. + {{< /notice >}} + + ```bash + export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64 + curl -O https://storage.googleapis.com/genai-toolbox/v0.4.0/$OS/toolbox + ``` + + +1. Make the binary executable: + + ```bash + chmod +x toolbox + ``` + +1. Write the following into a `tools.yaml` file. You must replace the `YOUR_PROJECT_ID` and `YOUR_DATASET_NAME` placeholder in the config with your actual BigQuery project and dataset name. The `location` field is optional; if not specified, it defaults to 'us'. The table name `hotels` is used directly in the statements. + + {{< notice tip >}} + Authentication with BigQuery is handled via Application Default Credentials (ADC). Ensure you have run `gcloud auth application-default login`. + {{< /notice >}} + + ```yaml + sources: + my-bigquery-source: + kind: bigquery + project: YOUR_PROJECT_ID + location: us + tools: + search-hotels-by-name: + kind: bigquery-sql + source: my-bigquery-source + description: Search for hotels based on name. + parameters: + - name: name + type: string + description: The name of the hotel. + statement: SELECT * FROM `YOUR_DATASET_NAME.hotels` WHERE LOWER(name) LIKE LOWER(CONCAT('%', @name, '%')); + search-hotels-by-location: + kind: bigquery-sql + source: my-bigquery-source + description: Search for hotels based on location. + parameters: + - name: location + type: string + description: The location of the hotel. + statement: SELECT * FROM `YOUR_DATASET_NAME.hotels` WHERE LOWER(location) LIKE LOWER(CONCAT('%', @location, '%')); + book-hotel: + kind: bigquery-sql + source: my-bigquery-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: integer + description: The ID of the hotel to book. + statement: UPDATE `YOUR_DATASET_NAME.hotels` SET booked = TRUE WHERE id = @hotel_id; + update-hotel: + kind: bigquery-sql + source: my-bigquery-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: 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. + - name: hotel_id + type: integer + description: The ID of the hotel to update. + statement: >- + UPDATE `YOUR_DATASET_NAME.hotels` SET checkin_date = PARSE_DATE('%Y-%m-%d', @checkin_date), checkout_date = PARSE_DATE('%Y-%m-%d', @checkout_date) WHERE id = @hotel_id; + cancel-hotel: + kind: bigquery-sql + source: my-bigquery-source + description: Cancel a hotel by its ID. + parameters: + - name: hotel_id + type: integer + description: The ID of the hotel to cancel. + statement: UPDATE `YOUR_DATASET_NAME.hotels` SET booked = FALSE WHERE id = @hotel_id; + toolsets: + my-toolset: + - search-hotels-by-name + - search-hotels-by-location + - book-hotel + - update-hotel + - cancel-hotel + ``` + + For more info on tools, check out the [Tools](../../resources/tools/_index.md) section. + +1. Run the Toolbox server, pointing to the `tools.yaml` file created earlier: + + ```bash + ./toolbox --tools_file "tools.yaml" + ``` + +## Step 3: Connect to MCP Inspector + +1. Run the MCP Inspector: + + ```bash + npx @modelcontextprotocol/inspector + ``` + +1. Type `y` when it asks to install the inspector package. + +1. It should show the following when the MCP Inspector is up and running: + + ```bash + 🔍 MCP Inspector is up and running at http://127.0.0.1:5173 🚀 + ``` + +1. Open the above link in your browser. + +1. For `Transport Type`, select `SSE`. + +1. For `URL`, type in `http://127.0.0.1:5000/mcp/sse`. + +1. Click Connect. + + ![inspector](../../getting-started/mcp_quickstart/inspector.png) + +1. Select `List Tools`, you will see a list of tools configured in `tools.yaml`. + + ![inspector_tools](../../getting-started/mcp_quickstart/inspector_tools.png) + +1. Test out your tools here! \ No newline at end of file