Izsaukumu uzlabota pārvaldība: shēmas un validācija
Šajā lapā
Izsaukumu uzlabota pārvaldība: shēmas un validācija
Funkciju izsaukumi ir galvenais mehānisms, kas ļauj aģentam lemt, kad un kā izmantot tavus rīkus. Prototipam pietiek ar rīka deklarēšanu, taču pāreja uz produkcijas vidi prasa ierobežot izsaukumus, validēt biznesa vērtības un apstrādāt kļūdas, nesabojājot aģenta darbību. Tieši to aplūkosim šajā nodarbībā.
JSON shēmas un stingrais režīms
Atbilžu API (Responses API) izmanto JSON shēmas, lai aprakstītu katra rīka parametrus, un stingrais (strict) režīms garantē, ka modelis precīzi ievēro shēmu. Konkrētāk, Enum vai Literal izmantošana aizver durvis izdomātām vērtībām.
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})"
Pēc noklusējuma ieslēgtā stingrā režīma dēļ modelis nekad nevar nosūtīt nederīgu prioritāti vai komponenti ārpus atļautā saraksta. Tev nebūs jāraksta aizsargājošs backend kods, lai tulkotu „urgent” vai „P1” vērtībā, ko atpazīst tava biļešu sistēma.
Pielāgota validācija ar Pydantic
Tipu pārbaude novērš neiespējamas vērtības, bet ne absurdas. Piecpadsmit zīmju IBAN ir pilnīgi derīga virkne; tava biznesa loģika to noraida. Pydantic ļauj iegult šos noteikumus tieši shēmā.
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]}..."
Ierobežojumi gt=0 un le=50000 summai spēlē līdzīgu lomu citā līmenī: tie padara negatīvu pārskaitījumu vai tādu, kas pārsniedz limitu, strukturāli neiespējamu neatkarīgi no tā, kā lietotājs formulē pieprasījumu.
Kļūdu apstrāde rīkos
Ko darīt, ja rīks tiek izpildīts, bet neizdodas? Kārdinājums ir ļaut izņēmumam izplatīties tālāk; tā ir kļūda, jo tas pārtrauc aģenta ciklu. Tā vietā atgriez skaidru kļūdas ziņojumu, ko modelis var nolasīt un interpretēt.
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)}"
})
Katrs zars formatē ziņojumu valodā, ko modelis saprot. Noildzes gadījumā aģents mēģinās veikt vēl vienu izsaukumu; HTTP 404 kļūdas gadījumā tas informēs lietotāju vai mainīs pieeju, nevis turpinās akli.
Strukturēta izeja rīkiem
Šis ierobežojums attiecas arī uz gala izvadi. Izmantojot output_type, final_output vairs nav teksts, kas jāparsē, bet gan tipēts objekts, ko izsaucošais kods var izmantot tieši.
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}")
Paradigma: rīki ar kopīgu kontekstu
Vēl viena bieži sastopama problēma: taviem rīkiem bieži ir nepieciešams kopīgs stāvoklis — lietotāja sesija, datubāzes savienojums, API atslēga — ko būtu absurdi nodot caur modeli. Konteksts to atrisina, nododot to līdzās sarunai.
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)
Rīkam nav biznesa parametru: lietotāja identitāte nāk no konteksta, nevis no modeļa. Tas ir arī drošības pasākums, jo aģents nevar apskatīt cita cilvēka profilu, mainot argumentu.
Galvenās atziņas
- Pydantic shēmas ar enum un Literal garantē izsaukumu derīgumu
- Lauku validatori pievieno biznesa validāciju virs tipu pārbaudes
- Rīkos atgriez JSON formāta kļūdas ziņojumus, nevis izsauc izņēmumus
output_typepiespiež aģentu strukturēt savu gala atbildi- Kopīgs konteksts (
RunContextWrapper) ļauj rīkiem piekļūt lietotnes stāvoklim