Python Function Tools

Relevant source files

• contributing/samples/agent_tool_with_grounding_metadata/__init__.py
• contributing/samples/agent_tool_with_grounding_metadata/agent.py
• contributing/samples/human_tool_confirmation/__init__.py
• contributing/samples/human_tool_confirmation/agent.py
• contributing/samples/langchain_structured_tool_agent/__init__.py
• contributing/samples/langchain_structured_tool_agent/agent.py
• src/google/adk/flows/llm_flows/__init__.py
• src/google/adk/integrations/crewai/__init__.py
• src/google/adk/integrations/crewai/crewai_tool.py
• src/google/adk/integrations/langchain/__init__.py
• src/google/adk/integrations/langchain/langchain_tool.py
• src/google/adk/tools/_automatic_function_calling_util.py
• src/google/adk/tools/_function_parameter_parse_util.py
• src/google/adk/tools/agent_tool.py
• src/google/adk/tools/crewai_tool.py
• src/google/adk/tools/function_tool.py
• src/google/adk/tools/google_search_agent_tool.py
• src/google/adk/tools/langchain_tool.py
• src/google/adk/utils/context_utils.py
• tests/unittests/cli/test_cli_feature_options.py
• tests/unittests/cli/test_cli_tools_click_option_mismatch.py
• tests/unittests/integrations/crewai/test_crewai_tool.py
• tests/unittests/integrations/langchain/test_langchain_tool.py
• tests/unittests/tools/test_agent_tool.py
• tests/unittests/tools/test_build_function_declaration.py
• tests/unittests/tools/test_from_function_with_options.py
• tests/unittests/tools/test_function_tool.py
• tests/unittests/tools/test_function_tool_pydantic.py
• tests/unittests/tools/test_function_tool_with_import_annotations.py
• tests/unittests/tools/test_transfer_to_agent_tool.py
• tests/unittests/utils/test_context_utils.py

Purpose and Scope

This document covers the FunctionTool system, which enables ordinary Python functions to be used as agent tools through automatic schema generation and execution wrapping. Python Function Tools convert function signatures, docstrings, and type hints into tool declarations that LLM agents can understand and invoke.

For information about:

• The base tool interface and framework, see Tool Framework
• MCP tool integration, see MCP (Model Context Protocol) Tools
• Tool authentication, see Tool Authentication
• Human-in-the-loop confirmation, see Tool Confirmation (HITL)

Overview

Python Function Tools allow developers to expose Python functions directly to agents without manually defining tool schemas. The system automatically:

• Extracts function signatures and converts them to types.FunctionDeclaration src/google/adk/tools/function_tool.py90-101
• Maps Python type hints to schema types (e.g., str to STRING, int to INTEGER) src/google/adk/tools/_automatic_function_calling_util.py41-58
• Generates descriptions from docstrings using inspect.cleandoc src/google/adk/tools/function_tool.py72-82
• Handles both synchronous and asynchronous functions src/google/adk/tools/function_tool.py160-200
• Provides ToolContext injection for accessing session state and services src/google/adk/tools/function_tool.py168-169
• Supports wrapping other agents as tools via AgentTool src/google/adk/tools/agent_tool.py94-108

Sources: src/google/adk/tools/function_tool.py39-101 src/google/adk/tools/_automatic_function_calling_util.py41-58 src/google/adk/tools/agent_tool.py94-108

---

FunctionTool Architecture

Conceptual Structure: Code Entity Space

Diagram: Bridging Python code entities to LLM Function Declarations.

Sources: src/google/adk/tools/function_tool.py39-101 src/google/adk/tools/_automatic_function_calling_util.py204-215 src/google/adk/tools/_function_parameter_parse_util.py214-221 src/google/adk/tools/agent_tool.py94-108

The FunctionTool class wraps a Python callable and implements the BaseTool interface. It:

1. Metadata Extraction: Inspects the function name and docstring during initialization src/google/adk/tools/function_tool.py61-82
2. Declaration Generation: Uses build_function_declaration to create a schema for the LLM src/google/adk/tools/function_tool.py91-98
3. Argument Mapping: Preprocesses LLM-provided arguments, converting JSON dicts to Pydantic models if the function signature requires it src/google/adk/tools/function_tool.py103-157
4. Execution: Handles mandatory argument checks and async/sync invocation src/google/adk/tools/function_tool.py160-200

Sources: src/google/adk/tools/function_tool.py39-200

---

Automatic Schema Generation

The conversion of Python signatures to JSON schemas is handled by _automatic_function_calling_util.py and _function_parameter_parse_util.py.

Type Mapping Table

The following mapping is used to translate Python types to Gemini/Vertex AI schema types:

Python Type	LLM Schema Type (types.Type)	File Reference
str, string	STRING	src/google/adk/tools/_automatic_function_calling_util.py42
int, integer	INTEGER	src/google/adk/tools/_automatic_function_calling_util.py43
float, number	NUMBER	src/google/adk/tools/_automatic_function_calling_util.py44
bool, boolean	BOOLEAN	src/google/adk/tools/_automatic_function_calling_util.py45
list, array, tuple	ARRAY	src/google/adk/tools/_automatic_function_calling_util.py50-52
dict, object	OBJECT	src/google/adk/tools/_automatic_function_calling_util.py53-54
Any	TYPE_UNSPECIFIED	src/google/adk/tools/_automatic_function_calling_util.py57

Pydantic Integration

