Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Geavanceerd function calling: schema's en validatie

Les 7 van 25 Bijgewerkt op 29 juli 2026 Ontwikkelaar
Op deze pagina
  1. Geavanceerd function calling: schema’s en validatie
  2. JSON-schema’s en strikte modus
  3. Aangepaste validatie met Pydantic
  4. Foutafhandeling in tools
  5. Gestructureerde output voor tools
  6. Patroon: tools met gedeelde context
  7. Belangrijkste punten

Geavanceerd function calling: schema’s en validatie

Function calling is het kernmechanisme waarmee een agent beslist wanneer en hoe uw tools worden aangeroepen. Het declareren van een tool volstaat voor een prototype, maar voor productieomgevingen moet u de aanroepen beperken, bedrijfswaarden valideren en fouten afhandelen zonder dat de agent crasht. Dat is wat deze les behandelt.

JSON-schema’s en strikte modus

De Responses API gebruikt JSON-schema’s om de parameters voor elke tool te beschrijven, en de strikte modus garandeert dat het model zich exact aan het schema houdt. Het gebruik van een Enum of een Literal sluit namelijk verzonnen waarden uit.

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="Korte tickettitel (max 100 tekens)")
    description: str = Field(description="Gedetailleerde probleembeschrijving")
    priority: Priority = Field(description="Prioriteitsniveau van het ticket")
    component: Literal["frontend", "backend", "infra", "data"] = Field(
        description="Betroffen technisch onderdeel"
    )
    tags: list[str] = Field(
        default_factory=list,
        description="Optionele tags om het ticket te categoriseren"
    )

@function_tool
def create_support_ticket(ticket: CreateTicket) -> str:
    """Maakt een nieuw technisch supportticket aan."""
    # In productie: roep Jira, Linear, GitHub Issues, enz. aan
    return f"Ticket aangemaakt: [{ticket.priority.value}] {ticket.title} ({ticket.component})"

Met strikte modus standaard ingeschakeld, kan het model nooit een ongeldige prioriteit sturen of een component buiten de toegestane lijst. U hoeft geen defensieve backend-code te schrijven om “urgent” of “P1” te vertalen naar een waarde die uw ticketsysteem herkent.

Aangepaste validatie met Pydantic

Typecontrole voorkomt onmogelijke waarden, maar geen absurde. Een IBAN van vijftien tekens is een perfect geldige string; uw bedrijfslogica wijst deze echter af. Met Pydantic kunt u deze regels direct in het schema embedden.

from pydantic import BaseModel, Field, field_validator

class MoneyTransfer(BaseModel):
    source_account: str = Field(description="IBAN van de bronrekening")
    destination_account: str = Field(description="IBAN van de doelrekening")
    amount: float = Field(gt=0, le=50000, description="Bedrag in euro's (max 50.000)")
    reason: str = Field(min_length=5, max_length=200, description="Reden voor overschrijving")

    @field_validator("source_account", "destination_account")
    @classmethod
    def validate_iban(cls, v):
        if not v.startswith("FR"):
            raise ValueError("Alleen Franse IBAN's worden geaccepteerd")
        if len(v) != 27:
            raise ValueError("IBAN moet uit 27 tekens bestaan")
        return v

@function_tool
def execute_transfer(transfer: MoneyTransfer) -> str:
    """Voert een bankoverschrijving uit tussen twee rekeningen."""
    return f"Overschrijving van €{transfer.amount} gestart van {transfer.source_account[:8]}... naar {transfer.destination_account[:8]}..."

De beperkingen gt=0 en le=50000 op het bedrag spelen een vergelijkbare rol op een ander niveau: ze maken een negatieve overschrijving of een overschrijding van het limiet structureel onmogelijk, ongeacht hoe de gebruiker het verzoek formuleert.

Foutafhandeling in tools

Wat gebeurt er als een tool wordt uitgevoerd maar faalt? De verleiding is groot om de exceptie te laten doorborrelen; dat is een fout, omdat dit de agent-lus onderbreekt. Retourneer in plaats daarvan een duidelijke foutmelding die het model kan lezen en interpreteren.

import json
from agents import function_tool

@function_tool
def query_external_api(endpoint: str, parameters: dict) -> str:
    """Raadpleegt een externe API met de opgegeven parameters."""
    try:
        # In productie: echte HTTP-aanroep
        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"Time-out bij aanroep van {endpoint}. Probeer het over enkele ogenblikken opnieuw."
        })
    except httpx.HTTPStatusError as e:
        return json.dumps({
            "error": True,
            "message": f"HTTP-fout {e.response.status_code} op {endpoint}.",
            "details": str(e)
        })
    except Exception as e:
        return json.dumps({
            "error": True,
            "message": f"Onverwachte fout: {str(e)}"
        })

Elke tak formatteert het bericht in een taal die het model begrijpt. Bij een time-out zal de agent een nieuwe poging wagen; bij een HTTP 404-fout zal deze de gebruiker informeren of van aanpak veranderen in plaats van blindelings door te gaan.

Gestructureerde output voor tools

Deze beperking geldt ook voor de uiteindelijke output. Met output_type is final_output geen tekst meer die geparseerd moet worden, maar een getypeerd object dat direct bruikbaar is voor de aanroepende code.

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="Analyseer de verstrekte gegevens en produceer een gestructureerd rapport.",
    model="gpt-5.6-terra",
    output_type=AnalysisResponse,
)

result = Runner.run_sync(agent, "Analyseer verkooptrends Q1 2026.")
# result.final_output is van het type AnalysisResponse
print(f"Samenvatting: {result.final_output.summary}")
print(f"Score: {result.final_output.confidence_score}")

Patroon: tools met gedeelde context

Een laatste terugkerend probleem: uw tools hebben vaak gedeelde state nodig—gebruikerssessie, databaseverbinding, API-sleutel—die doorgeven via het model absurd zou zijn. Context lost dit op door deze naast het gesprek mee te geven.

from dataclasses import dataclass
from agents import Agent, Runner, RunContextWrapper, function_tool

@dataclass
class AppContext:
    user_id: str
    db_connection: object  # Uw DB-verbinding
    api_key: str

@function_tool
def get_user_profile(ctx: RunContextWrapper[AppContext]) -> str:
    """Haalt het profiel van de huidige gebruiker op."""
    user_id = ctx.context.user_id
    # Gebruik ctx.context.db_connection voor de query
    return f"Gebruikersprofiel {user_id}: Premium, actief sinds 2024"

agent = Agent(
    name="Personalized Agent",
    instructions="U assisteert de ingelogde gebruiker.",
    tools=[get_user_profile],
)

context = AppContext(user_id="usr_123", db_connection=None, api_key="xxx")
result = Runner.run_sync(agent, "Wat is mijn profiel?", context=context)

De tool heeft geen bedrijfsparameters: de identiteit van de gebruiker komt uit de context, niet van het model. Dit is ook een veiligheidsmaatregel, omdat de agent niet het profiel van iemand anders kan bekijken door een argument te wijzigen.

Belangrijkste punten

  • Pydantic-schema’s met enums en Literals garanderen de geldigheid van aanroepen
  • Field-validatoren voegen bedrijfsvalidatie toe bovenop typecontrole
  • Retourneer JSON-foutberichten in plaats van excepties op te werpen in tools
  • output_type dwingt de agent om zijn eindrespons te structureren
  • Gedeelde context (RunContextWrapper) stelt tools in staat toegang te krijgen tot applicatiestate