github/genai-toolbox
1
0
Fork 0
mirror of https://github.com/googleapis/genai-toolbox.git synced 2026-01-12 08:58:28 -05:00
Code Issues Packages Projects Releases 14 Wiki Activity

feat(tools/alloydb-list-instances): Add custom tool kind for AlloyDB list_instances (#1357)

Browse Source 
## Description

---
This pull request introduces a new custom tool kind
`alloydb-list-instances` that allows users to list the AlloyDB instances
in a given project, cluster and location.

### Example Configuration

```yaml
tools:
  list_instances:
    kind: alloydb-list-instances
    source: alloydb-admin-source
    description: Use this tool to list all AlloyDB instances for a given project, cluster and location.
```

### Example Request
``` 
curl -X POST http://127.0.0.1:5000/api/tool/list_instances/invoke \
-H "Content-Type: application/json" \
-d '{
    "projectId": "example-project",
    "locationId": "us-central1",
    "clusterId": "example-cluster",
}'
```

## PR Checklist

---
> Thank you for opening a Pull Request! Before submitting your PR, there
are a
> few things you can do to make sure it goes smoothly:

- [x] Make sure you reviewed

[CONTRIBUTING.md](https://github.com/googleapis/genai-toolbox/blob/main/CONTRIBUTING.md)
- [ ] Make sure to open an issue as a

[bug/issue](https://github.com/googleapis/genai-toolbox/issues/new/choose)
before writing your code! That way we can discuss the change, evaluate
  designs, and agree on the general idea
- [x] Ensure the tests and linter pass
- [x] Code coverage does not decrease (if any source code was changed)
- [x] Appropriate docs were updated (if necessary)
- [x] Make sure to add `!` if this involve a breaking change

🛠️ Fixes #<issue_number_goes_here>
This commit is contained in:
Sri Varshitha
2025-09-12 15:08:23 +05:30
committed by GitHub
parent 3a8a65ceaa
commit 93c1b30fce
8 changed files with 448 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.ci/integration.cloudbuild.yaml
View File

@@ -70,6 +70,7 @@ steps:
- "GOPATH=/gopath"
- "ALLOYDB_PROJECT=$PROJECT_ID"
- "ALLOYDB_CLUSTER=$_ALLOYDB_POSTGRES_CLUSTER"
- "ALLOYDB_INSTANCE=$_ALLOYDB_POSTGRES_INSTANCE"
- "ALLOYDB_REGION=$_REGION"
secretEnv: ["ALLOYDB_POSTGRES_USER"]
volumes:

1
cmd/root.go
View File

@@ -44,6 +44,7 @@ import (
// Import tool packages for side effect of registration
_ "github.com/googleapis/genai-toolbox/internal/tools/alloydbainl"
_ "github.com/googleapis/genai-toolbox/internal/tools/alloydb/alloydblistclusters"
_ "github.com/googleapis/genai-toolbox/internal/tools/alloydb/alloydblistinstances"
_ "github.com/googleapis/genai-toolbox/internal/tools/alloydb/alloydblistusers"
_ "github.com/googleapis/genai-toolbox/internal/tools/bigquery/bigqueryanalyzecontribution"
_ "github.com/googleapis/genai-toolbox/internal/tools/bigquery/bigqueryconversationalanalytics"

2
cmd/root_test.go
View File

@@ -1339,7 +1339,7 @@ func TestPrebuiltTools(t *testing.T) {
wantToolset: server.ToolsetConfigs{
"alloydb-postgres-admin-tools": tools.ToolsetConfig{
Name: "alloydb-postgres-admin-tools",
ToolNames: []string{"alloydb-create-cluster", "alloydb-operations-get", "alloydb-create-instance", "list_clusters", "alloydb-list-instances", "list_users", "alloydb-create-user"},
ToolNames: []string{"alloydb-create-cluster", "alloydb-operations-get", "alloydb-create-instance", "list_clusters", "list_instances", "list_users", "alloydb-create-user"},
},
},
},

39
docs/en/resources/tools/alloydb/alloydb-list-instances.md Normal file
View File

@@ -0,0 +1,39 @@
---
title: "alloydb-list-instances"
type: docs
weight: 1
description: >
The "alloydb-list-instances" tool lists the AlloyDB instances for a given project, cluster and location.
aliases:
- /resources/tools/alloydb-list-instances
---
## About
The `alloydb-list-instances` tool retrieves AlloyDB instance information for all or specified clusters and locations in a given project. It is compatible with [alloydb-admin](../../sources/alloydb-admin.md) source.
`alloydb-list-instances` tool lists the detailed information of AlloyDB instances (instance name, type, IP address, state, configuration, etc) for a given project, cluster and location. The tool takes the following input parameters:
| Parameter | Type | Description | Required |
| :--------- | :----- | :--------------------------------------------------------------------------------------- | :------- |
| `projectId` | string | The GCP project ID to list instances for. | Yes |
| `clusterId` | string | The ID of the cluster to list instances from. Use '-' to get results for all clusters. Default: `-`.| No |
| `locationId` | string | The location of the cluster (e.g., 'us-central1'). Use '-' to get results for all locations. Default: `-`.| No |
> **Note**
> This tool authenticates using the credentials configured in its [alloydb-admin](../../sources/alloydb-admin.md) source which can be either [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials) or client-side OAuth.
## Example
```yaml
tools:
list_instances:
kind: alloydb-list-instances
source: alloydb-admin-source
description: Use this tool to list all AlloyDB instances for a given project, cluster and location.
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:------------------------------------------:|:------------:|--------------------------------------------------------------------------------------------------|
| kind | string | true | Must be alloydb-list-instances. | |
| source | string | true | The name of an alloydb-admin source. |
| description | string | true | Description of the tool that is passed to the agent. |

22
internal/prebuiltconfigs/tools/alloydb-postgres-admin.yaml
View File

@@ -134,24 +134,10 @@ tools:
kind: alloydb-list-clusters
source: alloydb-admin-source
description: "Lists all AlloyDB clusters in a given project and location."
alloydb-list-instances:
kind: http
source: alloydb-api-source
method: GET
path: /v1/projects/{{.projectId}}/locations/{{.locationId}}/clusters/{{.clusterId}}/instances
list_instances:
kind: alloydb-list-instances
source: alloydb-admin-source
description: "Lists all AlloyDB instances within a specific cluster."
pathParams:
- name: projectId
type: string
description: "The GCP project ID."
- name: locationId
type: string
description: "The location of the cluster (e.g., 'us-central1'). Use '-' to get results for all regions."
default: "-"
- name: clusterId
type: string
description: "The ID of the cluster to list instances from. Use '-' to get results for all clusters."
default: "-"
list_users:
kind: alloydb-list-users
source: alloydb-admin-source
@@ -210,6 +196,6 @@ toolsets:
- alloydb-operations-get
- alloydb-create-instance
- list_clusters
- alloydb-list-instances
- list_instances
- list_users
- alloydb-create-user

175
internal/tools/alloydb/alloydblistinstances/alloydblistinstances.go Normal file
View File

@@ -0,0 +1,175 @@
// Copyright 2025 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package alloydblistinstances
import (
"context"
"fmt"
yaml "github.com/goccy/go-yaml"
"github.com/googleapis/genai-toolbox/internal/sources"
alloydbadmin "github.com/googleapis/genai-toolbox/internal/sources/alloydbadmin"
"github.com/googleapis/genai-toolbox/internal/tools"
"google.golang.org/api/alloydb/v1"
"google.golang.org/api/option"
)
const kind string = "alloydb-list-instances"
func init() {
if !tools.Register(kind, newConfig) {
panic(fmt.Sprintf("tool kind %q already registered", kind))
}
}
func newConfig(ctx context.Context, name string, decoder *yaml.Decoder) (tools.ToolConfig, error) {
actual := Config{Name: name}
if err := decoder.DecodeContext(ctx, &actual); err != nil {
return nil, err
}
return actual, nil
}
// Configuration for the list-instances tool.
type Config struct {
Name string `yaml:"name" validate:"required"`
Kind string `yaml:"kind" validate:"required"`
Source string `yaml:"source" validate:"required"`
Description string `yaml:"description" validate:"required"`
AuthRequired []string `yaml:"authRequired"`
BaseURL string `yaml:"baseURL"`
}
// validate interface
var _ tools.ToolConfig = Config{}
// ToolConfigKind returns the kind of the tool.
func (cfg Config) ToolConfigKind() string {
return kind
}
// Initialize initializes the tool from the configuration.
func (cfg Config) Initialize(srcs map[string]sources.Source) (tools.Tool, error) {
rawS, ok := srcs[cfg.Source]
if !ok {
return nil, fmt.Errorf("source %q not found", cfg.Source)
}
s, ok := rawS.(*alloydbadmin.Source)
if !ok {
return nil, fmt.Errorf("invalid source for %q tool: source kind must be `%s`", kind, alloydbadmin.SourceKind)
}
allParameters := tools.Parameters{
tools.NewStringParameter("projectId", "The GCP project ID to list instances for."),
tools.NewStringParameterWithDefault("locationId", "-", "Optional: The location of the cluster (e.g., 'us-central1'). Use '-' to get results for all regions.(Default: '-')"),
tools.NewStringParameterWithDefault("clusterId", "-", "Optional: The ID of the cluster to list instances from. Use '-' to get results for all clusters.(Default: '-')"),
}
paramManifest := allParameters.Manifest()
inputSchema := allParameters.McpManifest()
inputSchema.Required = []string{"projectId"}
mcpManifest := tools.McpManifest{
Name: cfg.Name,
Description: cfg.Description,
InputSchema: inputSchema,
}
return Tool{
Name: cfg.Name,
Kind: kind,
Source: s,
AllParams: allParameters,
manifest: tools.Manifest{Description: cfg.Description, Parameters: paramManifest},
mcpManifest: mcpManifest,
}, nil
}
// Tool represents the list-instances tool.
type Tool struct {
Name string `yaml:"name"`
Kind string `yaml:"kind"`
Description string `yaml:"description"`
Source *alloydbadmin.Source
AllParams tools.Parameters `yaml:"allParams"`
manifest tools.Manifest
mcpManifest tools.McpManifest
}
// Invoke executes the tool's logic.
func (t Tool) Invoke(ctx context.Context, params tools.ParamValues, accessToken tools.AccessToken) (any, error) {
paramsMap := params.AsMap()
projectId, ok := paramsMap["projectId"].(string)
if !ok {
return nil, fmt.Errorf("invalid or missing 'projectId' parameter; expected a string")
}
locationId, ok := paramsMap["locationId"].(string)
if !ok {
return nil, fmt.Errorf("invalid 'locationId' parameter; expected a string")
}
clusterId, ok := paramsMap["clusterId"].(string)
if !ok {
return nil, fmt.Errorf("invalid 'clusterId' parameter; expected a string")
}
// Get an authenticated HTTP client from the source
client, err := t.Source.GetClient(ctx, string(accessToken))
if err != nil {
return nil, fmt.Errorf("error getting authorized client: %w", err)
}
// Create a new AlloyDB service client using the authorized client
alloydbService, err := alloydb.NewService(ctx, option.WithHTTPClient(client))
if err != nil {
return nil, fmt.Errorf("error creating AlloyDB service: %w", err)
}
urlString := fmt.Sprintf("projects/%s/locations/%s/clusters/%s", projectId, locationId, clusterId)
resp, err := alloydbService.Projects.Locations.Clusters.Instances.List(urlString).Do()
if err != nil {
return nil, fmt.Errorf("error listing AlloyDB instances: %w", err)
}
return resp, nil
}
// ParseParams parses the parameters for the tool.
func (t Tool) ParseParams(data map[string]any, claims map[string]map[string]any) (tools.ParamValues, error) {
return tools.ParseParams(t.AllParams, data, claims)
}
// Manifest returns the tool's manifest.
func (t Tool) Manifest() tools.Manifest {
return t.manifest
}
// McpManifest returns the tool's MCP manifest.
func (t Tool) McpManifest() tools.McpManifest {
return t.mcpManifest
}
// Authorized checks if the tool is authorized.
func (t Tool) Authorized(verifiedAuthServices []string) bool {
return true
}
func (t Tool) RequiresClientAuthorization() bool {
return t.Source.UseClientAuthorization()
}

94
internal/tools/alloydb/alloydblistinstances/alloydblistinstances_test.go Normal file
View File

@@ -0,0 +1,94 @@
// Copyright 2025 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package alloydblistinstances_test
import (
"testing"
yaml "github.com/goccy/go-yaml"
"github.com/google/go-cmp/cmp"
"github.com/googleapis/genai-toolbox/internal/server"
"github.com/googleapis/genai-toolbox/internal/testutils"
alloydblistinstances "github.com/googleapis/genai-toolbox/internal/tools/alloydb/alloydblistinstances"
)
func TestParseFromYaml(t *testing.T) {
ctx, err := testutils.ContextWithNewLogger()
if err != nil {
t.Fatalf("unexpected error: %s", err)
}
tcs := []struct {
desc string
in string
want server.ToolConfigs
}{
{
desc: "basic example",
in: `
tools:
list-my-instances:
kind: alloydb-list-instances
source: my-alloydb-admin-source
description: some description
`,
want: server.ToolConfigs{
"list-my-instances": alloydblistinstances.Config{
Name: "list-my-instances",
Kind: "alloydb-list-instances",
Source: "my-alloydb-admin-source",
Description: "some description",
AuthRequired: []string{},
},
},
},
{
desc: "with auth required",
in: `
tools:
list-my-instances-auth:
kind: alloydb-list-instances
source: my-alloydb-admin-source
description: some description
authRequired:
- my-google-auth-service
- other-auth-service
`,
want: server.ToolConfigs{
"list-my-instances-auth": alloydblistinstances.Config{
Name: "list-my-instances-auth",
Kind: "alloydb-list-instances",
Source: "my-alloydb-admin-source",
Description: "some description",
AuthRequired: []string{"my-google-auth-service", "other-auth-service"},
},
},
},
}
for _, tc := range tcs {
t.Run(tc.desc, func(t *testing.T) {
got := struct {
Tools server.ToolConfigs `yaml:"tools"`
}{}
// Parse contents
err := yaml.UnmarshalContext(ctx, testutils.FormatYaml(tc.in), &got)
if err != nil {
t.Fatalf("unable to unmarshal: %s", err)
}
if diff := cmp.Diff(tc.want, got.Tools); diff != "" {
t.Fatalf("incorrect parse: diff %v", diff)
}
})
}
}

133
tests/alloydb/alloydb_integration_test.go
View File

@@ -39,6 +39,7 @@ var (
AlloyDBProject = os.Getenv("ALLOYDB_PROJECT")
AlloyDBLocation = os.Getenv("ALLOYDB_REGION")
AlloyDBCluster = os.Getenv("ALLOYDB_CLUSTER")
AlloyDBInstance = os.Getenv("ALLOYDB_INSTANCE")
AlloyDBUser = os.Getenv("ALLOYDB_POSTGRES_USER")
)
@@ -52,6 +53,9 @@ func getAlloyDBVars(t *testing.T) map[string]string {
if AlloyDBCluster == "" {
t.Fatal("'ALLOYDB_CLUSTER' not set")
}
if AlloyDBInstance == "" {
t.Fatal("'ALLOYDB_INSTANCE' not set")
}
if AlloyDBUser == "" {
t.Fatal("'ALLOYDB_USER' not set")
}
@@ -59,6 +63,7 @@ func getAlloyDBVars(t *testing.T) map[string]string {
"projectId": AlloyDBProject,
"locationId": AlloyDBLocation,
"clusterId": AlloyDBCluster,
"instanceId": AlloyDBInstance,
"user": AlloyDBUser,
}
}
@@ -100,6 +105,11 @@ func getAlloyDBToolsConfig() map[string]any {
"source": "alloydb-admin-source",
"description": "Lists all AlloyDB users within a specific cluster.",
},
"alloydb-list-instances": map[string]any{
"kind": "alloydb-list-instances",
"source": "alloydb-admin-source",
"description": "Lists all AlloyDB instances within a specific cluster.",
},
},
}
}
@@ -132,6 +142,7 @@ func TestAlloyDBToolEndpoints(t *testing.T) {
// Run tool-specific invoke tests
runAlloyDBListClustersTest(t, vars)
runAlloyDBListUsersTest(t, vars)
runAlloyDBListInstancesTest(t, vars)
}
func runAlloyDBToolGetTest(t *testing.T) {
@@ -540,3 +551,125 @@ func runAlloyDBListUsersTest(t *testing.T, vars map[string]string) {
})
}
}
func runAlloyDBListInstancesTest(t *testing.T, vars map[string]string) {
type ListInstancesResponse struct {
Instances []struct {
Name string `json:"name"`
} `json:"instances"`
}
type ToolResponse struct {
Result string `json:"result"`
}
wantForSpecificClusterAndLocation := []string{
fmt.Sprintf("projects/%s/locations/%s/clusters/%s/instances/%s", vars["projectId"], vars["locationId"], vars["clusterId"], vars["instanceId"]),
}
// NOTE: If clusters or instances are added, removed or changed in the test project,
// the below lists must be updated for the tests to pass.
wantForAllClustersSpecificLocation := []string{
fmt.Sprintf("projects/%s/locations/%s/clusters/alloydb-ai-nl-testing/instances/alloydb-ai-nl-testing-instance", vars["projectId"], vars["locationId"]),
fmt.Sprintf("projects/%s/locations/%s/clusters/alloydb-pg-testing/instances/alloydb-pg-testing-instance", vars["projectId"], vars["locationId"]),
}
wantForAllClustersAllLocations := []string{
fmt.Sprintf("projects/%s/locations/us-central1/clusters/alloydb-ai-nl-testing/instances/alloydb-ai-nl-testing-instance", vars["projectId"]),
fmt.Sprintf("projects/%s/locations/us-central1/clusters/alloydb-pg-testing/instances/alloydb-pg-testing-instance", vars["projectId"]),
fmt.Sprintf("projects/%s/locations/us-east4/clusters/alloydb-private-pg-testing/instances/alloydb-private-pg-testing-instance", vars["projectId"]),
fmt.Sprintf("projects/%s/locations/us-east4/clusters/colab-testing/instances/colab-testing-primary", vars["projectId"]),
}
invokeTcs := []struct {
name string
requestBody io.Reader
want []string
wantStatusCode int
}{
{
name: "list instances for a specific cluster and location",
requestBody: bytes.NewBufferString(fmt.Sprintf(`{"projectId": "%s", "locationId": "%s", "clusterId": "%s"}`, vars["projectId"], vars["locationId"], vars["clusterId"])),
want: wantForSpecificClusterAndLocation,
wantStatusCode: http.StatusOK,
},
{
name: "list instances for all clusters and specific location",
requestBody: bytes.NewBufferString(fmt.Sprintf(`{"projectId": "%s", "locationId": "%s", "clusterId": "-"}`, vars["projectId"], vars["locationId"])),
want: wantForAllClustersSpecificLocation,
wantStatusCode: http.StatusOK,
},
{
name: "list instances for all clusters and all locations",
requestBody: bytes.NewBufferString(fmt.Sprintf(`{"projectId": "%s", "locationId": "-", "clusterId": "-"}`, vars["projectId"])),
want: wantForAllClustersAllLocations,
wantStatusCode: http.StatusOK,
},
{
name: "list instances missing project",
requestBody: bytes.NewBufferString(fmt.Sprintf(`{"locationId": "%s", "clusterId": "%s"}`, vars["locationId"], vars["clusterId"])),
wantStatusCode: http.StatusBadRequest,
},
{
name: "list instances non-existent project",
requestBody: bytes.NewBufferString(fmt.Sprintf(`{"projectId": "non-existent-project", "locationId": "%s", "clusterId": "%s"}`, vars["locationId"], vars["clusterId"])),
wantStatusCode: http.StatusInternalServerError,
},
{
name: "list instances non-existent location",
requestBody: bytes.NewBufferString(fmt.Sprintf(`{"projectId": "%s", "locationId": "non-existent-location", "clusterId": "%s"}`, vars["projectId"], vars["clusterId"])),
wantStatusCode: http.StatusInternalServerError,
},
{
name: "list instances non-existent cluster",
requestBody: bytes.NewBufferString(fmt.Sprintf(`{"projectId": "%s", "locationId": "%s", "clusterId": "non-existent-cluster"}`, vars["projectId"], vars["locationId"])),
wantStatusCode: http.StatusBadRequest,
},
}
for _, tc := range invokeTcs {
t.Run(tc.name, func(t *testing.T) {
api := "http://127.0.0.1:5000/api/tool/alloydb-list-instances/invoke"
req, err := http.NewRequest(http.MethodPost, api, tc.requestBody)
if err != nil {
t.Fatalf("unable to create request: %s", err)
}
req.Header.Add("Content-type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
t.Fatalf("unable to send request: %s", err)
}
defer resp.Body.Close()
if resp.StatusCode != tc.wantStatusCode {
bodyBytes, _ := io.ReadAll(resp.Body)
t.Fatalf("response status code is not %d, got %d: %s", tc.wantStatusCode, resp.StatusCode, string(bodyBytes))
}
if tc.wantStatusCode == http.StatusOK {
var body ToolResponse
if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
t.Fatalf("error parsing outer response body: %v", err)
}
var instancesData ListInstancesResponse
if err := json.Unmarshal([]byte(body.Result), &instancesData); err != nil {
t.Fatalf("error parsing nested result JSON: %v", err)
}
var got []string
for _, instance := range instancesData.Instances {
got = append(got, instance.Name)
}
sort.Strings(got)
sort.Strings(tc.want)
if !reflect.DeepEqual(got, tc.want) {
t.Errorf("instance list mismatch:\n got: %v\nwant: %v", got, tc.want)
}
}
})
}
}