08. Tool Integration

Chapter 8 of 24 · 15 min

KEY INSIGHT

Tools extend the agent's capabilities beyond reasoning, enabling it to interact with external systems through a well-defined interface with error handling and result processing. The agent's core capability is reasoning, but reasoning alone cannot accomplish practical tasks. Tool integration provides the means to take action in the world. Each tool implements a specific capability with standardized inputs, outputs, and error handling. Tool Interface Design All tools follow the same interface pattern. This consistency simplifies tool development and enables generic tool handling in the agent core. The interface specifies input validation, execution, and result formatting. ```python from abc import ABC, abstractmethod from typing import Any, TypedDict from datetime import datetime class ToolResult(TypedDict): success: bool data: Any | None error: str | None execution_time_ms: int class BaseTool(ABC): name: str description: str parameters: dict # JSON Schema for parameters @abstractmethod async def execute(self, **kwargs) -> ToolResult: """Execute the tool with given parameters.""" pass def validate_parameters(self, params: dict) -> tuple[bool, str | None]: """Validate parameters against the schema.""" # Implementation uses jsonschema or similar pass async def run(self, params: dict) -> ToolResult: """Run with timing and error handling wrapper.""" start = datetime.now() valid, error = self.validate_parameters(params) if not valid: return ToolResult( success=False, data=None, error=f"Invalid parameters: {error}", execution_time_ms=0 ) try: data = await self.execute(**params) elapsed = (datetime.now() - start).total_seconds() * 1000 return ToolResult( success=True, data=data, error=None, execution_time_ms=int(elapsed) ) except Exception as e: elapsed = (datetime.now() - start).total_seconds() * 1000 return ToolResult( success=False, data=None, error=str(e), execution_time_ms=int(elapsed) ) ``` Tool Categories Tools fall into several categories based on their purpose. Data retrieval tools query external information sources. Modification tools change state in external systems. Notification tools send information to users or other systems. Utility tools perform computations or transformations. A typical agent deployment includes tools from multiple categories. The specific selection depends on the agent's intended use cases and the systems it needs to access.

EXERCISE

Design a tool that searches a local filesystem for files matching criteria. Specify the parameter schema, return format, and at least three failure modes with appropriate error handling.