Como Adicionar Nova Tool

Visão Geral

As tools são funções que os agentes podem chamar para executar ações específicas (buscar dados, fazer reservas, etc).

Estrutura de uma Tool

from google.adk.tools import ToolContext
from typing import Optional
from dotenv import load_dotenv

load_dotenv()

async def minha_nova_tool(
    tool_context: ToolContext,
    parametro_obrigatorio: str,
    parametro_opcional: Optional[int] = None,
) -> dict:
    """
    Descrição breve do que a tool faz.

    Args:
        tool_context: Contexto da ferramenta (session, state)
        parametro_obrigatorio: Descrição do parâmetro
        parametro_opcional: Descrição do opcional

    Returns:
        Dict com os dados retornados
    """
    # Implementação
    result = {"status": "success", "data": "..."}

    # Retorno deve ser dict ou lista de blocks
    return result

Exemplo Completo

import os
import logging
from typing import Optional
from google.adk.tools import ToolContext
from google.cloud import bigquery

logger = logging.getLogger(__name__)

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT", "my-project")

def minha_tool(
    tool_context: ToolContext,
    destino: str,
    data_inicio: Optional[str] = None,
    limit: int = 10,
) -> list:
    """Busca produtos para um destino."""

    # Access state for context
    user_id = tool_context.state.get("user_id")

    # Implementar lógica
    client = bigquery.Client(project=PROJECT_ID)
    query = f"""
        SELECT * FROM dataset.products
        WHERE destination = @destino
        LIMIT @limit
    """

    results = client.query(query, params={"destino": destino, "limit": limit})

    # Retornar dados
    return [{"id": r.id, "name": r.name} for r in results]

Boas Práticas

1. Use typing

from typing import Optional, List, Dict, Any

2. Docstrings claras

Documente todos os parâmetros e o retorno.

3. Error handling

try:
    result = fazer_algo()
except Exception as e:
    logger.error(f"Erro na tool: {e}")
    return {"error": str(e)}

4. Logging

Use logger.info e logger.error para debug.

5. Sanitize PII

Retorne apenas dados necessários. Use tools/sanitize.py:

from ifriend_agent.tools.sanitize import strip_sensitive

def detalhes_experience(experience_id: str) -> dict:
    data = api.get(f"/experiences/{experience_id}")
    return strip_sensitive(data)

6. Context usage

Acesse session state quando necessário:

user_id = tool_context.state.get("user_id")
jwt_context = tool_context.state.get("jwt_context")

Onde criar

Coloque em ifriend_agent/tools/nome_da_tool_tool.py

Nome do arquivo deve terminar com _tool.py.

Como testar localmente

import asyncio
from google.adk.tools import ToolContext
from ifriend_agent.tools.sua_tool import sua_tool

async def test():
    context = MagicMock()
    context.state = {"user_id": "test-user"}

    result = await sua_tool(context, param="valor")
    print(result)

asyncio.run(test())