Μεταβλητές Πλαισίου και Μνήμη Πράκτορα
Σε αυτήν τη σελίδα
Μεταβλητές Πλαισίου και Μνήμη Πράκτορα
Ένας πράκτορας χωρίς μνήμη ξεχνά τα πάντα μεταξύ των εκτελέσεων: ζητά το όνομα του πελάτη σε κάθε μήνυμα και ξεκινά από την αρχή σε κάθε γύρο. Δύο συμπληρωματικοί μηχανισμοί λύνουν αυτό το πρόβλημα. Οι μεταβλητές πλαισίου εγχέουν κοινή κατάσταση στον πράκτορα και τα εργαλεία του, ενώ η συνομιλιακή μνήμη διατηρεί τη ροή μιας συνομιλίας πολλαπλών γύρων.
Μεταβλητές Πλαισίου: Κοινή Κατάσταση
Το RunContextWrapper είναι ένα αντικείμενο με τύπο που κυκλοφορεί μεταξύ του πράκτορα, των εργαλείων του και των δικλείδων ασφαλείας του. Συγκεκριμένα, ορίζετε ένα dataclass που περιγράφει τη συνεδρία—ταυτότητα, καλάθι, προτιμήσεις—και κάθε εργαλείο το λαμβάνει ως πρώτη παράμετρο. Στο παρακάτω παράδειγμα, το ajouter_au_panier γράφει σε αυτό το αντικείμενο και το voir_panier το διαβάζει ξανά: και τα δύο εργαλεία μοιράζονται το ίδιο καλάθι χωρίς να περνά κανένα δεδομένο μέσω του prompt.
from dataclasses import dataclass, field
from agents import Agent, Runner, RunContextWrapper, function_tool
@dataclass
class SessionUtilisateur:
user_id: str
nom: str
email: str
panier: list[dict] = field(default_factory=list)
preferences: dict = field(default_factory=dict)
@function_tool
def ajouter_au_panier(
ctx: RunContextWrapper[SessionUtilisateur],
produit: str,
quantite: int = 1,
) -> str:
"""Adds a product to the user's cart."""
ctx.context.panier.append({"produit": produit, "quantite": quantite})
total = len(ctx.context.panier)
return f"{produit} (x{quantite}) added to cart. Total: {total} item(s)."
@function_tool
def voir_panier(ctx: RunContextWrapper[SessionUtilisateur]) -> str:
"""Displays the cart contents."""
if not ctx.context.panier:
return "Your cart is empty."
lignes = [f"- {item['produit']} x{item['quantite']}" for item in ctx.context.panier]
return f"Cart for {ctx.context.nom}:\n" + "\n".join(lignes)
agent = Agent(
name="Shop Agent",
instructions="You help customers with their shopping.",
tools=[ajouter_au_panier, voir_panier],
model="gpt-5.6-terra",
)
session = SessionUtilisateur(
user_id="usr_789",
nom="Marie Dupont",
email="[email protected]",
)
# Context is shared across all tools
result = Runner.run_sync(agent, "Add a laptop and two mice to my cart", context=session)
print(result.final_output)
print(f"Cart after execution: {session.panier}")
Το πλαίσιο είναι μεταβλητό: τα εργαλεία μπορούν να το τροποποιήσουν και οι αλλαγές παραμένουν μετά την εκτέλεση. Αυτό είναι που κάνει την τελευταία γραμμή ενδιαφέρουσα—μετά το run_sync, το αντικείμενο session της εφαρμογής σας περιέχει πραγματικά τα δύο αντικείμενα, έτοιμα να σταλούν στο σύστημα παραγγελιών σας.
Δυναμικές Οδηγίες
Αυτή η κατάσταση δεν εξυπηρετεί μόνο τα εργαλεία: μπορεί επίσης να διαμορφώσει τη συμπεριφορά του πράκτορα. Οι οδηγίες μπορούν να είναι μια συνάρτηση που λαμβάνει το πλαίσιο και δημιουργεί το prompt συστήματος εν κινήσει, συμπεριλαμβάνοντας το όνομα του πελάτη και την προτιμώμενη γλώσσα.
def instructions_dynamiques(ctx: RunContextWrapper[SessionUtilisateur]) -> str:
prefs = ctx.context.preferences
langue = prefs.get("langue", "français")
return f"""You are a sales assistant.
The customer's name is {ctx.context.nom}.
Their email is {ctx.context.email}.
They have {len(ctx.context.panier)} item(s) in their cart.
Communicate in {langue}."""
agent = Agent(
name="Personalized Agent",
instructions=instructions_dynamiques,
tools=[ajouter_au_panier, voir_panier],
model="gpt-5.6-terra",
)
Οι οδηγίες αξιολογούνται σε κάθε γύρο του βρόχου του πράκτορα, επιτρέποντας την εξατομίκευση σε πραγματικό χρόνο: εάν ένα εργαλείο μόλις πρόσθεσε ένα αντικείμενο, ο επόμενος γύρος το λαμβάνει αμέσως υπόψη στο prompt συστήματος.
Συνομιλιακή Μνήμη Πολλαπλών Γύρων
Το πλαίσιο μεταφέρει δεδομένα, όχι τον ίδιο τον διάλογο. Για να διατηρήσετε μια συνομιλία σε πολλαπλές ανταλλαγές, περάστε το ιστορικό. Η αρχή συνοψίζεται σε τρία βήματα: προσθέτετε το μήνυμα του χρήστη, εκτελείτε τον πράκτορα στην πλήρη λίστα και στη συνέχεια αντικαθιστάτε το ιστορικό σας με αυτό που επιστρέφεται από το αποτέλεσμα—συμπεριλαμβανομένων μηνυμάτων, κλήσεων εργαλείων και απαντήσεων.
from agents import Agent, Runner
agent = Agent(
name="Assistant",
instructions="You are an assistant that remembers the conversation.",
model="gpt-5.6-terra",
)
historique = []
async def converser(message_utilisateur: str) -> str:
# Add the user's message to the history
historique.append({"role": "user", "content": message_utilisateur})
# Run the agent with the full history
result = await Runner.run(agent, historique)
# Save new exchanges for the next turn
historique.clear()
historique.extend(result.to_input_list())
return result.final_output
# Simulate a conversation
async def demo():
print(await converser("My name is Thomas."))
print(await converser("What is my first name?")) # The agent remembers
print(await converser("Recommend a good restaurant in Paris."))
Αυτή η μνήμη ζει στη RAM. Εξαφανίζεται όταν αναπτύσσετε εκ νέου την υπηρεσία σας και αυξάνεται επ’ αόριστον εάν η συνομιλία διαρκέσει: δύο περιορισμοί που πρέπει να έχετε υπόψη πριν προχωρήσετε σε παραγωγή.
Πρότυπο: Επίμονη Μνήμη με Βάση Δεδομένων
Για μνήμη που επιβιώνει μετά από επανεκκινήσεις, αποθηκεύστε το ιστορικό σε μια βάση δεδομένων. Η προσέγγιση που παρουσιάζεται εδώ πηγαίνει ένα βήμα παραπέρα: αντί να διατηρείτε τα πάντα, ο πράκτορας αποφασίζει ο ίδιος τι αξίζει να διατηρηθεί, μέσω ενός ζεύγους εργαλείων αποθήκευσης και ανάκτησης. Ο πελάτης λέει «Είμαι αλλεργικός στα φιστίκια», ο πράκτορας καλεί το sauvegarder_note και οι πληροφορίες παραμένουν διαθέσιμες τρεις εβδομάδες αργότερα.
import json
from agents import Agent, Runner, function_tool
@function_tool
async def sauvegarder_note(ctx: RunContextWrapper, cle: str, valeur: str) -> str:
"""Saves information to remember later."""
# In production: write to database
notes = ctx.context.notes
notes[cle] = valeur
return f"Note saved: {cle} = {valeur}"
@function_tool
async def recuperer_note(ctx: RunContextWrapper, cle: str) -> str:
"""Retrieves previously saved information."""
notes = ctx.context.notes
valeur = notes.get(cle)
if valeur:
return f"{cle} = {valeur}"
return f"No note found for '{cle}'"
@dataclass
class ContexteMemoire:
user_id: str
notes: dict = field(default_factory=dict)
agent = Agent(
name="Assistant with Memory",
instructions="""You are an assistant with persistent memory.
Use sauvegarder_note to retain important information
and recuperer_note to retrieve it.""",
tools=[sauvegarder_note, recuperer_note],
model="gpt-5.6-terra",
)
Πλαίσιο έναντι Οδηγιών: Πότε να Χρησιμοποιήσετε Τι
Αυτοί οι τέσσερις μηχανισμοί επικαλύπτονται εν μέρει και το κλασικό λάθος είναι να διοχετεύετε τα πάντα μέσω των οδηγιών. Ο παρακάτω πίνακας συνοψίζει την αντιστοίχιση που πρέπει να θυμάστε.
| Ανάγκη | Λύση |
|---|---|
| Δεδομένα χρήστη (όνομα, ρόλος) | Μεταβλητές πλαισίου |
| Συμπεριφορά πράκτορα | Οδηγίες (στατικές ή δυναμικές) |
| Ιστορικό συνομιλίας | result.to_input_list() |
| Μακροπρόθεσμη μνήμη | Εργαλεία + βάση δεδομένων |
| Διαμόρφωση χρόνου εκτέλεσης | Μεταβλητές πλαισίου |
Βασικά σημεία
- Το
RunContextWrapperμεταφέρει κατάσταση με τύπο προσβάσιμη από όλα τα εργαλεία - Το πλαίσιο είναι μεταβλητό: τα εργαλεία μπορούν να το τροποποιήσουν κατά την εκτέλεση
- Οι δυναμικές οδηγίες (συναρτήσεις) προσαρμόζονται στο πλαίσιο σε κάθε γύρο
- Το ιστορικό συνομιλίας διατηρείται με το
result.to_input_list() - Για επίμονη μνήμη, συνδυάστε εργαλεία αποθήκευσης με μια βάση δεδομένων