Module: tools¶

from adk_fluent import T

Fluent tool composition. Consistent with P, C, S, M modules.

Quick Reference¶

Method	Returns	Description
`T.fn(func_or_tool, confirm=False)`	`TComposite`	Wrap a callable as a tool
`T.agent(agent_or_builder)`	`TComposite`	Wrap an agent (or builder) as an AgentTool
`T.toolset(ts)`	`TComposite`	Wrap any ADK toolset (MCPToolset, etc.)
`T.google_search()`	`TComposite`	Google Search tool
`T.search(registry, always_loaded=None, max_tools=20)`	`TComposite`	BM25-indexed dynamic tool loading (two-phase pattern)
`T.schema(schema_cls)`	`TComposite`	Attach a ToolSchema for contract checking
`T.mock(name, returns=None, side_effect=None)`	`TComposite`	Create a mock tool that returns a fixed value or side-effect
`T.confirm(tool_or_composite, message=None)`	`TComposite`	Wrap tool(s) with a confirmation requirement
`T.timeout(tool_or_composite, seconds=30)`	`TComposite`	Wrap tool(s) with a per-invocation timeout
`T.cache(tool_or_composite, ttl=300, key_fn=None)`	`TComposite`	Wrap tool(s) with a TTL-based result cache
`T.mcp(url_or_params, tool_filter=None, prefix=None)`	`TComposite`	Thin factory over :class:`McpToolset` builder
`T.a2a(agent_card_url, name=None, description=None, timeout=600.0)`	`TComposite`	Wrap a remote A2A agent as an AgentTool
`T.skill(path)`	`TComposite`	Wrap ADK `SkillToolset` for progressive disclosure
`T.openapi(spec, tool_filter=None, auth=None)`	`TComposite`	Thin factory over :class:`OpenAPIToolset` builder
`T.bigquery(credentials_config=None, bigquery_tool_config=None, tool_filter=None)`	`TComposite`	Wrap ADK `BigQueryToolset` (BigQuery data + metadata tools)
`T.spanner(credentials_config=None, spanner_tool_settings=None, tool_filter=None)`	`TComposite`	Wrap ADK `SpannerToolset` (Spanner data + schema tools)
`T.bigtable(credentials_config=None, bigtable_tool_settings=None, tool_filter=None)`	`TComposite`	Wrap ADK `BigtableToolset` (Bigtable data + metadata tools)
`T.vertex_ai_search(data_store_id=None, data_store_specs=None, search_engine_id=None, filter=None, max_results=None, bypass_multi_tools_limit=False)`	`TComposite`	Wrap ADK `VertexAiSearchTool` (built-in Vertex AI Search grounding)
`T.enterprise_search()`	`TComposite`	Wrap ADK `EnterpriseWebSearchTool` (Gemini 2+ enterprise web grounding)
`T.url_context()`	`TComposite`	Wrap ADK `UrlContextTool` (Gemini 2 automatic URL content retrieval)
`T.computer_use(computer, excluded_predefined_functions=None)`	`TComposite`	Wrap ADK `ComputerUseToolset` (screen-control function tools)
`T.a2ui(catalog='basic', schema=None)`	`TComposite`	A2UI toolset for LLM-guided UI generation
`T.effectful(tool_or_composite, key, scope='session', ttl=0.0)`	`TComposite`	Wrap tool(s) as idempotent side-effects with a user-supplied key
`T.transform(tool_or_composite, pre=None, post=None)`	`TComposite`	Wrap tool(s) with pre/post argument/result transforms
`T.vertex_search(data_store_id=None, data_store_specs=None, search_engine_id=None, filter=None, max_results=None, bypass_multi_tools_limit=False)`	`TComposite`	Wrap ADK `VertexAiSearchTool` (built-in Vertex AI Search grounding)

Wrapping¶

`T.fn(func_or_tool: Any, *, confirm: bool = False) -> TComposite`¶

Wrap a callable as a tool.

If func_or_tool is already a BaseTool, it is used as-is. Plain callables are wrapped in FunctionTool. Set confirm=True to require user confirmation before execution.

Parameters:

func_or_tool (Any)
confirm (bool) — default: False

`T.agent(agent_or_builder: Any) -> TComposite`¶

Wrap an agent (or builder) as an AgentTool.

Parameters:

agent_or_builder (Any)

