Salt la conținutul principal
Română— Alege o limbă
Meniu

Apelarea avansată de funcții: scheme și validare

Lecția 7 din 25 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Apelarea avansată de funcții: scheme și validare
  2. Scheme JSON și modul strict
  3. Validare personalizată cu Pydantic
  4. Gestionarea erorilor în instrumente
  5. Ieșire structurată pentru instrumente
  6. Model: instrumente cu context partajat
  7. Puncte cheie

Apelarea avansată de funcții: scheme și validare

Apelarea de funcții reprezintă mecanismul central care permite unui agent să decidă când și cum să invoce instrumentele dumneavoastră. Declararea unui instrument este suficientă pentru un prototip, însă trecerea la producție necesită constrângerea apelurilor, validarea valorilor comerciale și gestionarea erorilor fără a bloca agentul. Acesta este subiectul acestei lecții.

Scheme JSON și modul strict

API-ul Responses utilizează scheme JSON pentru a descrie parametrii fiecărui instrument, iar modul strict garantează că modelul respectă exact schema. În mod specific, utilizarea unui Enum sau a unui Literal elimină posibilitatea generării de valori inventate.

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})"

Cu modul strict activat implicit, modelul nu poate trimite niciodată o prioritate invalidă sau o componentă care nu se află în lista permisă. Nu va fi nevoie să scrieți cod defensiv în backend pentru a traduce „urgent“ sau „P1“ într-o valoare recunoscută de sistemul dumneavoastră de ticketing.

Validare personalizată cu Pydantic

Verificarea tipurilor oprește valorile imposibile, nu și pe cele absurde. Un IBAN de cincisprezece caractere este un șir perfect valid; logica dumneavoastră de afaceri este cea care îl respinge. Pydantic vă permite să încorporați aceste reguli direct în 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]}..."

Constrângerile gt=0 și le=50000 aplicate sumei joacă un rol similar la un nivel diferit: ele fac imposibilă structural o transfer negativ sau unul care depășește limita, indiferent de modul în care utilizatorul formulează cererea.

Gestionarea erorilor în instrumente

Ce se întâmplă când un instrument se execută, dar eșuează? Tentația este de a lăsa excepția să se propage; aceasta este o greșeală, deoarece întrerupe bucla agentului. În schimb, returnați un mesaj de eroare clar pe care modelul îl poate citi și interpreta.

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)}"
        })

Fiecare ramură formatează mesajul într-un limbaj pe care modelul îl înțelege. În cazul unui timeout, agentul va încerca un nou apel; în cazul unei erori HTTP 404, acesta va informa utilizatorul sau va schimba abordarea, în loc să persiste orbește.

Ieșire structurată pentru instrumente

Această constrângere se aplică și rezultatului final. Cu output_type, final_output nu mai este un text de parsat, ci un obiect tipat, utilizabil direct de către codul apelant.

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}")

Model: instrumente cu context partajat

O ultimă problemă recurentă: instrumentele dumneavoastră au adesea nevoie de o stare partajată – sesiunea utilizatorului, conexiunea la baza de date, cheia API – pe care ar fi absurd să o transmiteți prin intermediul modelului. Contextul rezolvă această problemă prin transmiterea sa alături de conversație.

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)

Instrumentul nu are parametri de afaceri: identitatea utilizatorului provine din context, nu de la model. Aceasta este, de asemenea, o măsură de securitate, deoarece agentul nu poate vizualiza profilul altei persoane modificând un argument.

Puncte cheie

  • Schemele Pydantic cu enum-uri și Literals garantează validitatea apelurilor
  • Validatorii de câmp adaugă validare de afaceri peste verificarea tipurilor
  • Returnați mesaje de eroare JSON în loc să aruncați excepții în instrumente
  • output_type forțează agentul să structureze răspunsul final
  • Contextul partajat (RunContextWrapper) permite instrumentelor să acceseze starea aplicației