feat: Create wait for tool (#885)

`
tools:
  wait_for_tool:
    kind: wait-for
description: "Tool puts chat to sleep for given timeout example 3m,10s,
5m etc. For tasks such as cluster creation no need to wait. It takes
longer time such as 8m for instance creation. Use timeout value as
default if nothing is provided"
    timeout: 10s
`

Output: 
`
prernakakkar@prernakakkar:~/senseai/genai-toolbox$ curl -X POST -H
"Content-Type: application/json" -d '{"duration": "5m"}'
http://127.0.0.1:5000/api/tool/wa
it_for_tool/invoke
{"result":"[\"Wait for 5m0s completed successfully.\"]"}
`

cmd/root.go

@@ -64,6 +64,7 @@ import (
 	_ "github.com/googleapis/genai-toolbox/internal/tools/spanner/spannerexecutesql"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/spanner/spannersql"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/sqlitesql"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/utility/wait"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/valkey"
 
 	"github.com/spf13/cobra"

docs/en/resources/tools/utility/wait.md

@@ -0,0 +1,37 @@
+---
+title: "wait"
+type: docs
+weight: 1
+description: > 
+  A "wait" tool pauses execution for a specified duration.
+aliases:
+- /resources/tools/utility/wait
+---
+
+## About
+
+A `wait` tool pauses execution for a specified duration. This can be useful in workflows where a delay is needed between steps.
+
+`wait` takes one input parameter `duration` which is a string representing the time to wait (e.g., "10s", "2m", "1h").
+
+{{% notice info %}} 
+This tool is intended for developer assistant workflows with human-in-the-loop and shouldn't be used for production agents.
+{{% /notice %}}
+
+## Example
+
+```yaml
+tools:
+  wait_for_tool:
+    kind: wait
+    description: Use this tool to pause execution for a specified duration.
+    timeout: 30s
+```
+
+## Reference
+
+| **field**   |                  **type**                  | **required** | **description**                                                                                  |
+|-------------|:------------------------------------------:|:------------:|--------------------------------------------------------------------------------------------------|
+| kind        |                   string                   |     true     | Must be "wait".                                                                     |
+| description |                   string                   |     true     | Description of the tool that is passed to the LLM.                                               |
+| timeout     |                   string                   |     true     | The default duration the tool can wait for.                                                      |

internal/tools/utility/wait/wait.go

@@ -0,0 +1,120 @@
+// 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 wait
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	yaml "github.com/goccy/go-yaml"
+	"github.com/googleapis/genai-toolbox/internal/sources"
+	"github.com/googleapis/genai-toolbox/internal/tools"
+)
+
+const kind string = "wait"
+
+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
+}
+
+type Config struct {
+	Name         string   `yaml:"name" validate:"required"`
+	Kind         string   `yaml:"kind" validate:"required"`
+	Description  string   `yaml:"description" validate:"required"`
+	Timeout      string   `yaml:"timeout" validate:"required"`
+	AuthRequired []string `yaml:"authRequired"`
+}
+
+var _ tools.ToolConfig = Config{}
+
+func (cfg Config) ToolConfigKind() string {
+	return kind
+}
+
+func (cfg Config) Initialize(_ map[string]sources.Source) (tools.Tool, error) {
+	durationParameter := tools.NewStringParameter("duration", "The duration to wait for, specified as a string (e.g., '10s', '2m', '1h').")
+	parameters := tools.Parameters{durationParameter}
+
+	mcpManifest := tools.McpManifest{
+		Name:        cfg.Name,
+		Description: cfg.Description,
+		InputSchema: parameters.McpManifest(),
+	}
+
+	t := Tool{
+		Name:        cfg.Name,
+		Kind:        kind,
+		Parameters:  parameters,
+		manifest:    tools.Manifest{Description: cfg.Description, Parameters: parameters.Manifest(), AuthRequired: cfg.AuthRequired},
+		mcpManifest: mcpManifest,
+	}
+	return t, nil
+}
+
+// validate interface
+var _ tools.Tool = Tool{}
+
+type Tool struct {
+	Name        string
+	Kind        string
+	Parameters  tools.Parameters
+	manifest    tools.Manifest
+	mcpManifest tools.McpManifest
+}
+
+func (t Tool) Invoke(ctx context.Context, params tools.ParamValues) ([]any, error) {
+	paramsMap := params.AsMap()
+
+	durationStr, ok := paramsMap["duration"].(string)
+	if !ok {
+		return nil, fmt.Errorf("duration parameter is not a string")
+	}
+
+	totalDuration, err := time.ParseDuration(durationStr)
+	if err != nil {
+		return nil, fmt.Errorf("invalid duration format: %w", err)
+	}
+
+	time.Sleep(totalDuration)
+
+	return []any{fmt.Sprintf("Wait for %v completed successfully.", totalDuration)}, nil
+}
+
+func (t Tool) ParseParams(data map[string]any, claims map[string]map[string]any) (tools.ParamValues, error) {
+	return tools.ParseParams(t.Parameters, data, claims)
+}
+
+func (t Tool) Manifest() tools.Manifest {
+	return t.manifest
+}
+
+func (t Tool) McpManifest() tools.McpManifest {
+	return t.mcpManifest
+}
+
+func (t Tool) Authorized(verifiedAuthServices []string) bool {
+	return true
+}