`T.toolset(ts: Any) -> TComposite`¶

Wrap any ADK toolset (MCPToolset, etc.).

Parameters:

ts (Any)

Built-in tool groups¶

`T.google_search() -> TComposite`¶

Google Search tool.

Dynamic loading¶

`T.search(registry: Any, *, always_loaded: list[str] | None = None, max_tools: int = 20) -> TComposite`¶

BM25-indexed dynamic tool loading (two-phase pattern).

Wraps a ToolRegistry in a SearchToolset that implements discovery -> loading -> freezing lifecycle.

Parameters:

registry (Any)
always_loaded (list[str] | None) — default: None
max_tools (int) — default: 20

Contract checking¶

`T.schema(schema_cls: type) -> TComposite`¶

Attach a ToolSchema for contract checking.

When piped into a tool chain, this marker is extracted during IR conversion and wired to AgentNode.tool_schema.

Parameters:

schema_cls (type)

Mock¶

`T.mock(name: str, *, returns: Any = None, side_effect: Any = None) -> TComposite`¶

Create a mock tool that returns a fixed value or side-effect.

Args:

name: Name for the mock tool.
returns: Value to return (ignored if side_effect is set).
side_effect: Callable or static value used instead of returns.

Parameters:

name (str)
returns (Any) — default: None
side_effect (Any) — default: None

Confirm¶

`T.confirm(tool_or_composite: TComposite | Any, message: str | None = None) -> TComposite`¶

Wrap tool(s) with a confirmation requirement.

Each tool in the composite is individually wrapped so that require_confirmation is set.

Parameters:

tool_or_composite (TComposite | Any)
message (str | None) — default: None

Timeout¶

`T.timeout(tool_or_composite: TComposite | Any, seconds: float = 30) -> TComposite`¶

Wrap tool(s) with a per-invocation timeout.

Parameters:

tool_or_composite (TComposite | Any)
seconds (float) — default: 30

Cache¶

`T.cache(tool_or_composite: TComposite | Any, ttl: float = 300, key_fn: Any = None) -> TComposite`¶

Wrap tool(s) with a TTL-based result cache.

Parameters:

tool_or_composite (TComposite | Any)
ttl (float) — default: 300
key_fn (Any) — default: None

MCP¶

`T.mcp(url_or_params: Any, *, tool_filter: Any = None, prefix: str | None = None) -> TComposite`¶

Thin factory over :class:McpToolset builder.

Parameters:

url_or_params (Any)
tool_filter (Any) — default: None
prefix (str | None) — default: None

A2A¶

`T.a2a(agent_card_url: str, *, name: str | None = None, description: str | None = None, timeout: float = 600.0) -> TComposite`¶

Wrap a remote A2A agent as an AgentTool.

This is useful when you want the LLM to invoke a remote agent as a tool (structured I/O) rather than delegating to it as a sub-agent (opaque autonomous task).

Args:

agent_card_url: Base URL or full card URL of the remote agent.
name: Override the agent name (defaults to remote agent’s name).
description: Override the agent description.
timeout: HTTP timeout in seconds.

Parameters:

agent_card_url (str)
name (str | None) — default: None
description (str | None) — default: None
timeout (float) — default: 600.0

Skills¶

`T.skill(path: Any) -> TComposite`¶

Wrap ADK SkillToolset for progressive disclosure.

Parses SKILL.md files from directory path(s) and creates a SkillToolset. The toolset provides L1/L2/L3 progressive disclosure — skill metadata is always in the system prompt, instructions loaded on demand by the LLM.

Args:

path: Directory path, list of paths, or list of google.adk.skills.Skill objects.

Parameters:

path (Any)

OpenAPI¶

`T.openapi(spec: Any, *, tool_filter: Any = None, auth: Any = None) -> TComposite`¶

Thin factory over :class:OpenAPIToolset builder.

Parameters:

spec (Any)
tool_filter (Any) — default: None
auth (Any) — default: None

Google Cloud data toolsets¶

`T.bigquery(*, credentials_config: Any = None, bigquery_tool_config: Any = None, tool_filter: Any = None) -> TComposite`¶

Wrap ADK BigQueryToolset (BigQuery data + metadata tools).

Requires the BigQuery client extras (google-cloud-bigquery). The toolset is imported lazily, so this factory only fails when those extras are missing at call time.

