Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Declarar ferramentas no SDK

Aula 6 de 25 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Declarar ferramentas no SDK
  2. O decorador @function_tool
  3. Personalizar nome e descrição
  4. Tipos de parâmetros suportados
  5. Devolver resultados estruturados
  6. Ferramentas alojadas pela OpenAI
  7. Combinar ferramentas personalizadas e alojadas
  8. Pontos-chave

Declarar ferramentas no SDK

As ferramentas são as capacidades concretas do seu agente. Sem ferramentas, um agente só consegue gerar texto; com ferramentas, pode consultar bases de dados, chamar APIs e enviar e-mails. No entanto, deve declará-las corretamente, pois a qualidade de uma ferramenta não depende apenas do seu código, mas também de quão bem o modelo a compreende.

O decorador @function_tool

A forma mais simples de criar uma ferramenta é o decorador @function_tool, que transforma uma função Python padrão numa capacidade que o agente pode invocar.

from agents import function_tool

@function_tool
def search_customer(email: str) -> str:
    """Search for a customer by email address in the database.

    Args:
        email: The customer's email address to search for.
    """
    # In production: call your database
    customers = {
        "[email protected]": {"name": "Alice Dupont", "plan": "Pro", "since": "2024"},
        "[email protected]": {"name": "Bob Martin", "plan": "Starter", "since": "2025"},
    }
    customer = customers.get(email)
    if customer:
        return f"Customer found: {customer['name']}, plan {customer['plan']}, customer since {customer['since']}"
    return f"No customer found with email {email}"

Nada é declarado em duplicado: o SDK utiliza o nome da função como nome da ferramenta, a docstring como descrição e as dicas de tipo (type hints) para gerar o esquema JSON dos parâmetros. Por outras palavras, a sua docstring deixa de ser apenas um comentário para os seus colegas; torna-se no texto que o modelo lê para decidir se deve chamar esta função. Uma docstring vaga leva a chamadas imprecisas.

Personalizar nome e descrição

Quando o nome da sua função segue convenções internas em vez da lógica de negócio, pode substituir aquilo que o modelo vê.

@function_tool(
    name_override="search_crm",
    description_override="Search for a customer in the CRM by email, name, or account number."
)
def search_customer(identifier: str) -> str:
    """Search for a customer."""
    # ...
    return "Result"

Tipos de parâmetros suportados

Para além dos tipos nativos do Python, o SDK aceita modelos Pydantic. Quando uma ferramenta aceita três ou mais parâmetros, agrupe-os: o esquema torna-se mais legível para o modelo e a validação protege-o contra valores atípicos.

from pydantic import BaseModel, Field
from typing import Optional
from agents import function_tool

class SearchFilter(BaseModel):
    category: str = Field(description="Product category")
    max_price: Optional[float] = Field(None, description="Maximum price in euros")
    in_stock: bool = Field(True, description="Only products in stock")

@function_tool
def search_products(filter: SearchFilter) -> str:
    """Search for products based on specified criteria."""
    results = []
    # Search logic using filter.category, filter.max_price, etc.
    return f"Found {len(results)} products in {filter.category}"

Os modelos Pydantic validam automaticamente as entradas e fornecem descrições ricas, campo por campo, ao modelo.

Devolver resultados estruturados

Uma ferramenta devolve sempre uma cadeia de caracteres (string). Quando os seus dados têm estrutura — múltiplas métricas, uma lista, tipos mistos — serialize-os como JSON em vez de compor uma frase: o modelo lerá as chaves de forma muito mais fiável do que texto livre.

import json
from agents import function_tool

@function_tool
def get_sales_stats(month: str, year: int) -> str:
    """Retrieve sales statistics for a given month."""
    stats = {
        "month": month,
        "year": year,
        "revenue": 145000,
        "sales_count": 342,
        "avg_basket": 423.98,
        "top_products": ["Laptop Pro", "Tablet Air", "Monitor 4K"]
    }
    return json.dumps(stats, ensure_ascii=False, indent=2)

Ferramentas alojadas pela OpenAI

Para além das suas funções personalizadas, o SDK fornece acesso a ferramentas geridas pela OpenAI que são executadas no lado da plataforma.

from agents import Agent, WebSearchTool, FileSearchTool, CodeInterpreterTool

agent = Agent(
    name="General-purpose assistant",
    instructions="You are an assistant capable of searching the web, analyzing files, and executing code.",
    tools=[
        WebSearchTool(),
        FileSearchTool(
            vector_store_ids=["vs_abc123"],
            max_num_results=10,
        ),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

A WebSearchTool permite ao agente pesquisar na Internet em tempo real e não requer configuração. A FileSearchTool realiza pesquisas semânticas nos seus ficheiros, mas pressupõe uma configuração prévia: deve criar um vetor de armazenamento (vector store) através da API da OpenAI e carregar os seus documentos para ele — daí o vs_abc123 passado como parâmetro. A CodeInterpreterTool permite ao agente escrever e executar código Python num contentor isolado, tornando-a a escolha ideal para análise de dados e geração de gráficos. Requer um tool_config que especifique este contentor: {"type": "auto"} cria-o sob demanda (o SDK openai-agents rejeita CodeInterpreterTool() sem isto).

Combinar ferramentas personalizadas e alojadas

O verdadeiro poder reside na combinação. Um analista financeiro necessita dos seus dados internos, capacidades de cálculo e contexto de mercado: três fontes que nenhuma ferramenta única cobre.

agent = Agent(
    name="Financial analyst",
    instructions="""You are a financial analyst.
    Use internal tools to retrieve data,
    the code interpreter to analyze it,
    and web search for market context.""",
    tools=[
        get_sales_stats,
        search_customer,
        WebSearchTool(),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

Repare como as instruções especificam para que serve cada família de ferramentas. Sem esta clareza, um agente com quatro ferramentas hesita, tenta duas desnecessariamente e aumenta a latência sem motivo.

Pontos-chave

  • @function_tool transforma uma função Python numa ferramenta de agente
  • A docstring e as dicas de tipo geram automaticamente o esquema JSON
  • Utilize Pydantic para parâmetros complexos com validação
  • As ferramentas devolvem sempre cadeias de caracteres (JSON se estruturadas)
  • Combine as suas ferramentas personalizadas com WebSearchTool, FileSearchTool e CodeInterpreterTool