Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Προηγμένη κλήση συναρτήσεων: σχήματα και επικύρωση

Μάθημα 7 / 25 Ενημερώθηκε 29 Ιουλίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Προηγμένη κλήση συναρτήσεων: σχήματα και επικύρωση
  2. Σχήματα JSON και αυστηρή λειτουργία
  3. Προσαρμοσμένη επικύρωση με Pydantic
  4. Διαχείριση σφαλμάτων στα εργαλεία
  5. Δομημένη έξοδος για εργαλεία
  6. Πρότυπο: Εργαλεία με κοινό πλαίσιο
  7. Βασικά σημεία

Προηγμένη κλήση συναρτήσεων: σχήματα και επικύρωση

Η κλήση συναρτήσεων αποτελεί τον κεντρικό μηχανισμό που επιτρέπει σε έναν πράκτορα να αποφασίζει πότε και πώς θα ενεργοποιήσει τα εργαλεία σας. Η δήλωση ενός εργαλείου αρκεί για ένα πρωτότυπο, αλλά η μετάβαση σε περιβάλλον παραγωγής απαιτεί τον περιορισμό των κλήσεων, την επικύρωση των επιχειρηματικών τιμών και τον χειρισμό σφαλμάτων χωρίς να διακόπτεται η λειτουργία του πράκτορα. Αυτό ακριβώς καλύπτει το παρόν μάθημα.

Σχήματα JSON και αυστηρή λειτουργία

Το API Responses χρησιμοποιεί σχήματα 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})"

Με την αυστηρή λειτουργία ενεργοποιημένη από προεπιλογή, το μοντέλο δεν μπορεί ποτέ να στείλει μη έγκυρη προτεραιότητα ή στοιχείο εκτός της επιτρεπόμενης λίστας. Δεν θα χρειαστεί να γράψετε αμυντικό κώδικα backend για να μεταφράσετε τιμές όπως “urgent” ή “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)}"
        })

Κάθε κλάδος διαμορφώνει το μήνυμα σε μια γλώσσα που κατανοεί το μοντέλο. Σε περίπτωση χρονικού ορίου (timeout), ο πράκτορας θα επιχειρήσει νέα κλήση· σε περίπτωση σφάλματος HTTP 404, θα ενημερώσει τον χρήστη ή θα αλλάξει προσέγγιση, αντί να επιμένει τυφλά.

Δομημένη έξοδος για εργαλεία

Αυτός ο περιορισμός ισχύει και για την τελική έξοδο. Με το output_type, το final_output δεν είναι πλέον κείμενο προς ανάλυση, αλλά ένα αντικείμενο με τύπο, άμεσα usable από τον κώδικα που κάνει την κλήση.

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

Πρότυπο: Εργαλεία με κοινό πλαίσιο

Ένα τελευταίο επαναλαμβανόμενο ζήτημα: τα εργαλεία σας συχνά χρειάζονται κοινή κατάσταση— sessione χρήστη, σύνδεση βάσης δεδομένων, κλειδί API— την οποία θα ήταν παράλογο να περάσετε μέσω του μοντέλου. Το πλαίσιο (context) λύνει αυτό το πρόβλημα, περνώντας τα δεδομένα μαζί με τη συνομιλία.

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) επιτρέπει στα εργαλεία να αποκτούν πρόσβαση στην κατάσταση της εφαρμογής