Skip to content

feat(tools/healthcare): Add healthcare dataset tools #1671

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Yuan325 merged 3 commits into from
Oct 20, 2025
Merged

feat(tools/healthcare): Add healthcare dataset tools #1671

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4fd76ef
feat(sources/healthcare): add a new healthcare source
Quarz0 Oct 8, 2025
f15be3e
Apply suggestions from code review#1
Quarz0 Oct 9, 2025
fc0a1de
feat(tools/healthcare): Add healthcare dataset tools
Quarz0 Oct 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions .ci/integration.cloudbuild.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,28 @@ steps:
dataform \
dataform

- id: "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"
secretEnv: ["CLIENT_ID"]
volumes:
- name: "go"
path: "/gopath"
args:
- -c
- |
.ci/test_with_coverage.sh \
"Healthcare" \
healthcare \
healthcare

- id: "postgres"
name: golang:1
waitFor: ["compile-test-binary"]
Expand Down Expand Up @@ -813,6 +835,7 @@ 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"
_POSTGRES_HOST: 127.0.0.1
_POSTGRES_PORT: "5432"
_SPANNER_INSTANCE: "spanner-testing"
Expand Down
4 changes: 4 additions & 0 deletions cmd/root.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,9 @@ import (
_ "github.com/googleapis/genai-toolbox/internal/tools/firestore/firestorequerycollection"
_ "github.com/googleapis/genai-toolbox/internal/tools/firestore/firestoreupdatedocument"
_ "github.com/googleapis/genai-toolbox/internal/tools/firestore/firestorevalidaterules"
_ "github.com/googleapis/genai-toolbox/internal/tools/healthcare/gethealthcaredataset"
_ "github.com/googleapis/genai-toolbox/internal/tools/healthcare/listdicomstores"
_ "github.com/googleapis/genai-toolbox/internal/tools/healthcare/listfhirstores"
_ "github.com/googleapis/genai-toolbox/internal/tools/http"
_ "github.com/googleapis/genai-toolbox/internal/tools/looker/lookeradddashboardelement"
_ "github.com/googleapis/genai-toolbox/internal/tools/looker/lookerconversationalanalytics"
Expand Down Expand Up @@ -177,6 +180,7 @@ import (
_ "github.com/googleapis/genai-toolbox/internal/sources/dgraph"
_ "github.com/googleapis/genai-toolbox/internal/sources/firebird"
_ "github.com/googleapis/genai-toolbox/internal/sources/firestore"
_ "github.com/googleapis/genai-toolbox/internal/sources/healthcare"
_ "github.com/googleapis/genai-toolbox/internal/sources/http"
_ "github.com/googleapis/genai-toolbox/internal/sources/looker"
_ "github.com/googleapis/genai-toolbox/internal/sources/mongodb"
Expand Down
128 changes: 128 additions & 0 deletions docs/en/resources/sources/healthcare.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
---
title: "Cloud Healthcare API"
linkTitle: "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 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

- [`get-healthcare-dataset`](../tools/healthcare/get-healthcare-dataset.md)
Retrieves a dataset’s details.

- [`list-fhir-stores`](../tools/healthcare/list-fhir-stores.md)
Lists the available FHIR stores in the healthcare dataset.

- [`list-dicom-stores`](../tools/healthcare/list-dicom-stores.md)
Lists the available DICOM stores in the healthcare dataset.

## Requirements

### IAM Permissions

The Healthcare API uses [Identity and Access Management (IAM)][iam-overview] to control
user and group access to 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
[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 [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 Healthcare source that uses ADC:

```yaml
sources:
my-healthcare-source:
kind: "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 Healthcare source that uses the client's access token:

```yaml
sources:
my-healthcare-client-auth-source:
kind: "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 "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. |
8 changes: 8 additions & 0 deletions docs/en/resources/tools/healthcare/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: "Cloud Healthcare API"
linkTitle: "Healthcare"
type: docs
weight: 1
description: >
Tools that work with Healthcare Sources.
---
38 changes: 38 additions & 0 deletions docs/en/resources/tools/healthcare/get-healthcare-dataset.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
title: "get-healthcare-dataset"
linkTitle: "get-healthcare-dataset"
type: docs
weight: 1
description: >
A "get-healthcare-dataset" tool retrieves metadata for the Healthcare dataset in the source.
aliases:
- /resources/tools/healthcare-get-healthcare-dataset
---

## About

A `get-healthcare-dataset` tool retrieves metadata for a Healthcare dataset.
It's compatible with the following sources:

- [healthcare](../../sources/healthcare.md)

`get-healthcare-dataset` returns the metadata of the healthcare dataset
configured in the source. It takes no extra parameters.

## Example

```yaml
tools:
get_healthcare_dataset:
kind: get-healthcare-dataset
source: my-healthcare-source
description: Use this tool to get healthcare dataset metadata.
```

## Reference

| **field** | **type** | **required** | **description** |
|-------------|:------------------------------------------:|:------------:|----------------------------------------------------|
| kind | string | true | Must be "get-healthcare-dataset". |
| source | string | true | Name of the healthcare source. |
| description | string | true | Description of the tool that is passed to the LLM. |
38 changes: 38 additions & 0 deletions docs/en/resources/tools/healthcare/list-dicom-stores.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
title: "list-dicom-stores"
linkTitle: "list-dicom-stores"
type: docs
weight: 1
description: >
A "list-dicom-stores" lists the available DICOM stores in the healthcare dataset.
aliases:
- /resources/tools/healthcare-list-dicom-stores
---

## About

A `list-dicom-stores` lists the available DICOM stores in the healthcare dataset.
It's compatible with the following sources:

- [healthcare](../../sources/healthcare.md)

`list-dicom-stores` returns the details of the available DICOM stores in the
dataset of the healthcare source. It takes no extra parameters.

## Example

```yaml
tools:
list_dicom_stores:
kind: list-dicom-stores
source: my-healthcare-source
description: Use this tool to list DICOM stores in the healthcare dataset.
```

## Reference

| **field** | **type** | **required** | **description** |
|-------------|:------------------------------------------:|:------------:|----------------------------------------------------|
| kind | string | true | Must be "list-dicom-stores". |
| source | string | true | Name of the healthcare source. |
| description | string | true | Description of the tool that is passed to the LLM. |
38 changes: 38 additions & 0 deletions docs/en/resources/tools/healthcare/list-fhir-stores.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
title: "list-fhir-stores"
linkTitle: "list-fhir-stores"
type: docs
weight: 1
description: >
A "list-fhir-stores" lists the available FHIR stores in the healthcare dataset.
aliases:
- /resources/tools/healthcare-list-fhir-stores
---

## About

A `list-fhir-stores` lists the available FHIR stores in the healthcare dataset.
It's compatible with the following sources:

- [healthcare](../../sources/healthcare.md)

`list-fhir-stores` returns the details of the available FHIR stores in the
dataset of the healthcare source. It takes no extra parameters.

## Example

```yaml
tools:
list_fhir_stores:
kind: list-fhir-stores
source: my-healthcare-source
description: Use this tool to list FHIR stores in the healthcare dataset.
```

## Reference

| **field** | **type** | **required** | **description** |
|-------------|:------------------------------------------:|:------------:|----------------------------------------------------|
| kind | string | true | Must be "list-fhir-stores". |
| source | string | true | Name of the healthcare source. |
| description | string | true | Description of the tool that is passed to the LLM. |
Loading
Loading