Премини към основното съдържание
Български— Изберете език
Меню

Разширено извикване на функции: схеми и валидиране

Урок 7 от 25 Обновен 29 юли 2026 г. Програмист
На тази страница
  1. Разширено извикване на функции: схеми и валидиране
  2. JSON схеми и строг режим
  3. Персонализирано валидиране с Pydantic
  4. Обработка на грешки в инструментите
  5. Структуриран изход за инструменти
  6. Шаблон: инструменти със споделен контекст
  7. Ключови изводи

Разширено извикване на функции: схеми и валидиране

Извикването на функции е основният механизъм, който позволява на агента да решава кога и как да задейства Вашите инструменти. Декларирането на инструмент е достатъчно за прототип, но преминаването към производствена среда изисква да ограничите извикванията, да валидирате бизнес стойностите и да обработвате грешки, без да сривате агента. Това е предметът на настоящия урок.

JSON схеми и строг режим

API за отговори използва JSON схеми, за да опише параметрите за всеки инструмент, а режимът strict (строг) гарантира, че моделът се придържа точно към схемата. По-конкретно, използването на Enum или Literal затваря вратата за измислени стойности.

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

При активиран по подразбиране строг режим, моделът никога не може да изпрати невалиден приоритет или компонент извън разрешения списък. Няма да се наложи да пишете защитен бекенд код, който да превежда „спешно“ или „P1“ в стойност, разпознаваема от Вашата система за тикети.

Персонализирано валидиране с Pydantic

Проверката на типовете спира невъзможните стойности, но не и абсурдните. IBAN от петнадесет знака е напълно валиден низ; Вашата бизнес логика обаче го отхвърля. Pydantic Ви позволява да вградите тези правила директно в схемата.

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

Ограниченията gt=0 и le=50000 върху сумата играят подобна роля на различно ниво: те правят отрицателен превод или такъв, надвишаващ лимита, структурно невъзможен, независимо как потребителят формулира заявката.

Обработка на грешки в инструментите

А какво става, когато инструментът се изпълни, но се провали? Изкушението е да оставите изключението да се издигне нагоре; това е грешка, защото прекъсва цикъла на агента. Вместо това върнете ясно съобщение за грешка, което моделът може да прочете и интерпретира.

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

Всеки клон форматира съобщението на език, разбираем за модела. При изтичане на времето за изчакване агентът ще опита ново извикване; при HTTP грешка 404 той ще информира потребителя или ще промени подхода си, вместо да продължи упорито напред.

Структуриран изход за инструменти

Това ограничение важи и за крайния изход. С output_type, final_output вече не е текст за парсиране, а типизиран обект, директно използваем от извикващия код.

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

Шаблон: инструменти със споделен контекст

Един последен често срещан проблем: Вашите инструменти често се нуждаят от споделено състояние – сесия на потребител, връзка с база данни, API ключ – което би било абсурдно да се предава чрез модела. Контекстът решава това, като го предава заедно с разговора.

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)

Инструментът няма бизнес параметри: самоличността на потребителя идва от контекста, а не от модела. Това е и мярка за сигурност, тъй като агентът не може да види профила на някой друг, като промени аргумент.

Ключови изводи

  • Pydantic схемите с enums и Literals гарантират валидността на извикванията
  • Валидаторите на полета добавят бизнес валидиране върху проверката на типовете
  • Връщайте JSON съобщения за грешки вместо да хвърляте изключения в инструментите
  • output_type принуждава агента да структурира крайния си отговор
  • Споделеният контекст (RunContextWrapper) позволява на инструментите да достъпват състоянието на приложението