Args:

credentials_config: BigQueryCredentialsConfig for auth.
bigquery_tool_config: BigQueryToolConfig (write modes, etc.).
tool_filter: ToolPredicate or list of tool names to expose.

Parameters:

credentials_config (Any) — default: None
bigquery_tool_config (Any) — default: None
tool_filter (Any) — default: None

`T.spanner(*, credentials_config: Any = None, spanner_tool_settings: Any = None, tool_filter: Any = None) -> TComposite`¶

Wrap ADK SpannerToolset (Spanner data + schema tools).

Requires the Spanner client extras (google-cloud-spanner). Imported lazily; this factory only fails when those extras are missing.

Args:

credentials_config: SpannerCredentialsConfig for auth.
spanner_tool_settings: SpannerToolSettings (capabilities).
tool_filter: ToolPredicate or list of tool names to expose.

Parameters:

credentials_config (Any) — default: None
spanner_tool_settings (Any) — default: None
tool_filter (Any) — default: None

`T.bigtable(*, credentials_config: Any = None, bigtable_tool_settings: Any = None, tool_filter: Any = None) -> TComposite`¶

Wrap ADK BigtableToolset (Bigtable data + metadata tools).

Requires the Bigtable client extras (google-cloud-bigtable). Imported lazily; this factory only fails when those extras are missing.

Args:

credentials_config: BigtableCredentialsConfig for auth.
bigtable_tool_settings: BigtableToolSettings (capabilities).
tool_filter: ToolPredicate or list of tool names to expose.

Parameters:

credentials_config (Any) — default: None
bigtable_tool_settings (Any) — default: None
tool_filter (Any) — default: None

Search / grounding tools¶

`T.vertex_ai_search(*, data_store_id: str | None = None, data_store_specs: Any = None, search_engine_id: str | None = None, filter: str | None = None, max_results: int | None = None, bypass_multi_tools_limit: bool = False) -> TComposite`¶

Wrap ADK VertexAiSearchTool (built-in Vertex AI Search grounding).

Provide exactly one of data_store_id or search_engine_id (or data_store_specs), matching the ADK tool’s own validation.

Args:

data_store_id: Fully-qualified Vertex AI Search data store resource.
data_store_specs: List of VertexAISearchDataStoreSpec.
search_engine_id: Fully-qualified search engine resource.
filter: Optional Vertex AI Search filter expression.
max_results: Maximum number of results to return.
bypass_multi_tools_limit: Allow alongside other built-in tools.

Parameters:

data_store_id (str | None) — default: None
data_store_specs (Any) — default: None
search_engine_id (str | None) — default: None
filter (str | None) — default: None
max_results (int | None) — default: None
bypass_multi_tools_limit (bool) — default: False

`T.enterprise_search() -> TComposite`¶

Wrap ADK EnterpriseWebSearchTool (Gemini 2+ enterprise web grounding).

A built-in tool with no constructor arguments — Gemini invokes it automatically for grounded, Enterprise-compliant web search.

`T.url_context() -> TComposite`¶

Wrap ADK UrlContextTool (Gemini 2 automatic URL content retrieval).

A built-in tool with no constructor arguments — Gemini automatically fetches content from URLs in the prompt to inform its response.

Computer use¶

`T.computer_use(computer: Any, *, excluded_predefined_functions: list[str] | None = None) -> TComposite`¶

Wrap ADK ComputerUseToolset (screen-control function tools).

Args:

computer: A BaseComputer implementation that performs the actual screen/keyboard/mouse actions.
excluded_predefined_functions: Names of predefined computer-use functions to omit from the toolset.

Parameters:

computer (Any)
excluded_predefined_functions (list[str] | None) — default: None

A2UI¶

`T.a2ui(*, catalog: str = basic, schema: Any = None) -> TComposite`¶

A2UI toolset for LLM-guided UI generation.

Default (catalog="basic"): wraps SendA2uiToClientToolset from the optional a2ui-agent package. Raises :class:A2UINotInstalled when the package is not importable — install with pip install a2ui-agent.

Flux (catalog="flux"): returns a toolset that exposes the flux component factories and injects per-component llm metadata (description, examples, antiPatterns) loaded from catalog/flux/catalog.json into the tool schema. The flux path does not require a2ui-agent.

Args:

