Avanceret funktionskald: skemaer og validering
På denne side
Avanceret funktionskald: skemaer og validering
Funktionskald er den centrale mekanisme, der giver en agent mulighed for at beslutte, hvornår og hvordan dine værktøjer skal invoceres. Det er nok at deklarere et værktøj til en prototype, men når du skal i produktion, kræver det, at du begrænser kald, validerer forretningsværdier og håndterer fejl uden at få agenten til at crashe. Det er præcis, hvad denne lektion dækker.
JSON-skemaer og streng tilstand
Responses API bruger JSON-skemaer til at beskrive parametrene for hvert værktøj, og streng tilstand (strict mode) garanterer, at modellen overholder skemaet nøjagtigt. Specifikt lukker brugen af en Enum eller en Literal døren for opdigtede værdier.
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})"
Når streng tilstand er aktiveret som standard, kan modellen aldrig sende en ugyldig prioritet eller en komponent uden for den tilladte liste. Du behøver ikke skrive defensiv backend-kode for at oversætte „urgent” eller „P1” til en værdi, dit ticketsystem genkender.
Brugerdefineret validering med Pydantic
Typekontrol forhindrer umulige værdier, men ikke absurde. En IBAN på femten tegn er en helt gyldig streng; din forretningslogik vil afvise den. Pydantic giver dig mulighed for at indlejre disse regler direkte i skemaet.
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]}..."
Begrænsningerne gt=0 og le=50000 på beløbet spiller en lignende rolle på et andet niveau: de gør en negativ overførsel eller en, der overstiger grænsen, strukturelt umulig, uanset hvordan brugeren formulerer anmodningen.
Håndtering af fejl i værktøjer
Hvad så, når et værktøj eksekveres, men fejler? Fristelsen er stor til at lade undtagelsen boble op; det er en fejl, fordi det afbryder agentens løkke. Returnér i stedet en klar fejlmeddelelse, som modellen kan læse og fortolke.
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)}"
})
Hver gren formatterer meddelelsen på et sprog, som modellen forstår. Ved en timeout vil agenten forsøge et nyt kald; ved en HTTP 404-fejl vil den informere brugeren eller ændre strategi i stedet for blindt at fortsætte.
Struktureret output til værktøjer
Denne begrænsning gælder også for det endelige output. Med output_type er final_output ikke længere tekst, der skal parses, men et typet objekt, der kan bruges direkte af den kaldende kode.
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}")
Mønster: Værktøjer med delt kontekst
Et sidste tilbagevendende problem: Dine værktøjer har ofte brug for delt tilstand – brugersession, databaseforbindelse, API-nøgle – som det ville være absurd at sende gennem modellen. Kontekst løser dette ved at sende det sammen med samtalen.
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)
Værktøjet har ingen forretningsparametre: brugerens identitet kommer fra konteksten, ikke fra modellen. Dette er også en sikkerhedsforanstaltning, da agenten ikke kan se nogen andens profil ved at ændre et argument.
Vigtige pointer
- Pydantic-skemaer med enums og Literals garanterer gyldige kald
- Feltdvalidatorer tilføjer forretningsvalidering oven i typekontrol
- Returnér JSON-fejlmeddelelser i stedet for at kaste undtagelser i værktøjer
output_typetvinger agenten til at strukturere sit endelige svar- Delt kontekst (
RunContextWrapper) giver værktøjer adgang til applikationstilstand