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

Chamada de funções avançada: esquemas e validação

Aula 7 de 25 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Chamada de funções avançada: esquemas e validação
  2. Esquemas JSON e modo estrito
  3. Validação personalizada com Pydantic
  4. Tratamento de erros nas ferramentas
  5. Saída estruturada para ferramentas
  6. Padrão: ferramentas com contexto partilhado
  7. Pontos-chave

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_type força o agente a estruturar a sua resposta final
  • O contexto partilhado (RunContextWrapper) permite às ferramentas aceder ao estado da aplicação