Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Izsaukumu uzlabota pārvaldība: shēmas un validācija

Nodarbība 7 no 25 Atjaunota 2026. gada 29. jūlijs Programmētājs
Šajā lapā
  1. Izsaukumu uzlabota pārvaldība: shēmas un validācija
  2. JSON shēmas un stingrais režīms
  3. Pielāgota validācija ar Pydantic
  4. Kļūdu apstrāde rīkos
  5. Strukturēta izeja rīkiem
  6. Paradigma: rīki ar kopīgu kontekstu
  7. Galvenās atziņas

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_type piespiež aģentu strukturēt savu gala atbildi
  • Kopīgs konteksts (RunContextWrapper) ļauj rīkiem piekļūt lietotnes stāvoklim