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

Ιχνηλάτηση και Παρατηρησιμότητα

Μάθημα 14 / 25 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Ιχνηλάτηση και Παρατηρησιμότητα
  2. Ενσωματωμένη Ιχνηλάτηση
  3. Ονοματοδοσία Ιχνηλατήσεων
  4. Ανάλυση μιας Ροής Εργασίας σε Βήματα
  5. Προσαρμοσμένοι Επεξεργαστές Ιχνηλάτησης
  6. Εξαγωγή σε Εξωτερικά Συστήματα
  7. Μην Χάσετε τις Τελευταίες Ιχνηλατήσεις
  8. Απενεργοποίηση Ιχνηλάτησης
  9. Βασικές Μετρικές για Παρακολούθηση
  10. Βασικά σημεία

Ενημερώθηκε στις 3 Νοεμβρίου 2026. Οι επεξεργαστές ιχνηλάτησης διάβαζαν προηγουμένως τα trace.start_time, trace.end_time και span.name, τα οποία δεν υπάρχουν στο SDK: μια ιχνηλάτηση δεν έχει χρονοσήμα, και ένα span περιέχει τα started_at, ended_at και span_data. Ο επεξεργαστής εξαγωγής δεν υλοποιούσε τη μέθοδο on_trace_start, η οποία είναι αφηρημένη: η δημιουργία στιγμιότυπού της προκαλούσε TypeError. Οι «εμφωλευμένες ιχνηλατήσεις» δημιουργούσαν μια νέα ιχνηλάτηση μέσα σε μια άλλη, κάτι που το SDK επισημαίνει ως πιθανό σφάλμα: τα βήματα χρησιμοποιούν πλέον το custom_span(). Προσθήκες: flush_traces(), διαχείριση ευαίσθητων δεδομένων και Μηδενική Διατήρηση Δεδομένων (Zero Data Retention). Κώδικας επαληθευμένος με το openai-agents 0.24.0. Πηγές: Tracing (τεκμηρίωση SDK) · openai-agents-python.

Ιχνηλάτηση και Παρατηρησιμότητα

Ένας πράκτορας σε περιβάλλον παραγωγής είναι ένα «μαύρο κουτί» αν δεν ιχνηλατείτε τις ενέργειές του. Όταν ένας πελάτης παραπονιέται για μια παράλογη απάντηση, δεν έχετε ούτε το ακριβές αίτημα, ούτε τα εργαλεία που κλήθηκαν, ούτε τις τιμές που επέστρεψαν. Η ιχνηλάτηση του SDK καταγράφει κάθε βήμα της εκτέλεσης: κλήσεις μοντέλων, χρήση εργαλείων, μεταβιβάσεις (handoffs) και δικλείδες ασφαλείας (guardrails). Αυτό είναι το κύριο εργαλείο σας για την αποσφαλμάτωση, τη βελτιστοποίηση και τον έλεγχο των πρακτόρων σας.

Ενσωματωμένη Ιχνηλάτηση

Τα καλά νέα: δεν χρειάζεται να ενεργοποιήσετε τίποτα. Το SDK ιχνηλατεί αυτόματα κάθε εκτέλεση και, από προεπιλογή, στέλνει τις ιχνηλατήσεις στον πίνακα ελέγχου της OpenAI στο platform.openai.com. Ο παρακάτω πράκτορας, γραμμένος χωρίς καμία οδηγία ιχνηλάτησης, παράγει ήδη μια usable ιχνηλάτηση.

from agents import Agent, Runner, function_tool

@function_tool
def search_product(name: str) -> str:
    """Searches for a product in the catalog."""
    return f"Product found: {name}, price €29.99"

agent = Agent(
    name="Shop Agent",
    instructions="You help customers find products.",
    tools=[search_product],
    model="gpt-5.6-terra",
)

# Κάθε εκτέλεση δημιουργεί αυτόματα μια ιχνηλάτηση
result = Runner.run_sync(agent, "Search for the pro laptop")

