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

Ανατομία SDK: Agent, Runner, Tool, Guardrail

Μάθημα 5 / 25 Ενημερώθηκε 2 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Ανατομία SDK: Agent, Runner, Tool, Guardrail
  2. Agent: Διαμόρφωση
  3. Runner: Εκτέλεση
  4. Tool: Δυνατότητες
  5. Guardrail: Ασφάλεια
  6. Πώς αλληλεπιδρούν αυτά τα μέρη
  7. Βασικά σημεία

Ανατομία SDK: Agent, Runner, Tool, Guardrail

Το Agents SDK βασίζεται σε τέσσερις θεμελιώδεις έννοιες: Agent, Runner, Tool και Guardrail. Κάθε μία έχει μία και μοναδική ευθύνη. Η αλληλεπίδρασή τους—ποιος αποφασίζει, ποιος εκτελεί, ποιος δρα, ποιος ελέγχει—είναι αυτό που καθιστά το SDK ευανάγνωστο μόλις το εσωτερικεύσετε.

1

Agent — Ο εγκέφαλος

Ορίζει οδηγίες, μοντέλο, εργαλεία και guardrails. Αυτή είναι η διαμόρφωση του agent σας.

2

Runner — Η μηχανή εκτέλεσης

Συντονίζει τον βρόχο συλλογισμού: στέλνει αιτήματα, εκτελεί εργαλεία και διαχειρίζεται τις μεταβιβάσεις (handoffs).

3

Tool — Δυνατότητες

Συναρτήσεις που μπορεί να καλέσει το agent: αναζήτηση στον ιστό, εκτέλεση κώδικα, κλήσεις API και άλλα.

4

Guardrail — Ασφάλεια

Επικυρώνει τις εισόδους και τις εξόδους του agent. Αποκλείει επικίνδυνα ή άσχετα αιτήματα.

Agent: Διαμόρφωση

Η κλάση Agent είναι καθαρά δηλωτική: δεν εκτελεί τίποτα, μόνο περιγράφει. Ό,τι ορίζει τη συμπεριφορά του agent σας βρίσκεται σε ένα σημείο.

from agents import Agent, function_tool, WebSearchTool

@function_tool
def get_price(product: str) -> str:
    """Retrieves the price of a product."""
    prices = {"widget": "€29.99", "gadget": "€49.99"}
    return prices.get(product, "Unknown product")

agent = Agent(
    name="Sales Agent",
    instructions="""You are a sales agent for an online store.
    Help customers find products and learn their prices.
    Always respond in French with a professional tone.""",
    model="gpt-5.6-terra",
    tools=[get_price, WebSearchTool()],
    handoff_description="Agent specialized in selling products",
    output_type=None,  # or a Pydantic type to enforce an output format
)

Βασικές παράμετροι του Agent:

  • name: Αναγνώσιμο από τον άνθρωπο αναγνωριστικό για το agent
  • instructions: Το prompt συστήματος που ορίζει τη συμπεριφορά
  • model: Το μοντέλο προς χρήση (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
  • tools: Η λίστα των διαθέσιμων εργαλείων
  • handoff_description: Περιγραφή που χρησιμοποιείται για μεταβιβάσεις μεταξύ agents
  • output_type: Τύπος Pydantic για τη δομή της εξόδου

Runner: Εκτέλεση

Το Runner είναι η μηχανή που εκτελεί το agent σας. Διαχειρίζεται ολόκληρο τον βρόχο και διατίθεται σε τρεις λειτουργίες, ανάλογα με το πλαίσιο κλήσης σας.

from agents import Runner

# Synchronous mode (development)
result = Runner.run_sync(agent, "What is the price of the widget?")

# Asynchronous mode (production)
result = await Runner.run(agent, "What is the price of the widget?")

# Streaming mode (real time)
result = Runner.run_streamed(agent, "What is the price of the widget?")

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

result = Runner.run_sync(agent, "What is the price of the widget?")

# The agent's final response
print(result.final_output)

# The complete conversation history
print(result.to_input_list())

# The last active agent (useful with handoffs)
print(result.last_agent.name)

Tool: Δυνατότητες

Το SDK υποστηρίζει τρεις τρόπους δήλωσης εργαλείων, από τον πιο συνηθισμένο έως τον πιο αρχιτεκτονικό.

1. Εργαλεία συναρτήσεων (πιο συνηθισμένα)

Μια διακοσμημένη συνάρτηση Python γίνεται εργαλείο· το SDK εξάγει το σχήμα από την υπογραφή και το docstring.

from agents import function_tool

@function_tool
def send_email(recipient: str, subject: str, body: str) -> str:
    """Sends an email to a recipient."""
    # Your sending logic here
    return f"Email sent to {recipient}"

2. Εργαλεία που φιλοξενούνται από την OpenAI

Αυτά τα εργαλεία εκτελούνται στην πλευρά της OpenAI: εσείς δεν γράφετε τη λογική αναζήτησης ούτε το sandbox Python.

from agents import WebSearchTool, FileSearchTool, CodeInterpreterTool

tools = [
    WebSearchTool(),                               # Web search
    FileSearchTool(vector_store_ids=["vs_123"]),   # File search
    CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),                          # Code execution
]

