tool

Documentation

Overview

Package tool defines the interfaces for tools that can be called by an agent. A tool is a piece of code that performs a specific task. You can either define your own custom tools or use built-in ones, for example, GoogleSearch.

Index

• type Context
• type Predicate
  • func StringPredicate(allowedTools []string) Predicate
• type Tool
• type Toolset
  • func FilterToolset(toolset Toolset, predicate Predicate) Toolset

Types

type Context

type Context interface {
	agent.CallbackContext
	// FunctionCallID returns the unique identifier of the function call
	// that triggered this tool execution.
	FunctionCallID() string

	// Actions returns the EventActions for the current event. This can be
	// used by the tool to modify the agent's state, transfer to another
	// agent, or perform other actions.
	Actions() *session.EventActions
	// SearchMemory performs a semantic search on the agent's memory.
	SearchMemory(context.Context, string) (*memory.SearchResponse, error)

	// ToolConfirmation returns a handler for checking the Human-in-the-Loop
	// confirmation status for the current tool context. This should be used within a tool's logic
	// *before* performing any sensitive operations that require user approval.
	//
	// Example Usage:
	// if confirmation := ctx.ToolConfirmation(); confirmation == nil {
	//     // Confirmation required, create confirmation or handle appropriately
	//     ctx.RequestConfirmation("hint", payload)
	// }
	//
	// The returned *toolconfirmation.ToolConfirmation object provides methods to check the actual
	// confirmation state.
	ToolConfirmation() *toolconfirmation.ToolConfirmation

	// RequestConfirmation initiates the Human-in-the-Loop (HITL) process to ask the user for approval
	// before the tool proceeds with a specific action. Call this method when a tool needs
	// explicit user consent.
	//
	// This will typically result in the ADK emitting a special event
	// (e.g., a FunctionCall like "adk_request_confirmation") to the client application/UI,
	// prompting the user for a decision.
	//
	// Args:
	//   - hint: A human-readable string explaining why confirmation is needed. This is usually
	//     displayed to the user in the confirmation prompt.
	//   - payload: Any additional data or context about the action requiring confirmation.
	//
	// Returns:
	//   - nil: If the confirmation request was successfully enqueued or initiated within the ADK.
	//     This indicates that the process of asking the user has begun. It does NOT mean the action
	//     is approved. The tool's execution will likely pause or be suspended until the user responds.
	//   - error: If there was a failure in initiating the confirmation process itself (e.g., invalid
	//     arguments, issue with the event system). The request to ask the user has not been sent.
	RequestConfirmation(hint string, payload any) error
}

Context defines the interface for the context passed to a tool when it's called. It provides access to invocation-specific information and allows the tool to interact with the agent's state and memory.

type Predicate

type Predicate func(ctx agent.ReadonlyContext, tool Tool) bool

Predicate is a function which decides whether a tool should be exposed to LLM.

func StringPredicate

func StringPredicate(allowedTools []string) Predicate

StringPredicate is a helper that creates a Predicate from a string slice.

type Tool

type Tool interface {
	// Name returns the name of the tool.
	Name() string
	// Description returns a description of the tool.
	Description() string
	// IsLongRunning indicates whether the tool is a long-running operation,
	// which typically returns a resource id first and finishes the operation later.
	IsLongRunning() bool
}

Tool defines the interface for a callable tool.

type Toolset

type Toolset interface {
	// Name returns the name of the toolset.
	Name() string
	// Tools returns a list of tools in the toolset. The provided
	// ReadonlyContext can be used to dynamically determine which tools
	// to return based on the current invocation state.
	Tools(ctx agent.ReadonlyContext) ([]Tool, error)
}

Toolset is an interface for a collection of tools. It allows grouping related tools together and providing them to an agent.

func FilterToolset

func FilterToolset(toolset Toolset, predicate Predicate) Toolset

FilterToolset returns a Toolset that filters the tools in the given Toolset using the given predicate.