Przejdź do głównej treści
Polski— Wybierz język
Menu

Zaawansowane wywoływanie funkcji: schematy i walidacja

Lekcja 7 z 25 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Zaawansowane wywoływanie funkcji: schematy i walidacja
  2. Schematy JSON i tryb ścisły
  3. Niestandardowa walidacja z Pydantic
  4. Obsługa błędów w narzędziach
  5. Strukturyzowane wyjście dla narzędzi
  6. Wzorzec: narzędzia ze wspólnym kontekstem
  7. Kluczowe wnioski

Zaawansowane wywoływanie funkcji: schematy i walidacja

Wywoływanie funkcji to mechanizm, dzięki któremu agent decyduje, kiedy i jak użyć Twoich narzędzi. Zdefiniowanie narzędzia wystarczy do prototypu, ale wdrożenie produkcyjne wymaga ograniczenia wywołań, walidacji danych biznesowych i obsługi błędów bez awarii agenta. Właśnie tym zajmiemy się w tej lekcji.

Schematy JSON i tryb ścisły

API Responses używa schematów JSON do opisu parametrów każdego narzędzia, a tryb strict (ścisły) gwarantuje, że model będzie ściśle przestrzegał schematu. Użycie Enum lub Literal skutecznie blokuje możliwość generowania wymyślonych wartości.

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

Dzięki domyślnie włączonemu trybowi ścisłemu model nigdy nie prześle nieprawidłowego priorytetu ani komponentu spoza dozwolonej listy. Nie musisz pisać defensywnego kodu backendowego, który tłumaczyłby słowa „urgent“ czy „P1“ na wartości rozpoznawane przez Twój system zgłoszeń.

Niestandardowa walidacja z Pydantic

Sprawdzanie typów blokuje wartości niemożliwe, ale nie absurdalne. IBAN składający się z piętnastu znaków jest poprawnym ciągiem znaków, ale Twoja logika biznesowa go odrzuci. Pydantic pozwala osadzić te reguły bezpośrednio w schemacie.

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

Ograniczenia gt=0 i le=50000 dla kwoty pełnią podobną rolę na innym poziomie: sprawiają, że przelew ujemny lub przekraczający limit jest strukturalnie niemożliwy, niezależnie od tego, jak użytkownik sformułuje prośbę.

Obsługa błędów w narzędziach

Co zrobić, gdy narzędzie zostanie wykonane, ale zakończy się niepowodzeniem? Pokusa, by pozwolić wyjątkowi propagate się w górę, jest duża, ale to błąd, ponieważ przerywa pętlę działania agenta. Zamiast tego zwróć czytelny komunikat o błędzie, który model może odczytać i zinterpretować.

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

Każda gałąź formatuje wiadomość w języku zrozumiałym dla modelu. W przypadku przekroczenia czasu oczekiwania agent spróbuje ponownego wywołania; w przypadku błędu HTTP 404 poinformuje użytkownika lub zmieni podejście, zamiast działać w ślepo.

Strukturyzowane wyjście dla narzędzi

To ograniczenie dotyczy również końcowego wyniku. Dzięki output_type, final_output nie jest już tekstem do parsowania, lecz typowanym obiektem, gotowym do bezpośredniego użycia przez kod wywołujący.

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

Wzorzec: narzędzia ze wspólnym kontekstem

Ostatni często pojawiający się problem: narzędzia często potrzebują wspólnego stanu – sesji użytkownika, połączenia z bazą danych, klucza API – którego przekazywanie przez model byłoby absurdalne. Kontekst rozwiązuje ten problem, przekazując te dane wraz z konwersacją.

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)

Narzędzie nie przyjmuje parametrów biznesowych: tożsamość użytkownika pochodzi z kontekstu, a nie od modelu. Jest to również środek bezpieczeństwa, ponieważ agent nie może wyświetlić profilu innej osoby, zmieniając argument.

Kluczowe wnioski

  • Schematy Pydantic z enumeracjami i Literals gwarantują poprawność wywołań
  • Walidatory pól dodają walidację biznesową ponad sprawdzanie typów
  • Zwracaj komunikaty o błędach w formacie JSON zamiast zgłaszać wyjątki w narzędziach
  • output_type wymusza na agencie strukturyzowanie końcowej odpowiedzi
  • Wspólny kontekst (RunContextWrapper) pozwala narzędziom uzyskiwać dostęp do stanu aplikacji