Napredno klicanje funkcij: sheme in preverjanje veljavnosti
Na tej strani
Napredno klicanje funkcij: sheme in preverjanje veljavnosti
Klicanje funkcij je osrednji mehanizem, ki agentu omogoča, da se odloči, kdaj in kako uporabiti vaša orodja. Za prototip je dovolj, da orodje le deklarirate, vendar prehod v proizvodno okolje zahteva omejevanje klicev, preverjanje poslovnih vrednosti in obravnavo napak brez rušenja agenta. Prav to obravnava ta lekcija.
JSON sheme in strogi način
API za odzive uporablja JSON sheme za opis parametrov vsakega orodja, način strict (strogo) pa zagotavlja, da se model natančno drži sheme. Uporaba Enum ali Literal zapre vrata izmišljenim vrednostim.
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})"
Ko je strogi način privzeto omogočen, model nikoli ne more poslati neveljavne prioritete ali komponente zunaj dovoljenega seznama. Ne boste morali pisati obrambne kode na strani strežnika, ki bi prevajala izraze, kot sta „urgent” ali „P1”, v vrednosti, ki jih vaš sistem za izdajo kartic prepozna.
Prilagojeno preverjanje veljavnosti s Pydanticom
Preverjanje tipov prepreči nemogoče vrednosti, ne pa tudi absurdnih. Petnajstznakovni IBAN je popolnoma veljaven niz; vaša poslovna logika ga zavrne. Pydantic vam omogoča, da ta pravila vgradite neposredno v shemo.
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]}..."
Omejitvi gt=0 in le=50000 pri znesku igrata podobno vlogo na drugi ravni: negativni prenos ali prenos, ki presega omejitev, sta strukturno nemogoča, ne glede na to, kako uporabnik oblikuje zahtevo.
Obravnava napak v orodjih
Kaj pa, ko se orodje izvede, a ne uspe? Napeljuje vas, da pustite izjemo priti na površje; to je napaka, saj prekine zanko agenta. Namesto tega vrnite jasno sporočilo o napaki, ki ga model lahko prebere in razume.
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)}"
})
Vsaka veja oblikuje sporočilo v jeziku, ki ga model razume. Ob časovni omejitvi bo agent poskusil ponovni klic; ob napaki HTTP 404 bo obvestil uporabnika ali spremenil pristop, namesto da bi slepo vztrajal.
Strukturirani izhod za orodja
Ta omejitev velja tudi za končni izhod. Z output_type final_output ni več besedilo za razčlenjevanje, temveč tipiziran objekt, ki ga kličoča koda lahko neposredno uporabi.
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}")
Vzorec: orodja s skupnim kontekstom
Še ena pogosta težava: vaša orodja pogosto potrebujejo skupno stanje – sejo uporabnika, povezavo z bazo podatkov, ključ API – ki bi bilo absurdno posredovati prek modela. Kontekst to reši tako, da ga posreduje skupaj s pogovorom.
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)
Orodje nima poslovnih parametrov: identiteta uporabnika izvira iz konteksta, ne iz modela. To je tudi varnostni ukrep, saj agent ne more videti profila nekoga drugega s spremembo argumenta.
Ključne ugotovitve
- Sheme Pydantic z enumeracijami in Literals zagotavljajo veljavnost klicev
- Validatorji polj dodajo poslovno preverjanje veljavnosti poleg preverjanja tipov
- V orodjih vračajte sporočila o napakah v formatu JSON namesto metanja izjem
output_typeprisili agenta, da strukturira svoj končni odgovor- Skupni kontekst (
RunContextWrapper) omogoča orodjem dostop do stanja aplikacije