Tools
Extend agent capabilities with tools for external interactions and actions
Tools represent specific capabilities that extend AI agents beyond text generation and reasoning. They enable agents to interact with external systems, perform actions, and access real-time information.
What Are Tools?
Tools are modular code components that execute distinct, predefined tasks. They bridge the gap between an agent's reasoning capabilities and the external world.
Key Characteristics
- Action-Oriented: Perform specific tasks like API calls, database queries, or file operations
- Extends Capabilities: Access real-time information and affect external systems
- Predefined Logic: Execute developer-defined functions without independent reasoning
- Dynamic Usage: Agents decide which tools to use and when based on context
Agent vs Tool Responsibilities
The LLM reasons about which tool to use, when, and with what inputs. The tool itself executes its designated function without independent reasoning.
How Agents Use Tools
Agents leverage tools through a dynamic process:
- Reasoning: LLM analyzes instructions, context, and user requests
- Selection: Chooses appropriate tools based on available options and descriptions
- Invocation: Generates required arguments and executes the tool
- Observation: Receives and processes the tool's output
- Integration: Incorporates results into ongoing reasoning and response generation
Tool Types
ADK TypeScript supports several types of tools for different use cases:
🔧 Function Tools
Custom tools created for your specific application needs
⚡ Built-in Tools
Ready-to-use tools for search, file operations, and user interaction
🔌 MCP Tools
Model Context Protocol tools for standardized integrations
🌐 Third-Party Tools
Manual integration patterns for external libraries and frameworks
📊 OpenAPI Tools
Manual tool creation for REST API integration using OpenAPI specs
☁️ Google Cloud Tools
Authentication patterns and integration for Google Cloud services
Tool Context & Advanced Features
Context Access
Tools can access additional contextual information through ToolContext
:
- Session State: Read and modify persistent session data
- Event Actions: Control agent flow and behavior after tool execution
- Authentication: Handle API credentials and authentication flows
- Artifacts: Manage files and documents uploaded or generated
- Memory: Search and access long-term user memory
State Management
Tools can interact with session state to:
- Share data between different tools and agents
- Maintain information across interactions
- Use state prefixes for different scopes (app, user, session, temporary)
- Track state changes automatically
Flow Control
Tools can influence agent behavior through event actions:
- Skip Summarization: Bypass LLM processing when tool output is ready
- Transfer Control: Hand off execution to specialized agents
- Escalate: Pass control to parent agents in hierarchies
- Loop Control: Terminate loops in workflow agents
Authentication & Security
Tools support various authentication mechanisms:
- OAuth flows for secure API access
- API key management for service authentication
- Credential storage and retrieval
- Multi-step auth flows with user interaction
Best Practices
Tool Design Guidelines
- Use descriptive, action-oriented function names
- Provide clear type hints and parameter descriptions
- Return structured dictionaries with status indicators
- Write comprehensive docstrings for LLM understanding
- Handle errors gracefully with meaningful messages
Function Design
- Naming: Use verb-noun patterns (e.g.,
getWeather
,searchDocuments
) - Parameters: Clear names with proper TypeScript types
- Returns: Structured objects with status and error handling
- Documentation: Detailed descriptions for LLM decision making
Error Handling
- Status Indicators: Include clear success/error status in responses
- Error Messages: Provide actionable error information
- Graceful Degradation: Handle failures without breaking agent flow
- Retry Logic: Implement appropriate retry mechanisms
Performance Considerations
- Async Operations: Support for long-running operations
- Caching: Cache frequently accessed data
- Rate Limiting: Respect external service limits
- Timeout Handling: Implement appropriate timeouts
Tool Integration Patterns
Sequential Tool Usage
Tools can be chained together where one tool's output becomes another's input.
Conditional Tool Selection
Agents can choose different tools based on context and previous results.
Parallel Tool Execution
Multiple tools can run simultaneously for independent tasks.
Tool Composition
Complex workflows can combine multiple tool types for sophisticated operations.
Getting Started
New to tools? Start with these foundational concepts:
- Function Tools - Learn to create custom tools
- Built-in Tools - Explore ready-to-use capabilities
- Authentication - Secure your tool integrations
Advanced Topics
Once you're comfortable with the basics:
- OpenAPI Tools - Generate tools from API specifications
- Google Cloud Tools - Enterprise cloud integrations
- MCP Tools - Standardized tool protocols