Python Function Tools

Relevant source files

• 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/labs/__init__.py
• src/google/adk/tools/_automatic_function_calling_util.py
• src/google/adk/tools/_function_parameter_parse_util.py
• src/google/adk/tools/crewai_tool.py
• src/google/adk/tools/function_tool.py
• src/google/adk/tools/langchain_tool.py
• src/google/adk/utils/context_utils.py
• tests/unittests/integrations/crewai/test_crewai_tool.py
• tests/unittests/integrations/langchain/test_langchain_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_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.

This page also details specialized tools for few-shot prompting (ExampleTool), long-running asynchronous tasks (LongRunningFunctionTool), and proactive human-in-the-loop (HITL) interactions (get_user_choice_tool and request_input).

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.py93-104
• Maps Python type hints to schema types (e.g., str to STRING, int to INTEGER) src/google/adk/tools/_automatic_function_calling_util.py42-59
• Generates descriptions from docstrings using inspect.cleandoc src/google/adk/tools/function_tool.py74-84
• 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

Sources: src/google/adk/tools/function_tool.py42-104 src/google/adk/tools/_automatic_function_calling_util.py42-59

---

FunctionTool Architecture

Conceptual Structure: Code Entity Space

Diagram: Bridging Python code entities to LLM Function Declarations.

Sources: src/google/adk/tools/function_tool.py42-104 src/google/adk/tools/_automatic_function_calling_util.py205-215 src/google/adk/tools/_function_parameter_parse_util.py36-48

The FunctionTool class wraps a Python callable and implements the BaseTool interface src/google/adk/tools/function_tool.py42 It:

1. Metadata Extraction: Inspects the function name and docstring during initialization src/google/adk/tools/function_tool.py64-84
2. Declaration Generation: Uses build_function_declaration to create a schema for the LLM src/google/adk/tools/function_tool.py94-102
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.py106-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.py42-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-43
int, integer	INTEGER	src/google/adk/tools/_automatic_function_calling_util.py44
float, number	src/google/adk/tools/_automatic_function_calling_util.py45
bool, boolean	BOOLEAN	src/google/adk/tools/_automatic_function_calling_util.py46
list, array, tuple	ARRAY	src/google/adk/tools/_automatic_function_calling_util.py51-53
dict, object	OBJECT	src/google/adk/tools/_automatic_function_calling_util.py54-55
Any	TYPE_UNSPECIFIED	src/google/adk/tools/_automatic_function_calling_util.py58

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.py162 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.py182-183

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.py62-94

Sources: src/google/adk/tools/_automatic_function_calling_util.py42-59 src/google/adk/tools/function_tool.py123-157 src/google/adk/tools/_function_parameter_parse_util.py62-94

---

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.py67-99

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

Sources: src/google/adk/utils/context_utils.py37-99 src/google/adk/tools/function_tool.py87-89

---

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.py106-200 src/google/adk/tools/_automatic_function_calling_util.py62-94

Argument Validation and Preprocessing

Before calling the underlying function, FunctionTool performs _preprocess_args to ensure arguments match the function's expected types src/google/adk/tools/function_tool.py106 This includes converting dictionaries into Pydantic models src/google/adk/tools/function_tool.py182-183 and handling lists of Pydantic models src/google/adk/tools/function_tool.py193-196

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

---

Specialized Function Tools

ExampleTool (Few-shot Prompting)

The ExampleTool is a specialized tool used to provide few-shot examples to the LLM. It allows developers to define expected tool call sequences and responses within the toolset, helping the model learn complex interaction patterns.

LongRunningFunctionTool (Async HITL)

For operations that take a significant amount of time or require external triggers, the LongRunningFunctionTool provides an asynchronous pattern. It is designed to work with session resumability, allowing the agent to pause execution while waiting for the tool to complete.

Proactive Clarification Tools

ADK provides built-in tools for agents to proactively seek clarification from users:

• get_user_choice_tool: Used when the agent needs the user to select from a set of options.
• request_input tool: Allows the LLM to pause execution and request specific missing information from the user. This generates a RequestInput event, which is central to the ADK's Human-in-the-Loop patterns.

---

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 (located in google.adk.integrations.crewai) allows CrewAI tools to be integrated src/google/adk/integrations/crewai/crewai_tool.py37-47 It handles CrewAI's specific **kwargs patterns and args_schema mapping src/google/adk/integrations/crewai/crewai_tool.py62-119
• LangChain: The LangchainTool wrapper (located in google.adk.integrations.langchain) supports LangChain's tool structures src/google/adk/integrations/langchain/__init__.py15-20

Sources: src/google/adk/integrations/crewai/crewai_tool.py37-131 src/google/adk/tools/crewai_tool.py19-26 src/google/adk/tools/langchain_tool.py19-32

---

Advanced Features

Tool Confirmation (HITL)

FunctionTool supports a require_confirmation attribute src/google/adk/tools/function_tool.py53 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.py59-62

Sources: src/google/adk/tools/function_tool.py49-63

---

Summary of Key Classes and Functions

Entity	Role	File
FunctionTool	Primary class wrapping Python callables into ADK tools.	src/google/adk/tools/function_tool.py42
build_function_declaration	Utility to generate types.FunctionDeclaration from a function.	src/google/adk/tools/_automatic_function_calling_util.py205
find_context_parameter	Inspects signature to find where to inject ToolContext.	src/google/adk/utils/context_utils.py67
_preprocess_args	Handles type conversion (e.g., JSON to Pydantic) before invocation.	src/google/adk/tools/function_tool.py106
LangchainTool	Wrapper for LangChain ecosystem tools.	src/google/adk/integrations/langchain/langchain_tool.py
CrewaiTool	Wrapper for CrewAI ecosystem tools.	src/google/adk/integrations/crewai/crewai_tool.py37

Sources: src/google/adk/tools/function_tool.py src/google/adk/tools/_automatic_function_calling_util.py src/google/adk/utils/context_utils.py src/google/adk/integrations/langchain/langchain_tool.py src/google/adk/integrations/crewai/crewai_tool.py