Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Sejħa avvanzata tal-funzjonijiet: skemi u validazzjoni

Lezzjoni 7 / 25 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Sejħa avvanzata tal-funzjonijiet: skemi u validazzjoni
  2. Skemi JSON u modalità stretta
  3. Validazzjoni personalizzata ma’ Pydantic
  4. Immaniġġjar tal-iżbalji fl-għodod
  5. Output strutturat għall-għodod
  6. Mudell: għodod b’kuntest kondiviż
  7. Punti Ewlenin

Sejħa avvanzata tal-funzjonijiet: skemi u validazzjoni

Is-sejħa tal-funzjonijiet hija l-mekkaniżmu ewlieni li jippermetti lil aġent jiddeċiedi meta u kif jinvoka l-għodod tiegħek. Li tiddikjara għodda biżżejjed għal prototip, iżda biex tgħaddi għall-produzzjoni trid tillimita s-sejħat, tivvalida valuri tan-negozju, u timmaniġġja l-fallimenti mingħajr ma twaqqaf l-aġent. Dan huwa eżattament dak li tkopri din il-lezzjoni.

Skemi JSON u modalità stretta

L-API tar-Risposti tuża skemi JSON biex tiddeskrivi l-parametri għal kull għodda, u l-modalità stretta (strict) tiggarantixxi li l-mudell jaderixxi eżattament mal-iskema. Speċifikament, l-użu ta’ Enum jew Literal jagħlaq il-bieb għal valuri inventati.

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

Bil-modalità stretta attivata b’mod predefinit, il-mudell qatt ma jista’ jibgħat prijorità invalida jew komponent barra mil-lista permessa. M’għandekx bżonn tikteb koddefensiv tal-backend biex tittraduċi “urgent” jew “P1” f’valur li s-sistema tat-tikketti tiegħek tirrikonoxxi.

Validazzjoni personalizzata ma’ Pydantic

Iċ-ċekk tat-tip iwaqqaf valuri impossibbli, mhux dawk assurdi. IBAN ta’ ħmistax-il karattru huwa string perfettament validu; il-loġika tan-negozju tiegħek tirrifjutah. Pydantic jippermettilek tħaffer dawn ir-regoli direttament fl-iskema.

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]}..."

Il-vincoli gt=0 u le=50000 fuq l-ammont jaqdu rwol simili fuq livell differenti: jagħmlu trasferiment negattiv jew wieħed li jaqbeż il-limitu strutturalment impossibbli, irrispettivament minn kif l-utent ifformula t-talba.

Immaniġġjar tal-iżbalji fl-għodod

X’jiġri meta għodda tesegwixxi iżda tfalli? It-tentazzjoni hija li tħalli l-eċċezzjoni titla’ ‘l fuq; dan huwa żball, għax jinterrompi ċ-ċiklu tal-aġent. Minflok, irritorna messaġġ ta’ żball ċar li l-mudell jista’ jaqra u jinterpreta.

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

Kull fergħa tiffurmatta l-messaġġ f’lingwa li l-mudell jifhem. F’każ ta’ timeout, l-aġent jipprova sejħa oħra; f’każ ta’ żball HTTP 404, jinforma lill-utent jew ibiddel l-approċċ minflok ma jkompli blindament.

Output strutturat għall-għodod

Dan il-vincolu japplika wkoll għall-output finali. Ma’ output_type, final_output ma jibqax test li għandu jiġi pparzat iżda oġġett ittajpjat, użabbli direttament mill-kodiċi li qed isejjaħ.

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

Mudell: għodod b’kuntest kondiviż

Aħħar kwistjoni rikorrenti: l-għodod tiegħek spiss jeħtieġu stat kondiviż—sessjoni tal-utent, konnessjoni tad-database, ċavetta API—li jkun assurdu li tgħaddih permezz tal-mudell. Il-kuntest isolvi dan billi jgħaddih flimkien mal-konversazzjoni.

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)

L-għodda m’għandha l-ebda parametru tan-negozju: l-identità tal-utent tiġi mill-kuntest, mhux mill-mudell. Din hija wkoll miżura ta’ sigurtà, peress li l-aġent ma jistax jara l-profil ta’ xi ħadd ieħor billi jbiddel argument.

Punti Ewlenin

  • L-iskemi Pydantic b’enums u Literals jiggarantixxu l-validità tas-sejħa
  • Il-validaturi tal-kamp (field validators) iżidu validazzjoni tan-negozju fuq iċ-ċekk tat-tip
  • Irritorna messaġġi ta’ żball JSON minflok ma tqajjem eċċezzjonijiet fl-għodod
  • output_type jfurza lill-aġent jistruttura r-risposta finali tiegħu
  • Il-kuntest kondiviż (RunContextWrapper) jippermetti lill-għodod jaċċessaw l-istat tal-applikazzjoni