Променливи на контекста и памет на агента
На тази страница
Променливи на контекста и памет на агента
Агент без памет забравя всичко между отделните изпълнения: той пита за името на клиента във всяко съобщение и започва от нулата при всеки завой. Два взаимно допълващи се механизма решават този проблем. Променливите на контекста инжектират споделено състояние в агента и неговите инструменти, докато разговорната памет поддържа нишката на многократен диалог.
Променливи на контекста: Споделено състояние
RunContextWrapper е типизиран обект, който циркулира между агента, неговите инструменти и неговите предпазни механизми (guardrails). Конкретно, Вие дефинирате клас с данни (dataclass), описващ сесията – идентичност, количка, предпочитания – и всеки инструмент го получава като първи параметър. В примера по-долу ajouter_au_panier записва в този обект, а voir_panier го прочита обратно: и двата инструмента споделят една и съща количка, без никакви данни да преминават през промпта.
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}")
Контекстът е променлив (mutable): инструментите могат да го модифицират и промените се запазват след изпълнението. Това прави последния ред интересен – след run_sync, обектът session на Вашето приложение всъщност съдържа двата артикула, готови за изпращане към системата Ви за поръчки.
Динамични инструкции
Това състояние не служи само за инструментите: то може също да оформи поведението на агента. Инструкциите могат да бъдат функция, която получава контекста и изгражда системния промпт в реално време, включвайки името на клиента и предпочитания език.
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",
)
Инструкциите се оценяват при всеки завой от цикъла на агента, което позволява персонализиране в реално време: ако инструмент току-що е добавил артикул, следващият завой веднага го отчита в системния промпт.
Разговорна памет за многократни диалози
Контекстът пренася данни, а не самия диалог. За да поддържате разговор през множество размени, предайте историята. Принципът се свежда до три стъпки: добавяте съобщението на потребителя, изпълнявате агента върху пълния списък, след което заменяте Вашата история с тази, върната от резултата – включително съобщения, извиквания на инструменти и отговори.
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. Тя изчезва, когато преразположите (redeploy) услугата си, и расте неограничено, ако разговорът продължи: две ограничения, които трябва да имате предвид, преди да преминете към продукция.
Шаблон: Постоянна памет с база данни
За памет, която оцелява след рестартиране, съхранявайте историята в база данни. Подходът, представен тук, отива една стъпка по-нататък: вместо да пази всичко, самият агент решава какво заслужава да бъде запазено, чрез двойка инструменти за запазване и извличане. Клиентът казва „Алергичен съм към фъстъци“, агентът извиква 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() - За постоянна памет комбинирайте инструменти за запазване с база данни