Επισκεφθείτε τον πίνακα ελέγχου για να δείτε την πλήρη ιχνηλάτηση: διάρκεια, tokens που καταναλώθηκαν, εργαλεία που κλήθηκαν και την τελική απάντηση.

Ονοματοδοσία Ιχνηλατήσεων

Μετά από μερικές εκατοντάδες εκτελέσεις, ο πίνακας ελέγχου μετατρέπεται σε μια αδιάκριτη λίστα. Δώστε στις ιχνηλατήσεις σας ονόματα με νόημα ώστε να τις βρίσκετε εύκολα· ένα όνομα επιχειρηματικής ροής είναι καλύτερο από ένα τεχνικό ID.

from agents import trace

with trace("premium-customer-order"):
    result = await Runner.run(
        agent,
        "I want to order 5 laptops for my team",
    )

Το όνομα της ιχνηλάτησης εμφανίζεται στον πίνακα ελέγχου και διευκολύνει τη φιλτραρίσματος.

Ανάλυση μιας Ροής Εργασίας σε Βήματα

Για μια ροή εργασίας με πολλαπλές κλήσεις, ανοίξτε μία ιχνηλάτηση γύρω από ολόκληρη τη διαδικασία και στη συνέχεια σημειώστε κάθε βήμα με custom_span(). Μην εμφωλεύετε ένα trace() μέσα σε ένα άλλο: το SDK θα καταγράψει τότε την προειδοποίηση Trace already exists. Creating a new trace, but this is probably a mistake. Τα spans, ωστόσο, έχουν σχεδιαστεί για να εμφωλεύονται: το καθένα τοποθετείται κάτω από το τρέχον span.

from agents import Runner, custom_span, trace


async def process_order(message: str, conversation_id: str):
    with trace("order-workflow", group_id=conversation_id):
        with custom_span("step-1-understanding"):
            result_understanding = await Runner.run(triage_agent, message)

        with custom_span("step-2-processing"):
            result_processing = await Runner.run(
                order_agent,
                result_understanding.to_input_list(),
            )

        with custom_span("step-3-confirmation", data={"step": 3}):
            result_final = await Runner.run(
                confirmation_agent,
                result_processing.to_input_list(),
            )

    return result_final.final_output

Στον πίνακα ελέγχου, η ιχνηλάτηση order-workflow εμφανίζει τα τρία βήματα, και κάτω από το καθένα, τα αυτόματα spans εκτέλεσης: πράκτορας, κλήσεις μοντέλου, εργαλεία. Το group_id συνδέει ιχνηλατήσεις από την ίδια συνομιλία, χρησιμοποιώντας για παράδειγμα το thread ID σας.

Από προεπιλογή, το SDK τυλίγει κάθε Runner.run() σε μια ιχνηλάτηση με όνομα Agent workflow, και μέσα στις ιχνηλατήσεις περιλαμβάνονται ο πράκτορας, κάθε δημιουργία μοντέλου, κάθε κλήση συνάρτησης, οι δικλείδες ασφαλείας και οι μεταβιβάσεις. Για μια πιο συμπαγή ιεραρχία, η τεκμηρίωση προτείνει την περικοπή των αυτόματων spans εργασιών και γύρων:

from agents import RunConfig

result = await Runner.run(
    agent,
    "Hello",
    run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)

Προσαρμοσμένοι Επεξεργαστές Ιχνηλάτησης

Ο πίνακας ελέγχου της OpenAI είναι βολικός, αλλά η ομάδα λειτουργιών σας πιθανότατα παρακολουθεί τα πάντα αλλού. Για να στείλετε ιχνηλατήσεις στο δικό σας σύστημα, γράψτε έναν επεξεργαστή: αυτός λαμβάνει γεγονότα έναρξης και λήξης, τόσο για την πλήρη ιχνηλάτηση όσο και για κάθε span. Και οι έξι μέθοδοι του TracingProcessor είναι αφηρημένες: πρέπει να τις υλοποιήσετε όλες, έστω και κενές, διαφορετικά η δημιουργία στιγμιότυπου θα αποτύχει.

