Išplėstinis funkcijų kvietimas: schemos ir validavimas
Šiame puslapyje
Išplėstinis funkcijų kvietimas: schemos ir validavimas
Funkcijų kvietimas yra pagrindinis mechanizmas, leidžiantis agentui nuspręsti, kada ir kaip naudoti tavo įrankius. Prototipui pakanka tiesiog deklaruoti įrankį, tačiau pereinant į gamybinę aplinką tenka apriboti kvietimus, patikrinti verslo reikšmes ir tvarkyti klaidas taip, kad agentas „nenukristų“. Būtent tai ir nagrinėjama šioje pamokoje.
JSON schemos ir griežtas režimas
„Responses“ API naudoja JSON schemas kiekvieno įrankio parametrams aprašyti, o griežtas (strict) režimas garantuoja, kad modelis tiksliai laikysis schemos. Visų pirma, naudojant Enum arba Literal, užkertamas kelias sugalvotoms reikšmėms.
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})"
Pagal nutylėjimą įjungus griežtą režimą, modelis niekada neišsiųs neteisingo prioriteto ar komponento, nepatenkančio į leistiną sąrašą. Tau nereikės rašyti apsauginio serverio kodo, kuris verstų „urgent“ arba „P1“ į tavo bilietų sistemos atpažįstamą reikšmę.
Tinkintas validavimas naudojant „Pydantic“
Tipų tikrinimas sustabdo neįmanomas reikšmes, bet ne absurdiškas. Penkiolikos simbolių IBAN yra visiškai tinkama eilutė, tačiau tavo verslo logika ją atmes. „Pydantic“ leidžia įterpti šias taisykles tiesiai į schemą.
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]}..."
Sumos apribojimai gt=0 ir le=50000 atlieka panašų vaidmenį kitame lygmenyje: jie daro neigiamą pervedimą arba viršijantį limitą pervedimą struktūriškai neįmanomu, nesvarbu, kaip vartotojas suformuluotų prašymą.
Klaidų tvarkymas įrankiuose
O kas nutinka, kai įrankis vykdomas, bet nepavyksta? Pagunda leisti išimčiai kilti aukštyn yra klaida, nes tai nutraukia agento ciklą. Vietoj to grąžink aiškų klaidos pranešimą, kurį modelis galės perskaityti ir interpretuoti.
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)}"
})
Kiekviena šaka suformatuoja pranešimą modelio suprantama kalba. Esant laiko limito viršijimui, agentas bandys dar kartą; gavęs HTTP 404 klaidą, jis informuos vartotoją arba pakeis metodiką, užuot aklai tęsęs veiksmus.
Struktūrizuota įrankių išvestis
Šis apribojimas taikomas ir galutinei išvestiai. Naudojant output_type, final_output tampa ne tekstu, kurį reikia analizuoti, o tipizuotu objektu, tiesiogiai naudojamu kviečiančiojo kodo.
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}")
Šablonas: įrankiai su bendru kontekstu
Dar viena dažna problema: tavo įrankiams dažnai reikia bendros būsenos – vartotojo sesijos, duomenų bazės ryšio, API rakto – kurių perdavimas per modelį būtų absurdiškas. Kontekstas tai išsprendžia perduodamas šią informaciją kartu su pokalbiu.
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)
Įrankis neturi verslo parametrų: vartotojo tapatybė gaunama iš konteksto, o ne iš modelio. Tai taip pat yra saugumo priemonė, nes agentas negali peržiūrėti kito asmens profilio pakeisdamas argumentą.
Svarbiausi punktai
- „Pydantic“ schemos su „enums“ ir „Literals“ garantuoja kvietimų validumą
- Laukų validatoriai papildo tipų tikrinimą verslo taisyklėmis
- Įrankiuose grąžink JSON klaidų pranešimus vietoj išimčių sukėlimo
output_typepriverčia agentą struktūrizuoti galutinį atsakymą- Bendras kontekstas (
RunContextWrapper) leidžia įrankiams pasiekti programos būseną