If a parameter is annotated with a Pydantic BaseModel, the system generates a nested OBJECT schema src/google/adk/tools/_automatic_function_calling_util.py161 During tool execution, the FunctionTool automatically validates the incoming JSON from the LLM against the Pydantic model using model_validate src/google/adk/tools/function_tool.py146-148

The _function_parameter_parse_util.py also provides advanced parsing for complex types like fixed-length tuples, generating schemas with prefixItems and unevaluatedItems: False src/google/adk/tools/_function_parameter_parse_util.py61-93

Sources: src/google/adk/tools/_automatic_function_calling_util.py41-58 src/google/adk/tools/function_tool.py123-157 src/google/adk/tools/_function_parameter_parse_util.py61-93

---

AgentTool: Wrapping Agents as Tools

The AgentTool class allows an entire agent to be exposed as a tool to another agent src/google/adk/tools/agent_tool.py94-108

• Schema Mapping: It extracts the input_schema and output_schema from the wrapped agent to define the tool's parameters and response format src/google/adk/tools/agent_tool.py135-187
• Context Propagation: By default, it propagates plugins from the parent runner context to the child agent's runner src/google/adk/tools/agent_tool.py104-107
• Execution: When invoked, it initializes a new Runner for the child agent, using the same app_name and services as the parent context src/google/adk/tools/agent_tool.py192-234

Sources: src/google/adk/tools/agent_tool.py94-234 tests/unittests/tools/test_agent_tool.py143-181

---

Context Injection

Function tools can access the execution context by including a parameter annotated with ToolContext (or named tool_context).

Detection Logic

The system uses find_context_parameter to identify which argument should receive the context src/google/adk/utils/context_utils.py65-97

1. It looks for parameters annotated with Context, ToolContext, or CallbackContext src/google/adk/utils/context_utils.py36-62
2. It handles Optional[Context] and string-based forward references src/google/adk/utils/context_utils.py55-59
3. If no annotation is found, FunctionTool defaults to checking for the name tool_context src/google/adk/tools/function_tool.py85

Sources: src/google/adk/utils/context_utils.py36-97 src/google/adk/tools/function_tool.py84-87

---

Tool Execution Flow

Data Flow: From LLM Request to Function Result

Diagram: Logic flow within FunctionTool.run_async.

Sources: src/google/adk/tools/function_tool.py103-200 src/google/adk/tools/_automatic_function_calling_util.py61-93

Mandatory Argument Validation

Before calling the underlying function, FunctionTool checks if all required arguments (those without default values) are provided by the LLM src/google/adk/tools/function_tool.py179-182 If arguments are missing, it returns a structured error message encouraging the model to retry with the missing parameters src/google/adk/tools/function_tool.py186-189

Sources: src/google/adk/tools/function_tool.py174-190

---

Integration Wrappers

The ADK provides integration wrappers for third-party tool ecosystems, enabling developers to use existing tools within the ADK framework.

CrewAI and LangChain

ADK supports wrapping tools from the CrewAI and LangChain ecosystems:

• CrewAI: The CrewaiTool wrapper (moved to google.adk.integrations.crewai) allows CrewAI tools to be integrated src/google/adk/tools/crewai_tool.py19-20
• LangChain: The LangchainTool wrapper (moved to google.adk.integrations.langchain) supports LangChain's StructuredTool and @tool decorators src/google/adk/tools/langchain_tool.py19-20

Sources: src/google/adk/tools/crewai_tool.py src/google/adk/tools/langchain_tool.py

---

Advanced Features

Tool Confirmation (HITL)

FunctionTool supports a require_confirmation attribute src/google/adk/tools/function_tool.py50 This can be:

• A boolean: If True, every call requires user approval.
• A callable: A function that takes the tool's arguments and returns a boolean src/google/adk/tools/function_tool.py56-59

Sources: src/google/adk/tools/function_tool.py46-60

Feature Flag: JSON Schema for Declarations

A feature flag JSON_SCHEMA_FOR_FUNC_DECL allows switching between the legacy types.Schema object and a modern parameters_json_schema approach for tool declarations src/google/adk/tools/_automatic_function_calling_util.py210-215 When enabled, it uses _function_tool_declarations.build_function_declaration_with_json_schema src/google/adk/tools/_automatic_function_calling_util.py212-214

Sources: src/google/adk/tools/_automatic_function_calling_util.py210-215 src/google/adk/features/_feature_registry.py23

---

Summary of Key Classes and Functions

Entity	Role	File
FunctionTool	Primary class wrapping Python callables into ADK tools.	src/google/adk/tools/function_tool.py39
AgentTool	Wraps an Agent instance to be used as a tool.	src/google/adk/tools/agent_tool.py94
build_function_declaration	Utility to generate types.FunctionDeclaration from a function.	src/google/adk/tools/_automatic_function_calling_util.py204
_get_pydantic_schema	Generates JSON schema using Pydantic's model_json_schema.	src/google/adk/tools/_automatic_function_calling_util.py153
find_context_parameter	Inspects signature to find where to inject ToolContext.	src/google/adk/utils/context_utils.py65
_preprocess_args	Handles type conversion (e.g., JSON to Pydantic) before invocation.	src/google/adk/tools/function_tool.py103

Sources: src/google/adk/tools/function_tool.py src/google/adk/tools/agent_tool.py src/google/adk/tools/_automatic_function_calling_util.py src/google/adk/utils/context_utils.py