Kontextvariablen und Agenten-Gedächtnis
Auf dieser Seite
Kontextvariablen und Agenten-Gedächtnis
Ein Agent ohne Gedächtnis vergisst zwischen den Ausführungen alles: er fragt in jeder Nachricht nach dem Namen des Kunden und beginnt bei jedem Turn von vorne. Zwei komplementäre Mechanismen beheben dies. Kontextvariablen injizieren einen gemeinsamen Zustand in den Agenten und seine Werkzeuge, während konversationelles Gedächtnis den Faden einer mehrstufigen Konversation aufrechterhält.
Kontextvariablen: Gemeinsamer Zustand
RunContextWrapper ist ein typisiertes Objekt, das zwischen dem Agenten, seinen Werkzeugen und seinen Sicherheitsgrenzen zirkuliert. Konkret definieren Sie eine Dataclass, die die Sitzung beschreibt – Identität, Warenkorb, Präferenzen – und jedes Werkzeug erhält es als ersten Parameter. Im folgenden Beispiel schreibt ajouter_au_panier in dieses Objekt und voir_panier liest es zurück: beide Werkzeuge teilen denselben Warenkorb, ohne dass Daten durch den Prompt fließen.
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:
"""Fügt ein Produkt zum Warenkorb des Benutzers hinzu."""
ctx.context.panier.append({"produit": produit, "quantite": quantite})
total = len(ctx.context.panier)
return f"{produit} (x{quantite}) zum Warenkorb hinzugefügt. Gesamt: {total} Artikel."
@function_tool
def voir_panier(ctx: RunContextWrapper[SessionUtilisateur]) -> str:
"""Zeigt den Inhalt des Warenkorbs an."""
if not ctx.context.panier:
return "Ihr Warenkorb ist leer."
lignes = [f"- {item['produit']} x{item['quantite']}" for item in ctx.context.panier]
return f"Warenkorb für {ctx.context.nom}:\n" + "\n".join(lignes)
agent = Agent(
name="Shop Agent",
instructions="Sie helfen Kunden beim Einkaufen.",
tools=[ajouter_au_panier, voir_panier],
model="gpt-5.6-terra",
)
session = SessionUtilisateur(
user_id="usr_789",
nom="Marie Dupont",
email="[email protected]",
)
# Kontext wird von allen Werkzeugen geteilt
result = Runner.run_sync(agent, "Fügen Sie einen Laptop und zwei Mäuse in meinen Warenkorb hinzu", context=session)
print(result.final_output)
print(f"Warenkorb nach Ausführung: {session.panier}")
Der Kontext ist veränderbar: Werkzeuge können ihn modifizieren, und Änderungen bleiben nach der Ausführung bestehen. Das macht die letzte Zeile interessant: Nach run_sync enthält Ihr Anwendungsobjekt session tatsächlich die beiden Artikel und ist bereit, an Ihr Bestellsystem gesendet zu werden.
Dynamische Anweisungen
Dieser Zustand dient nicht nur Werkzeugen: Er kann auch das Verhalten des Agenten prägen. Anweisungen können eine Funktion sein, die den Kontext empfängt und den Systemprompt dynamisch erstellt, einschließlich des Kunden-Namens und der bevorzugten Sprache.
def instructions_dynamiques(ctx: RunContextWrapper[SessionUtilisateur]) -> str:
prefs = ctx.context.preferences
langue = prefs.get("langue", "français")
return f"""Sie sind ein Verkaufsassistent.
Der Name des Kunden ist {ctx.context.nom}.
Ihre E-Mail-Adresse ist {ctx.context.email}.
Sie haben {len(ctx.context.panier)} Artikel(n) in ihrem Warenkorb.
Kommunizieren Sie in {langue}."""
agent = Agent(
name="Personalisierter Agent",
instructions=instructions_dynamiques,
tools=[ajouter_au_panier, voir_panier],
model="gpt-5.6-terra",
)
Anweisungen werden bei jedem Turn des Agenten-Loops ausgewertet, was Echtzeit-Personalisierung ermöglicht: Wenn ein Werkzeug gerade einen Artikel hinzugefügt hat, berücksichtigt das nächste Turn dies sofort im Systemprompt.
Mehrstufiges konversationelles Gedächtnis
Kontext trägt Daten, nicht den Dialog selbst. Um eine Konversation über mehrere Austausche hinweg aufrechtzuerhalten, übergeben Sie die Historie. Das Prinzip lässt sich auf drei Schritte herunterbrechen: Sie fügen die Nachricht des Benutzers hinzu, Sie führen den Agenten auf der vollständigen Liste aus und ersetzen Ihre Historie dann durch die vom Ergebnis zurückgegebene – einschließlich Nachrichten, Werkzeugaufrufe und Antworten.
from agents import Agent, Runner
agent = Agent(
name="Assistent",
instructions="Sie sind ein Assistent, der sich an die Konversation erinnert.",
model="gpt-5.6-terra",
)
historique = []
async def converser(message_utilisateur: str) -> str:
# Fügen Sie die Nachricht des Benutzers zur Historie hinzu
historique.append({"role": "user", "content": message_utilisateur})
# Führen Sie den Agenten mit der vollständigen Historie aus
result = await Runner.run(agent, historique)
# Speichern Sie neue Austausche für das nächste Turn
historique.clear()
historique.extend(result.to_input_list())
return result.final_output
# Simulieren Sie eine Konversation
async def demo():
print(await converser("Mein Name ist Thomas."))
print(await converser("Wie ist mein Vorname?")) # Der Agent erinnert sich
print(await converser("Empfehlen Sie ein gutes Restaurant in Paris."))
Dieses Gedächtnis lebt im RAM. Es verschwindet, wenn Sie Ihren Dienst neu bereitstellen, und wächst unbegrenzt, wenn die Konversation anhält: zwei Grenzen, die Sie im Blick behalten müssen, bevor Sie in die Produktion gehen.
Muster: Persistierendes Gedächtnis mit einer Datenbank
Für ein Gedächtnis, das Neustarts übersteht, speichern Sie die Historie in einer Datenbank. Der hier präsentierte Ansatz geht einen Schritt weiter: Anstatt alles zu behalten, entscheidet sich der Agent selbst, was erhalten werden muss, über ein Paar von Speicher- und Abruf-Werkzeugen. Der Kunde sagt “Ich bin allergisch gegen Erdnüsse”, der Agent ruft sauvegarder_note auf, und die Information bleibt drei Wochen später verfügbar.
import json
from agents import Agent, Runner, function_tool
@function_tool
async def sauvegarder_note(ctx: RunContextWrapper, cle: str, valeur: str) -> str:
"""Speichert Informationen, um sie später zu behalten."""
# In der Produktion: Schreiben in die Datenbank
notes = ctx.context.notes
notes[cle] = valeur
return f"Notiz gespeichert: {cle} = {valeur}"
@function_tool
async def recuperer_note(ctx: RunContextWrapper, cle: str) -> str:
"""Ruft zuvor gespeicherte Informationen ab."""
notes = ctx.context.notes
valeur = notes.get(cle)
if valeur:
return f"{cle} = {valeur}"
return f"Keine Notiz für '{cle}' gefunden"
@dataclass
class ContexteMemoire:
user_id: str
notes: dict = field(default_factory=dict)
agent = Agent(
name="Assistent mit Gedächtnis",
instructions="""Sie sind ein Assistent mit persistierendem Gedächtnis.
Verwenden Sie sauvegarder_note, um wichtige Informationen zu behalten,
und recuperer_note, um sie abzurufen.""",
tools=[sauvegarder_note, recuperer_note],
model="gpt-5.6-terra",
)
Kontext vs. Anweisungen: Wann was verwenden
Diese vier Mechanismen überschneiden sich teilweise, und der klassische Fehler besteht darin, alles über Anweisungen zu leiten. Die folgende Tabelle fasst die Zuordnung zusammen, die Sie sich merken sollten.
| Bedarf | Lösung |
|---|---|
| Benutzerdaten (Name, Rolle) | Kontextvariablen |
| Agentenverhalten | Anweisungen (statisch oder dynamisch) |
| Konversationshistorie | result.to_input_list() |
| Langzeitgedächtnis | Werkzeuge + Datenbank |
| Laufzeitkonfiguration | Kontextvariablen |
Kernaussagen
RunContextWrapperträgt einen typisierten Zustand, der von allen Werkzeugen zugänglich ist- Kontext ist veränderbar: Werkzeuge können ihn während der Ausführung modifizieren
- Dynamische Anweisungen (Funktionen) passen sich dem Kontext bei jedem Turn an
- Konversationshistorie wird mit
result.to_input_list()aufrechterhalten - Für persistierendes Gedächtnis kombinieren Sie Speicher-Werkzeuge mit einer Datenbank