catalog: Catalog identifier ("basic" or "flux").
schema: Optional catalog schema dict for validation.

Raises:

ValueError: If `catalog` is not a known identifier.

Parameters:

catalog (str) — default: 'basic'
schema (Any) — default: None

Effectful (idempotent)¶

`T.effectful(tool_or_composite: TComposite | Any, *, key: str | Any, scope: str = session, ttl: float = 0.0) -> TComposite`¶

Wrap tool(s) as idempotent side-effects with a user-supplied key.

First call with a given key runs the tool and records the result in the ambient :class:EffectCache; subsequent calls with the same key return the cached value without invoking the tool.

An :class:EffectRecorded event is emitted on the ambient

class:: EventBus with source="fresh" or source="cache".

Args:

tool_or_composite: The tool to wrap.
key: Either a format string rendered against args (e.g. "user:{user_id}") or a callable (args) -> str.
scope: Cache partition bucket ("session" by default).
ttl: Lifetime in seconds. 0 means “no expiry”.

Parameters:

tool_or_composite (TComposite | Any)
key (str | Any)
scope (str) — default: 'session'
ttl (float) — default: 0.0

Transform¶

`T.transform(tool_or_composite: TComposite | Any, *, pre: Any = None, post: Any = None) -> TComposite`¶

Wrap tool(s) with pre/post argument/result transforms.

Parameters:

tool_or_composite (TComposite | Any)
pre (Any) — default: None
post (Any) — default: None

Methods¶

`T.vertex_search(*, data_store_id: str | None = None, data_store_specs: Any = None, search_engine_id: str | None = None, filter: str | None = None, max_results: int | None = None, bypass_multi_tools_limit: bool = False) -> TComposite`¶

Wrap ADK VertexAiSearchTool (built-in Vertex AI Search grounding).

Provide exactly one of data_store_id or search_engine_id (or data_store_specs), matching the ADK tool’s own validation.

Args:

data_store_id: Fully-qualified Vertex AI Search data store resource.
data_store_specs: List of VertexAISearchDataStoreSpec.
search_engine_id: Fully-qualified search engine resource.
filter: Optional Vertex AI Search filter expression.
max_results: Maximum number of results to return.
bypass_multi_tools_limit: Allow alongside other built-in tools.

Parameters:

data_store_id (str | None) — default: None
data_store_specs (Any) — default: None
search_engine_id (str | None) — default: None
filter (str | None) — default: None
max_results (int | None) — default: None
bypass_multi_tools_limit (bool) — default: False

Composition Operators¶

`|` (compose (TComposite))¶

Combine tools into a collection

Types¶

Type	Description
`TComposite`	Composable tool chain.

Module: tools¶

Quick Reference¶

Wrapping¶

T.fn(func_or_tool: Any, *, confirm: bool = False) -> TComposite¶

T.agent(agent_or_builder: Any) -> TComposite¶

T.toolset(ts: Any) -> TComposite¶

Built-in tool groups¶

T.google_search() -> TComposite¶

Dynamic loading¶

T.search(registry: Any, *, always_loaded: list[str] | None = None, max_tools: int = 20) -> TComposite¶

Contract checking¶

T.schema(schema_cls: type) -> TComposite¶

Mock¶

T.mock(name: str, *, returns: Any = None, side_effect: Any = None) -> TComposite¶

Confirm¶

T.confirm(tool_or_composite: TComposite | Any, message: str | None = None) -> TComposite¶

Timeout¶

T.timeout(tool_or_composite: TComposite | Any, seconds: float = 30) -> TComposite¶

Cache¶

T.cache(tool_or_composite: TComposite | Any, ttl: float = 300, key_fn: Any = None) -> TComposite¶

MCP¶

T.mcp(url_or_params: Any, *, tool_filter: Any = None, prefix: str | None = None) -> TComposite¶

A2A¶

T.a2a(agent_card_url: str, *, name: str | None = None, description: str | None = None, timeout: float = 600.0) -> TComposite¶

Skills¶

T.skill(path: Any) -> TComposite¶

OpenAPI¶

T.openapi(spec: Any, *, tool_filter: Any = None, auth: Any = None) -> TComposite¶

Google Cloud data toolsets¶

T.bigquery(*, credentials_config: Any = None, bigquery_tool_config: Any = None, tool_filter: Any = None) -> TComposite¶

