feat(healthcare): add support for healthcare source, tool and prebuilt config

.ci/integration.cloudbuild.yaml

@@ -214,6 +214,29 @@ steps:
           dataform \
           dataform
 
+  - id: "cloud-healthcare"
+    name: golang:1
+    waitFor: ["compile-test-binary"]
+    entrypoint: /bin/bash
+    env:
+      - "GOPATH=/gopath"
+      - "HEALTHCARE_PROJECT=$PROJECT_ID"
+      - "SERVICE_ACCOUNT_EMAIL=$SERVICE_ACCOUNT_EMAIL"
+      - "HEALTHCARE_REGION=$_REGION"
+      - "HEALTHCARE_DATASET=$_HEALTHCARE_DATASET"
+      - "HEALTHCARE_PREPOPULATED_DICOM_STORE=$_HEALTHCARE_PREPOPULATED_DICOM_STORE"
+    secretEnv: ["CLIENT_ID"]
+    volumes:
+      - name: "go"
+        path: "/gopath"
+    args:
+      - -c
+      - |
+        .ci/test_with_coverage.sh \
+          "Cloud Healthcare API" \
+          cloudhealthcare \
+          cloudhealthcare
+
   - id: "postgres"
     name: golang:1
     waitFor: ["compile-test-binary"]
@@ -937,6 +960,8 @@ substitutions:
   _ALLOYDB_AI_NL_CLUSTER: "alloydb-ai-nl-testing"
   _ALLOYDB_AI_NL_INSTANCE: "alloydb-ai-nl-testing-instance"
   _BIGTABLE_INSTANCE: "bigtable-testing-instance"
+  _HEALTHCARE_DATASET: "test-dataset"
+  _HEALTHCARE_PREPOPULATED_DICOM_STORE: "prepopulated-test-dicom-store"
   _POSTGRES_HOST: 127.0.0.1
   _POSTGRES_PORT: "5432"
   _SPANNER_INSTANCE: "spanner-testing"

cmd/root.go