Ορίστε τι εκθέτει πραγματικά κάθε αντικείμενο: μια ιχνηλάτηση έχει trace_id και name, και η μέθοδος export() της επιστρέφει επίσης group_id και metadata· δεν έχει χρονοσήμα. Ένα span έχει span_id, trace_id, parent_id, started_at και ended_at (συμβολοσειρές ISO 8601), και span_data, του οποίου το χαρακτηριστικό type είναι agent, generation, function, handoff, guardrail, custom κ.ο.κ. Επομένως, η διάρκεια της ιχνηλάτησης μετριέται μέσα στον επεξεργαστή.

import time
from datetime import datetime
from typing import Any

from agents import add_trace_processor
from agents.tracing import Span, Trace, TracingProcessor


class MyTraceProcessor(TracingProcessor):
    def __init__(self) -> None:
        self._starts: dict[str, float] = {}

    def on_trace_start(self, trace: Trace) -> None:
        self._starts[trace.trace_id] = time.monotonic()
        print(f"[TRACE START] {trace.name} - {trace.trace_id}")

    def on_trace_end(self, trace: Trace) -> None:
        duration = time.monotonic() - self._starts.pop(trace.trace_id, time.monotonic())
        print(f"[TRACE END] {trace.name} - duration: {duration:.2f} s")

    def on_span_start(self, span: Span[Any]) -> None:
        print(f"  [SPAN START] {span.span_data.type}")

    def on_span_end(self, span: Span[Any]) -> None:
        if span.started_at and span.ended_at:
            duration = datetime.fromisoformat(span.ended_at) - datetime.fromisoformat(span.started_at)
            print(f"  [SPAN END] {span.span_data.type} - {duration.total_seconds():.2f} s")

    def shutdown(self) -> None:
        pass

    def force_flush(self) -> None:
        pass


add_trace_processor(MyTraceProcessor())

Το add_trace_processor() προσθέτει τον επεξεργαστή σας στον αρχικό: οι ιχνηλατήσεις συνεχίζουν να πηγαίνουν στον πίνακα ελέγχου της OpenAI. Το set_trace_processors() αντικαθιστά τους προεπιλεγμένους επεξεργαστές: τίποτα δεν πηγαίνει πλέον στην OpenAI, εκτός αν βάλετε εσείς τον εξαγωγέα της πίσω στη λίστα.

Εξαγωγή σε Εξωτερικά Συστήματα

Για ένα εργαλείο παρατηρησιμότητας, χρειάζεται απλώς να αναδιαμορφώσετε τα spans. Το παρακάτω παράδειγμα γράφει μία γραμμή JSON ανά ολοκληρωμένο span, μια μορφή που οι περισσότεροι συλλέκτες καταγραφών γνωρίζουν πώς να ingest· το span.export() παρέχει ήδη ένα πλήρες λεξικό.

import json
import logging
from typing import Any

from agents.tracing import Span, Trace, TracingProcessor

logger = logging.getLogger("agent-traces")


class JsonExportProcessor(TracingProcessor):
    """Writes each finished span as JSON, for a log collector."""

    def on_trace_start(self, trace: Trace) -> None:
        pass

    def on_trace_end(self, trace: Trace) -> None:
        logger.info(json.dumps(trace.export(), default=str))

    def on_span_start(self, span: Span[Any]) -> None:
        pass

    def on_span_end(self, span: Span[Any]) -> None:
        logger.info(json.dumps(span.export(), default=str))

    def shutdown(self) -> None:
        pass

    def force_flush(self) -> None:
        pass

Προσέξτε τι εξάγετε: από προεπιλογή, τα spans δημιουργίας περιέχουν εισόδους και εξόδους του μοντέλου, και τα spans συναρτήσεων περιέχουν ορίσματα εργαλείων και αποτελέσματα. Για να τα αποκλείσετε, περάστε RunConfig(trace_include_sensitive_data=False) ή ορίστε τη μεταβλητή περιβάλλοντος OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Για έτοιμες ενσωματώσεις, η τεκμηρίωση του SDK παραθέτει πολλά εργαλεία τρίτων που παρέχουν τον δικό τους επεξεργαστή.

