Chamada de funções avançada: esquemas e validação
Nesta página
Chamada de funções avançada: esquemas e validação
A chamada de funções é o mecanismo central que permite a um agente decidir quando e como invocar as suas ferramentas. Declarar uma ferramenta é suficiente para um protótipo, mas a passagem para produção exige que restrinja as chamadas, valide valores de negócio e trate falhas sem fazer o agente colapsar. É isso que esta lição aborda.
Esquemas JSON e modo estrito
A API de Respostas utiliza esquemas JSON para descrever os parâmetros de cada ferramenta, e o modo estrito garante que o modelo adere exatamente ao esquema. Especificamente, utilizar um Enum ou um Literal fecha a porta a valores inventados.
from agents import function_tool
from pydantic import BaseModel, Field
from typing import Literal
from enum import Enum
class Priority(str, Enum):
LOW = "low"
MEDIUM = "medium"
HIGH = "high"
CRITICAL = "critical"
class CreateTicket(BaseModel):
title: str = Field(description="Short ticket title (max 100 characters)")
description: str = Field(description="Detailed problem description")
priority: Priority = Field(description="Ticket priority level")
component: Literal["frontend", "backend", "infra", "data"] = Field(
description="Affected technical component"
)
tags: list[str] = Field(
default_factory=list,
description="Optional tags to categorize the ticket"
)
@function_tool
def create_support_ticket(ticket: CreateTicket) -> str:
"""Creates a new technical support ticket."""
# In production: call Jira, Linear, GitHub Issues, etc.
return f"Ticket created: [{ticket.priority.value}] {ticket.title} ({ticket.component})"
Com o modo estrito ativado por predefinição, o modelo nunca pode enviar uma prioridade inválida ou um componente fora da lista permitida. Não precisará de escrever código defensivo no backend para traduzir “urgente” ou “P1” num valor que o seu sistema de tickets reconheça.
Validação personalizada com Pydantic
A verificação de tipos impede valores impossíveis, mas não valores absurdos. Um IBAN de quinze caracteres é uma cadeia de caracteres perfeitamente válida; a sua lógica de negócio é que a rejeita. O Pydantic permite incorporar estas regras diretamente no esquema.
from pydantic import BaseModel, Field, field_validator
class MoneyTransfer(BaseModel):
source_account: str = Field(description="Source account IBAN")
destination_account: str = Field(description="Destination account IBAN")
amount: float = Field(gt=0, le=50000, description="Amount in euros (max 50,000)")
reason: str = Field(min_length=5, max_length=200, description="Reason for transfer")
@field_validator("source_account", "destination_account")
@classmethod
def validate_iban(cls, v):
if not v.startswith("FR"):
raise ValueError("Only French IBANs are accepted")
if len(v) != 27:
raise ValueError("IBAN must contain 27 characters")
return v
@function_tool
def execute_transfer(transfer: MoneyTransfer) -> str:
"""Executes a bank transfer between two accounts."""
return f"Transfer of €{transfer.amount} initiated from {transfer.source_account[:8]}... to {transfer.destination_account[:8]}..."
As restrições gt=0 e le=50000 no montante desempenham um papel semelhante num nível diferente: tornam estruturalmente impossível uma transferência negativa ou que exceda o limite, independentemente da forma como o utilizador formula o pedido.
Tratamento de erros nas ferramentas
E quando uma ferramenta é executada mas falha? A tentação é deixar a exceção propagar-se; isso é um erro, pois interrompe o ciclo do agente. Em vez disso, devolva uma mensagem de erro clara que o modelo possa ler e interpretar.
import json
from agents import function_tool
@function_tool
def query_external_api(endpoint: str, parameters: dict) -> str:
"""Queries an external API with the specified parameters."""
try:
# In production: real HTTP call
import httpx
response = httpx.get(f"https://api.example.com/{endpoint}", params=parameters, timeout=10)
response.raise_for_status()
return json.dumps(response.json(), ensure_ascii=False)
except httpx.TimeoutException:
return json.dumps({
"error": True,
"message": f"Timeout calling {endpoint}. Retry in a few moments."
})
except httpx.HTTPStatusError as e:
return json.dumps({
"error": True,
"message": f"HTTP error {e.response.status_code} on {endpoint}.",
"details": str(e)
})
except Exception as e:
return json.dumps({
"error": True,
"message": f"Unexpected error: {str(e)}"
})
Cada ramo formata a mensagem numa linguagem que o modelo compreende. Num caso de tempo limite, o agente tentará outra chamada; num erro HTTP 404, informará o utilizador ou mudará de abordagem, em vez de persistir cegamente.
Saída estruturada para ferramentas
Esta restrição aplica-se também à saída final. Com output_type, o final_output deixa de ser texto para analisar e passa a ser um objeto tipado, diretamente utilizável pelo código chamador.
from pydantic import BaseModel
from agents import Agent, Runner
class AnalysisResponse(BaseModel):
summary: str
key_points: list[str]
recommendation: str
confidence_score: float
agent = Agent(
name="Analyst",
instructions="Analyze the provided data and produce a structured report.",
model="gpt-5.6-terra",
output_type=AnalysisResponse,
)
result = Runner.run_sync(agent, "Analyze Q1 2026 sales trends.")
# result.final_output is of type AnalysisResponse
print(f"Summary: {result.final_output.summary}")
print(f"Score: {result.final_output.confidence_score}")
Padrão: ferramentas com contexto partilhado
Uma última questão recorrente: as suas ferramentas necessitam frequentemente de estado partilhado — sessão do utilizador, ligação à base de dados, chave de API — que seria absurdo passar através do modelo. O contexto resolve isto, passando-o juntamente com a conversa.
from dataclasses import dataclass
from agents import Agent, Runner, RunContextWrapper, function_tool
@dataclass
class AppContext:
user_id: str
db_connection: object # Your DB connection
api_key: str
@function_tool
def get_user_profile(ctx: RunContextWrapper[AppContext]) -> str:
"""Retrieves the current user's profile."""
user_id = ctx.context.user_id
# Use ctx.context.db_connection for the query
return f"User profile {user_id}: Premium, active since 2024"
agent = Agent(
name="Personalized Agent",
instructions="You assist the logged-in user.",
tools=[get_user_profile],
)
context = AppContext(user_id="usr_123", db_connection=None, api_key="xxx")
result = Runner.run_sync(agent, "What is my profile?", context=context)
A ferramenta não tem parâmetros de negócio: a identidade do utilizador provém do contexto, não do modelo. Esta é também uma medida de segurança, uma vez que o agente não pode visualizar o perfil de outra pessoa alterando um argumento.
Pontos-chave
- Esquemas Pydantic com enums e Literals garantem a validade da chamada
- Validadores de campo adicionam validação de negócio à verificação de tipos
- Devolva mensagens de erro em JSON em vez de levantar exceções nas ferramentas
output_typeforça o agente a estruturar a sua resposta final- O contexto partilhado (
RunContextWrapper) permite às ferramentas aceder ao estado da aplicação