@@ -69,6 +69,21 @@ import (
 	_ "github.com/googleapis/genai-toolbox/internal/tools/clickhouse/clickhouselistdatabases"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/clickhouse/clickhouselisttables"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/clickhouse/clickhousesql"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcarefhirfetchpage"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcarefhirpatienteverything"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcarefhirpatientsearch"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaregetdataset"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaregetdicomstore"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaregetdicomstoremetrics"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaregetfhirresource"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaregetfhirstore"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaregetfhirstoremetrics"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcarelistdicomstores"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcarelistfhirstores"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcareretrieverendereddicominstance"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaresearchdicominstances"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaresearchdicomseries"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaresearchdicomstudies"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudmonitoring"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudsql/cloudsqlcreatedatabase"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudsql/cloudsqlcreateusers"
@@ -192,6 +207,7 @@ import (
 	_ "github.com/googleapis/genai-toolbox/internal/sources/bigtable"
 	_ "github.com/googleapis/genai-toolbox/internal/sources/cassandra"
 	_ "github.com/googleapis/genai-toolbox/internal/sources/clickhouse"
+	_ "github.com/googleapis/genai-toolbox/internal/sources/cloudhealthcare"
 	_ "github.com/googleapis/genai-toolbox/internal/sources/cloudmonitoring"
 	_ "github.com/googleapis/genai-toolbox/internal/sources/cloudsqladmin"
 	_ "github.com/googleapis/genai-toolbox/internal/sources/cloudsqlmssql"

cmd/root_test.go

@@ -1256,6 +1256,7 @@ func TestPrebuiltTools(t *testing.T) {
 	cloudsqlmysqlobsvconfig, _ := prebuiltconfigs.Get("cloud-sql-mysql-observability")
 	cloudsqlmssqlobsvconfig, _ := prebuiltconfigs.Get("cloud-sql-mssql-observability")
 	serverless_spark_config, _ := prebuiltconfigs.Get("serverless-spark")
+	cloudhealthcare_config, _ := prebuiltconfigs.Get("cloud-healthcare")
 
 	// Set environment variables
 	t.Setenv("API_KEY", "your_api_key")
@@ -1349,6 +1350,10 @@ func TestPrebuiltTools(t *testing.T) {
 	t.Setenv("NEO4J_USERNAME", "your_neo4j_user")
 	t.Setenv("NEO4J_PASSWORD", "your_neo4j_password")
 
+	t.Setenv("CLOUD_HEALTHCARE_PROJECT", "your_gcp_project_id")
+	t.Setenv("CLOUD_HEALTHCARE_REGION", "your_gcp_region")
+	t.Setenv("CLOUD_HEALTHCARE_DATASET", "your_healthcare_dataset")
+
 	ctx, err := testutils.ContextWithNewLogger()
 	if err != nil {
 		t.Fatalf("unexpected error: %s", err)
@@ -1628,6 +1633,24 @@ func TestPrebuiltTools(t *testing.T) {
 				},
 			},
 		},
+		{
+			name: "cloud healthcare prebuilt tools",
+			in:   cloudhealthcare_config,
+			wantToolset: server.ToolsetConfigs{
+				"cloud_healthcare_dataset_tools": tools.ToolsetConfig{
+					Name:      "cloud_healthcare_dataset_tools",
+					ToolNames: []string{"get_dataset", "list_dicom_stores", "list_fhir_stores"},
+				},
+				"cloud_healthcare_fhir_tools": tools.ToolsetConfig{
+					Name:      "cloud_healthcare_fhir_tools",
+					ToolNames: []string{"get_fhir_store", "get_fhir_store_metrics", "get_fhir_resource", "fhir_patient_search", "fhir_patient_everything", "fhir_fetch_page"},
+				},
+				"cloud_healthcare_dicom_tools": tools.ToolsetConfig{
+					Name:      "cloud_healthcare_dicom_tools",
+					ToolNames: []string{"get_dicom_store", "get_dicom_store_metrics", "search_dicom_studies", "search_dicom_series", "search_dicom_instances", "retrieve_rendered_dicom_instance"},
+				},
+			},
+		},
 	}
 
 	for _, tc := range tcs {

docs/en/reference/prebuilt-tools.md

@@ -590,3 +590,33 @@ details on how to connect your AI tools (IDEs) to databases via Toolbox and MCP.
 *   **Tools:**
     *   `execute_cypher`: Executes a Cypher query.
     *   `get_schema`: Retrieves the schema of the Neo4j database.
+
+## Google Cloud Healthcare API
+*   `--prebuilt` value: `cloud-healthcare`
+*   **Environment Variables:**
+    *   `CLOUD_HEALTHCARE_PROJECT`: The GCP project ID.
+    *   `CLOUD_HEALTHCARE_REGION`: The Cloud Healthcare API dataset region.
+    *   `CLOUD_HEALTHCARE_DATASET`: The Cloud Healthcare API dataset ID.
+    *   `CLOUD_HEALTHCARE_USE_CLIENT_OAUTH`: (Optional) If `true`, forwards the client's
+        OAuth access token for authentication. Defaults to `false`.
+*   **Permissions:**
+    *   **Healthcare FHIR Resource Reader** (`roles/healthcare.fhirResourceReader`) to read an
+        search FHIR resources.
+    *   **Healthcare DICOM Viewer** (`roles/healthcare.dicomViewer`) to retrieve DICOM images from a
+        DICOM store.
+*   **Tools:**
+    *   `get_dataset`: Gets information about a Cloud Healthcare API dataset.
+    *   `list_dicom_stores`: Lists DICOM stores in a Cloud Healthcare API dataset.
+    *   `list_fhir_stores`: Lists FHIR stores in a Cloud Healthcare API dataset.
+    *   `get_fhir_store`: Gets information about a FHIR store.
+    *   `get_fhir_store_metrics`: Gets metrics for a FHIR store.
+    *   `get_fhir_resource`: Gets a FHIR resource from a FHIR store.
+    *   `fhir_patient_search`: Searches for patient resource(s) based on a set of criteria.
+    *   `fhir_patient_everything`: Retrieves resources related to a given patient.
+    *   `fhir_fetch_page`: Fetches a page of FHIR resources.
+    *   `get_dicom_store`: Gets information about a DICOM store.
+    *   `get_dicom_store_metrics`: Gets metrics for a DICOM store.
+    *   `search_dicom_studies`: Searches for DICOM studies.
+    *   `search_dicom_series`: Searches for DICOM series.
+    *   `search_dicom_instances`: Searches for DICOM instances.
+    *   `retrieve_rendered_dicom_instance`: Retrieves a rendered DICOM instance.

docs/en/resources/sources/cloud-healthcare.md

@@ -0,0 +1,164 @@
+---
+title: "Cloud Healthcare API"
+linkTitle: "Cloud Healthcare"
+type: docs
+weight: 1
+description: >
+  The Cloud Healthcare API provides a managed solution for storing and
+  accessing healthcare data in Google Cloud, providing a critical bridge 
+  between existing care systems and applications hosted on Google Cloud.
+---
+
+## About
+
+The [Cloud Healthcare API][healthcare-docs] provides a managed solution
+for storing and accessing healthcare data in Google Cloud, providing a
+critical bridge between existing care systems and applications hosted on
+Google Cloud. It supports healthcare data standards such as HL7® FHIR®,
+HL7® v2, and DICOM®. It provides a fully managed, highly scalable,
+enterprise-grade development environment for building clinical and analytics
+solutions securely on Google Cloud.
+
+A dataset is a container in your Google Cloud project that holds modality-specific
+healthcare data. Datasets contain other data stores, such as FHIR stores and DICOM
+stores, which in turn hold their own types of healthcare data.
+
+A single dataset can contain one or many data stores, and those stores can all service
+the same modality or different modalities as application needs dictate. Using multiple
+stores in the same dataset might be appropriate in various situations.
+
+If you are new to the Cloud Healthcare API, you can try to
+[create and view datasets and stores using curl][healthcare-quickstart-curl].
+
+[healthcare-docs]: https://cloud.google.com/healthcare/docs
+[healthcare-quickstart-curl]:
+    https://cloud.google.com/healthcare-api/docs/store-healthcare-data-rest
+
+## Available Tools
+
+- [`cloud-healthcare-get-dataset`](../tools/cloudhealthcare/cloud-healthcare-get-dataset.md)
+  Retrieves a dataset’s details.
+
+- [`cloud-healthcare-list-fhir-stores`](../tools/cloudhealthcare/cloud-healthcare-list-fhir-stores.md)
+  Lists the available FHIR stores in the healthcare dataset.
+
+- [`cloud-healthcare-list-dicom-stores`](../tools/cloudhealthcare/cloud-healthcare-list-dicom-stores.md)
+  Lists the available DICOM stores in the healthcare dataset.
+
+- [`cloud-healthcare-get-fhir-store`](../tools/cloudhealthcare/cloud-healthcare-get-fhir-store.md)
+  Retrieves information about a FHIR store.
+
+- [`cloud-healthcare-get-fhir-store-metrics`](../tools/cloudhealthcare/cloud-healthcare-get-fhir-store-metrics.md)
+  Retrieves metrics for a FHIR store.
+
+- [`cloud-healthcare-get-fhir-resource`](../tools/cloudhealthcare/cloud-healthcare-get-fhir-resource.md)
+  Retrieves a specific FHIR resource from a FHIR store.
+
+- [`cloud-healthcare-fhir-patient-search`](../tools/cloudhealthcare/cloud-healthcare-fhir-patient-search.md)
+  Searches for patients in a FHIR store based on a set of criteria.
+
+- [`cloud-healthcare-fhir-patient-everything`](../tools/cloudhealthcare/cloud-healthcare-fhir-patient-everything.md)
+  Retrieves all information for a given patient.
+
+- [`cloud-healthcare-fhir-fetch-page`](../tools/cloudhealthcare/cloud-healthcare-fhir-fetch-page.md)
+  Fetches a page of FHIR resources from a given URL.
+
+- [`cloud-healthcare-get-dicom-store`](../tools/cloudhealthcare/cloud-healthcare-get-dicom-store.md)
+  Retrieves information about a DICOM store.
+
+- [`cloud-healthcare-get-dicom-store-metrics`](../tools/cloudhealthcare/cloud-healthcare-get-dicom-store-metrics.md)
+  Retrieves metrics for a DICOM store.
+
+- [`cloud-healthcare-search-dicom-studies`](../tools/cloudhealthcare/cloud-healthcare-search-dicom-studies.md)
+  Searches for DICOM studies in a DICOM store.
+
+- [`cloud-healthcare-search-dicom-series`](../tools/cloudhealthcare/cloud-healthcare-search-dicom-series.md)
+  Searches for DICOM series in a DICOM store.
+
+- [`cloud-healthcare-search-dicom-instances`](../tools/cloudhealthcare/cloud-healthcare-search-dicom-instances.md)
+  Searches for DICOM instances in a DICOM store.
+
+- [`cloud-healthcare-retrieve-rendered-dicom-instance`](../tools/cloudhealthcare/cloud-healthcare-retrieve-rendered-dicom-instance.md)
+  Retrieves a rendered DICOM instance from a DICOM store.
+
+## Requirements
+
+### IAM Permissions
+
+The Cloud Healthcare API uses [Identity and Access Management (IAM)][iam-overview] to control
+user and group access to Cloud Healthcare resources like projects, datasets, and stores.
+
+### Authentication via Application Default Credentials (ADC)
+
+By **default**, Toolbox will use your [Application Default Credentials
+(ADC)][adc] to authorize and authenticate when interacting with the
+[Cloud Healthcare API][healthcare-docs].
+
+When using this method, you need to ensure the IAM identity associated with your
+ADC (such as a service account) has the correct permissions for the queries you
+intend to run. Common roles include `roles/healthcare.fhirResourceReader` (which includes
+permissions to read and search for FHIR resources) or `roles/healthcare.dicomViewer` (for
+retrieving DICOM images).
+Follow this [guide][set-adc] to set up your ADC.
+
+### Authentication via User's OAuth Access Token
+
+If the `useClientOAuth` parameter is set to `true`, Toolbox will instead use the
+OAuth access token for authentication. This token is parsed from the
+`Authorization` header passed in with the tool invocation request. This method
+allows Toolbox to make queries to the [Cloud Healthcare API][healthcare-docs] on behalf of the
+client or the end-user.
+
+When using this on-behalf-of authentication, you must ensure that the
+identity used has been granted the correct IAM permissions.
+
+[iam-overview]: <https://cloud.google.com/healthcare/docs/access-control>
+[adc]: <https://cloud.google.com/docs/authentication#adc>
+[set-adc]: <https://cloud.google.com/docs/authentication/provide-credentials-adc>
+
+## Example
+
+Initialize a Cloud Healthcare API source that uses ADC:
+
+```yaml
+sources:
+  my-healthcare-source:
+    kind: "cloud-healthcare"
+    project: "my-project-id"
+    region: "us-central1"
+    dataset: "my-healthcare-dataset-id"
+    # allowedFhirStores: # Optional: Restricts tool access to a specific list of FHIR store IDs.
+    #   - "my_fhir_store_1"
+    # allowedDicomStores: # Optional: Restricts tool access to a specific list of DICOM store IDs.
+    #   - "my_dicom_store_1"
+    #   - "my_dicom_store_2"
+```
+
+Initialize a Cloud Healthcare API source that uses the client's access token:
+
+```yaml
+sources:
+  my-healthcare-client-auth-source:
+    kind: "cloud-healthcare"
+    project: "my-project-id"
+    region: "us-central1"
+    dataset: "my-healthcare-dataset-id"
+    useClientOAuth: true
+    # allowedFhirStores: # Optional: Restricts tool access to a specific list of FHIR store IDs.
+    #   - "my_fhir_store_1"
+    # allowedDicomStores: # Optional: Restricts tool access to a specific list of DICOM store IDs.
+    #   - "my_dicom_store_1"
+    #   - "my_dicom_store_2"
+```
+
+## Reference
+
+| **field**          | **type** | **required** | **description**                                                                                                                                                                                                                                                              |
+|--------------------|:--------:|:------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| kind               |  string  |     true     | Must be "cloud-healthcare".                                                                                                                                                                                                                                                  |
+| project            |  string  |     true     | ID of the GCP project that the dataset lives in.                                                                                                                                                                                                                             |
+| region             |  string  |     true     | Specifies the region (e.g., 'us', 'asia-northeast1') of the healthcare dataset. [Learn More](https://cloud.google.com/healthcare-api/docs/regions)                                                                                                                           |
+| dataset            |  string  |     true     | ID of the healthcare dataset.                                                                                                                                                                                                                                                |
+| allowedFhirStores  | []string |    false     | An optional list of FHIR store IDs that tools using this source are allowed to access. If provided, any tool operation attempting to access a store not in this list will be rejected. If a single store is provided, it will be treated as the default for prebuilt tools.  |
+| allowedDicomStores | []string |    false     | An optional list of DICOM store IDs that tools using this source are allowed to access. If provided, any tool operation attempting to access a store not in this list will be rejected. If a single store is provided, it will be treated as the default for prebuilt tools. |
+| useClientOAuth     |   bool   |    false     | If true, forwards the client's OAuth access token from the "Authorization" header to downstream queries.                                                                                                                                                                     |

docs/en/resources/tools/cloudhealthcare/_index.md

@@ -0,0 +1,8 @@
+---
+title: "Cloud Healthcare API"
+linkTitle: "Cloud Healthcare"
+type: docs
+weight: 1
+description: > 
+  Tools that work with Cloud Healthcare Sources.
+---

docs/en/resources/tools/cloudhealthcare/cloud-healthcare-fhir-fetch-page.md

@@ -0,0 +1,43 @@
+---
+title: "cloud-healthcare-fhir-fetch-page"
+type: docs
+weight: 1
+description: >
+  A "cloud-healthcare-fhir-fetch-page" tool fetches a page of FHIR resources from a given URL.
+aliases:
+- /resources/tools/cloud-healthcare-fhir-fetch-page
+---
+
+## About
+
+A `cloud-healthcare-fhir-fetch-page` tool fetches a page of FHIR resources from a given URL. It's
+compatible with the following sources:
+
+- [cloud-healthcare](../../sources/cloud-healthcare.md)
+
+`cloud-healthcare-fhir-fetch-page` can be used for pagination when a previous tool call (like
+`cloud-healthcare-fhir-patient-search` or `cloud-healthcare-fhir-patient-everything`) returns a 'next' link in the response bundle.
+
+## Example
+
+```yaml
+tools:
+  get_fhir_store:
+    kind: cloud-healthcare-fhir-fetch-page
+    source: my-healthcare-source
+    description: Use this tool to fetch a page of FHIR resources from a FHIR Bundle's entry.link.url
+```
+
+## Reference
+
+| **field**   | **type** | **required** | **description**                                    |
+|-------------|:--------:|:------------:|----------------------------------------------------|
+| kind        |  string  |     true     | Must be "cloud-healthcare-fhir-fetch-page".        |
+| source      |  string  |     true     | Name of the healthcare source.                     |
+| description |  string  |     true     | Description of the tool that is passed to the LLM. |
+
+### Parameters
+
+| **field** | **type** | **required** | **description**                                                                                                                                                                               |
+|-----------|:--------:|:------------:|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| pageURL   |  string  |     true     | The full URL of the FHIR page to fetch. This would usually be the value of `Bundle.entry.link.url` field within the response returned from FHIR search or FHIR patient everything operations. |