internal/tools/utility/wait/wait_test.go

@@ -0,0 +1,75 @@
+// 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 wait_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"
+
+	wait "github.com/googleapis/genai-toolbox/internal/tools/utility/wait"
+)
+
+func TestParseFromYamlWait(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:
+				example_tool:
+					kind: wait
+					description: some description
+					timeout: 10s
+					authRequired:
+						- my-google-auth-service
+			`,
+			want: server.ToolConfigs{
+				"example_tool": wait.Config{
+					Name:         "example_tool",
+					Kind:         "wait",
+					Description:  "some description",
+					Timeout:      "10s",
+					AuthRequired: []string{"my-google-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)
+			}
+		})
+	}
+}

tests/server.go

@@ -67,7 +67,7 @@ func StartCmd(ctx context.Context, toolsFile map[string]any, args ...string) (*C
 	if err != nil {
 		return nil, nil, fmt.Errorf("unable to write tools file: %s", err)
 	}
-	args = append(args, "--tools_file", path)
+	args = append(args, "--tools-file", path)
 
 	ctx, cancel := context.WithCancel(ctx)
 	// Open a pipe for tracking the output from the cmd

tests/utility/wait_integration_test.go

@@ -0,0 +1,118 @@
+// 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 utility
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"regexp"
+	"testing"
+	"time"
+
+	"github.com/googleapis/genai-toolbox/internal/testutils"
+	"github.com/googleapis/genai-toolbox/tests"
+)
+
+func RunWaitTool(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+
+	args := []string{"--port", "5001"}
+
+	toolsFile := map[string]any{
+		"tools": map[string]any{
+			"my-wait-for-tool": map[string]any{
+				"kind":        "wait",
+				"description": "Wait for a specified duration.",
+				"timeout":     "30s",
+			},
+		},
+	}
+	cmd, cleanup, err := tests.StartCmd(ctx, toolsFile, args...)
+	if err != nil {
+		t.Fatalf("command initialization returned an error: %s", err)
+	}
+	defer cleanup()
+
+	waitCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+	out, err := testutils.WaitForString(waitCtx, regexp.MustCompile(`Server ready to serve`), cmd.Out)
+	if err != nil {
+		t.Logf("toolbox command logs: \n%s", out)
+		t.Fatalf("toolbox didn't start successfully: %s", err)
+	}
+
+	invokeTcs := []struct {
+		name        string
+		api         string
+		requestBody io.Reader
+		want        string
+		isErr       bool
+	}{
+		{
+			name:        "invoke my-wait-for-tool",
+			api:         "http://127.0.0.1:5001/api/tool/my-wait-for-tool/invoke",
+			requestBody: bytes.NewBuffer([]byte(`{"duration": "1s"}`)),
+			want:        `["Wait for 1s completed successfully."]`,
+			isErr:       false,
+		},
+		{
+			name:        "invoke my-wait-for-tool with invalid duration",
+			api:         "http://127.0.0.1:5001/api/tool/my-wait-for-tool/invoke",
+			requestBody: bytes.NewBuffer([]byte(`{"duration": "invalid"}`)),
+			isErr:       true,
+		},
+	}
+	for _, tc := range invokeTcs {
+		t.Run(tc.name, func(t *testing.T) {
+			req, err := http.NewRequest(http.MethodPost, tc.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 != http.StatusOK {
+				if tc.isErr {
+					return
+				}
+				bodyBytes, _ := io.ReadAll(resp.Body)
+				t.Fatalf("response status code is not 200, got %d: %s", resp.StatusCode, string(bodyBytes))
+			}
+
+			var body map[string]interface{}
+			err = json.NewDecoder(resp.Body).Decode(&body)
+			if err != nil {
+				t.Fatalf("error parsing response body")
+			}
+
+			got, ok := body["result"].(string)
+			if !ok {
+				t.Fatalf("unable to find result in response body")
+			}
+
+			if got != tc.want {
+				t.Fatalf("unexpected value: got %q, want %q", got, tc.want)
+			}
+		})
+	}
+}