Μην Χάσετε τις Τελευταίες Ιχνηλατήσεις

Ο προεπιλεγμένος εξαγωγέας στέλνει ιχνηλατήσεις στο παρασκήνιο, κάθε λίγα δευτερόλεπτα. Σε έναν worker που επεξεργάζεται εργασίες και δεν σταματά, ή σε ένα σύντομο script, καλέστε το flush_traces() μετά το κλείσιμο της ιχνηλάτησης για να αναγκάσετε την αποστολή:

from agents import flush_traces

with trace("nightly-processing"):
    await Runner.run(agent, "Summarize today's tickets")
flush_traces()  # μετά το τέλος της ιχνηλάτησης, ποτέ στη μέση

Απενεργοποίηση Ιχνηλάτησης

Υπάρχει μία περίπτωση όπου η ιχνηλάτηση εμποδίζει περισσότερο από ό,τι βοηθά: μια σουίτα δοκιμών που εκτελεί εκατοντάδες ψεύτικους πράκτορες και μολύνει τον πίνακα ελέγχου σας. Στις δοκιμές ή κατά την τοπική ανάπτυξη, μπορείτε επομένως να την απενεργοποιήσετε, είτε globally είτε για μία μόνο εκτέλεση.

from agents import RunConfig, set_tracing_disabled

# Απενεργοποίηση πλήρως (ή μεταβλητή περιβάλλοντος OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)

# Ή για μία μόνο εκτέλεση
result = await Runner.run(agent, "Test message", run_config=RunConfig(tracing_disabled=True))

Ένα τελευταίο σημείο, αυτό συμβατικό: σύμφωνα με την τεκμηρίωση, η ιχνηλάτηση προς την OpenAI δεν είναι διαθέσιμη για οργανισμούς που υπόκεινται σε πολιτική Μηδενικής Διατήρησης Δεδομένων (Zero Data Retention). Σε αυτή την περίπτωση, μόνο ο δικός σας επεξεργαστής, εγκατεστημένος με set_trace_processors(), θα σας παρέχει ιχνηλατήσεις.

Βασικές Μετρικές για Παρακολούθηση

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

Τα άλλα τρία αφορούν την ποιότητα. Το ποσοστό αποτυχίας εργαλείων, το ποσοστό των εργαλείων που επιστρέφουν σφάλμα, αποκαλύπτει ένα ασταθές API τρίτου μέρους ή κακώς δημιουργημένα ορίσματα. Το ποσοστό ενεργοποίησης δικλείδων ασφαλείας, ορατό στα spans guardrail, μετρά τη συχνότητα των αποκλεισμών: μια ξαφνική αύξηση σηματοδοτεί είτε μια επίθεση είτε μια δικλείδα ασφαλείας που έχει γίνει υπερβολικά αυστηρή. Τέλος, η κατανομή μεταβιβάσεων σας λέει ποιος πράκτορας απαντά συχνότερα—και κατά συνέπεια εάν η διαλογή σας στέλνει τα αιτήματα εκεί που πρέπει.

Βασικά σημεία

  • Το SDK ιχνηλατεί αυτόματα κάθε εκτέλεση στον πίνακα ελέγχου της OpenAI (εκτός από οργανισμούς με πολιτική Zero Data Retention)
  • Μία trace() ανά ροή εργασίας· σημειώστε τα βήματα με custom_span() και χρησιμοποιήστε group_id για να συνδέσετε ιχνηλατήσεις από μια συνομιλία
  • Μια ιχνηλάτηση δεν έχει χρονοσήμα· ένα span έχει started_at, ended_at και span_data.type
  • Ένα TracingProcessor υλοποιεί τις έξι μεθόδους του· το add_trace_processor() προσθέτει, το set_trace_processors() αντικαθιστά
  • Το trace_include_sensitive_data=False αποκλείει εισόδους και εξόδους· το flush_traces() αναγκάζει την αποστολή
  • Απενεργοποιήστε την ιχνηλάτηση στις δοκιμές με set_tracing_disabled(True) ή RunConfig(tracing_disabled=True)