3. Agents ως εργαλεία

Ένα agent μπορεί να χρησιμοποιήσει ένα άλλο ως εργαλείο. Ο συντονιστής παρακάτω αναθέτει την έρευνα χωρίς ποτέ να παραχωρεί τον έλεγχο της συνομιλίας, γεγονός που το διακρίνει από μια μεταβίβαση (handoff).

search_agent = Agent(
    name="Researcher",
    instructions="You look up precise information.",
    tools=[WebSearchTool()],
)

primary_agent = Agent(
    name="Coordinator",
    instructions="You coordinate research.",
    tools=[search_agent.as_tool(
        tool_name="search",
        tool_description="Performs in-depth research"
    )],
)

Guardrail: Ασφάλεια

Ένα guardrail είναι ένα agent ελέγχου που τοποθετείται μπροστά από το επιχειρηματικό σας agent. Εδώ, ένας επαληθευτής ελέγχει εάν το αίτημα εμπίπτει στις πωλήσεις πριν απαντήσει το agent πωλήσεων.

from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner

guardrail_agent = Agent(
    name="Verifier",
    instructions="Determine whether the request concerns sales. Respond true or false.",
    output_type=bool,
)

async def verify_topic(ctx, agent, input_data):
    result = await Runner.run(guardrail_agent, input_data, context=ctx)
    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=not result.final_output,
    )

protected_agent = Agent(
    name="Protected Sales Agent",
    instructions="You are a sales agent.",
    input_guardrails=[
        InputGuardrail(guardrail_function=verify_topic),
    ],
)

Εάν το guardrail ενεργοποιηθεί (tripwire_triggered=True), η εκτέλεση σταματά και εγείρεται η εξαίρεση InputGuardrailTripwireTriggered. Προγραμματίστε να την πιάσετε στην εφαρμογή σας· διαφορετικά, θα επιστρέψετε σφάλμα 500 σε έναν χρήστη που απλώς έκανε μια άσχετη ερώτηση.

Πώς αλληλεπιδρούν αυτά τα μέρη

Η πλήρης ροή εκτελείται ως εξής:

  1. Καλείτε Runner.run(agent, message)
  2. Το Runner ελέγχει τα input guardrails
  3. Το Runner στέλνει το μήνυμα στο μοντέλο του Agent
  4. Εάν το μοντέλο ζητήσει ένα εργαλείο, το Runner το εκτελεί
  5. Το Runner επιστρέφει το αποτέλεσμα στο μοντέλο (πίσω στο βήμα 3)
  6. Όταν το μοντέλο παράγει μια τελική απάντηση, το Runner ελέγχει τα output guardrails
  7. Επιστρέφεται το RunResult

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

  • Το Agent ορίζει τη συμπεριφορά (οδηγίες, μοντέλο, εργαλεία)
  • Το Runner συντονίζει την εκτέλεση του βρόχου του agent
  • Δηλώστε εργαλεία με @function_tool, ενσωματωμένες κλάσεις ή .as_tool()
  • Τα Guardrails επικυρώνουν εισόδους και εξόδους για ασφάλεια
  • Το RunResult περιέχει την τελική απάντηση και το πλήρες ιστορικό