T.spanner(*, credentials_config: Any = None, spanner_tool_settings: Any = None, tool_filter: Any = None) -> TComposite¶

T.bigtable(*, credentials_config: Any = None, bigtable_tool_settings: Any = None, tool_filter: Any = None) -> TComposite¶

Search / grounding tools¶

T.vertex_ai_search(*, data_store_id: str | None = None, data_store_specs: Any = None, search_engine_id: str | None = None, filter: str | None = None, max_results: int | None = None, bypass_multi_tools_limit: bool = False) -> TComposite¶

T.enterprise_search() -> TComposite¶

T.url_context() -> TComposite¶

Computer use¶

T.computer_use(computer: Any, *, excluded_predefined_functions: list[str] | None = None) -> TComposite¶

A2UI¶

T.a2ui(*, catalog: str = basic, schema: Any = None) -> TComposite¶

Effectful (idempotent)¶

T.effectful(tool_or_composite: TComposite | Any, *, key: str | Any, scope: str = session, ttl: float = 0.0) -> TComposite¶

Transform¶

T.transform(tool_or_composite: TComposite | Any, *, pre: Any = None, post: Any = None) -> TComposite¶

Methods¶

T.vertex_search(*, data_store_id: str | None = None, data_store_specs: Any = None, search_engine_id: str | None = None, filter: str | None = None, max_results: int | None = None, bypass_multi_tools_limit: bool = False) -> TComposite¶

Composition Operators¶

| (compose (TComposite))¶

Types¶

`T.fn(func_or_tool: Any, *, confirm: bool = False) -> TComposite`¶

`T.agent(agent_or_builder: Any) -> TComposite`¶

`T.toolset(ts: Any) -> TComposite`¶

`T.google_search() -> TComposite`¶

`T.search(registry: Any, *, always_loaded: list[str] | None = None, max_tools: int = 20) -> TComposite`¶

`T.schema(schema_cls: type) -> TComposite`¶

`T.mock(name: str, *, returns: Any = None, side_effect: Any = None) -> TComposite`¶

`T.confirm(tool_or_composite: TComposite | Any, message: str | None = None) -> TComposite`¶

`T.timeout(tool_or_composite: TComposite | Any, seconds: float = 30) -> TComposite`¶

`T.cache(tool_or_composite: TComposite | Any, ttl: float = 300, key_fn: Any = None) -> TComposite`¶

`T.mcp(url_or_params: Any, *, tool_filter: Any = None, prefix: str | None = None) -> TComposite`¶

`T.a2a(agent_card_url: str, *, name: str | None = None, description: str | None = None, timeout: float = 600.0) -> TComposite`¶

`T.skill(path: Any) -> TComposite`¶

`T.openapi(spec: Any, *, tool_filter: Any = None, auth: Any = None) -> TComposite`¶

`T.bigquery(*, credentials_config: Any = None, bigquery_tool_config: Any = None, tool_filter: Any = None) -> TComposite`¶

`T.spanner(*, credentials_config: Any = None, spanner_tool_settings: Any = None, tool_filter: Any = None) -> TComposite`¶

`T.bigtable(*, credentials_config: Any = None, bigtable_tool_settings: Any = None, tool_filter: Any = None) -> TComposite`¶

`T.vertex_ai_search(*, data_store_id: str | None = None, data_store_specs: Any = None, search_engine_id: str | None = None, filter: str | None = None, max_results: int | None = None, bypass_multi_tools_limit: bool = False) -> TComposite`¶

`T.enterprise_search() -> TComposite`¶

`T.url_context() -> TComposite`¶

`T.computer_use(computer: Any, *, excluded_predefined_functions: list[str] | None = None) -> TComposite`¶

`T.a2ui(*, catalog: str = basic, schema: Any = None) -> TComposite`¶

`T.effectful(tool_or_composite: TComposite | Any, *, key: str | Any, scope: str = session, ttl: float = 0.0) -> TComposite`¶

`T.transform(tool_or_composite: TComposite | Any, *, pre: Any = None, post: Any = None) -> TComposite`¶

`T.vertex_search(*, data_store_id: str | None = None, data_store_specs: Any = None, search_engine_id: str | None = None, filter: str | None = None, max_results: int | None = None, bypass_multi_tools_limit: bool = False) -> TComposite`¶

`|` (compose (TComposite))¶