Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Muuttujat ja agentin muisti

Oppitunti 13 / 25 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Muuttujat ja agentin muisti
  2. Muuttujat: Jaettu tila
  3. Dynaamiset ohjeet
  4. Monivaiheinen keskustelumuisti
  5. Malli: Pysyvä muisti tietokannan kanssa
  6. Konteksti vs. ohjeet: Milloin käyttää mitä?
  7. Keskeiset asiat

Muuttujat ja agentin muisti

Ilman muistia toimiva agentti unohtaa kaiken suoritusten välillä: se kysyy asiakkaan nimeä jokaisessa viestissä ja aloittaa alusta joka vuorolla. Kaksi täydentävää mekanismia korjaa tämän. Muuttujat syöttävät jaetun tilan agentille ja sen työkaluille, kun taas keskustelumuisti ylläpitää monivaiheisen keskustelun lankaa.

Muuttujat: Jaettu tila

RunContextWrapper on tyypitetty objekti, joka kiertää agentin, sen työkalujen ja suojamuurien välillä. Käytännössä määrittelet istunnon kuvaavan dataclass-olion – identiteetti, ostoskori, mieltymykset – ja jokainen työkalu saa sen ensimmäisenä parametrina. Alla olevassa esimerkissä ajouter_au_panier kirjoittaa tähän objektiin ja voir_panier lukee sen takaisin: molemmat työkalut jakavat saman ostoskorin ilman, että data kulkee kehotteen läpi.

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}")

Konteksti on muokattava: työkalut voivat muuttaa sitä, ja muutokset säilyvät suorituksen jälkeen. Tämä tekee viimeisestä rivistä mielenkiintoisen: run_sync:n jälkeen sovelluksesi session-objekti sisältää itse asiassa kaksi kohdetta, valmiina lähetettäväksi tilausjärjestelmääsi.

Dynaamiset ohjeet

Tämä tila ei ole tarkoitettu vain työkaluille: se voi myös muokata agentin käyttäytymistä. Ohjeet voivat olla funktio, joka vastaanottaa kontekstin ja rakentaa järjestelmäkehotteen lennosta, mukaan lukien asiakkaan nimi ja ensisijainen kieli.

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",
)

Ohjeet arvioidaan agentin silmukan jokaisella vuorolla, mikä mahdollistaa reaaliaikaisen personoinnin: jos työkalu on juuri lisännyt kohteen, seuraava vuoro ottaa sen heti huomioon järjestelmäkehotteessa.

Monivaiheinen keskustelumuisti

Konteksti kuljettaa dataa, ei itse dialogia. Keskustelun ylläpitämiseksi useiden vaihtojen yli välitä historia. Periaate tiivistyy kolmeen vaiheeseen: lisäät käyttäjän viestin, suoritat agentin koko listalla ja korvaat historiansa tuloksen palauttamalla listalla – mukaan lukien viestit, työkalukutsut ja vastaukset.

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."))

Tämä muisti elää keskusmuistissa (RAM). Se katoaa, kun uudelleenkäynnistät palvelusi, ja se kasvaa rajattomasti, jos keskustelu kestää: kaksi rajoitusta, jotka on pidettävä mielessä ennen tuotantoon siirtymistä.

Malli: Pysyvä muisti tietokannan kanssa

Muistille, joka selviää uudelleenkäynnistyksistä, tallenna historia tietokantaan. Tässä esitelty lähestymistapa menee askelen pidemmälle: kaiken säilyttämisen sijaan agentti päättää itse, mikä ansaitsee säilyttämisen, tallennus- ja hakutyökaluparin avulla. Asiakas sanoo “Olen allerginen maapähkinöille”, agentti kutsuu sauvegarder_note:n, ja tieto pysyy saatavilla kolme viikkoa myöhemmin.

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",
)

Konteksti vs. ohjeet: Milloin käyttää mitä?

Nämä neljä mekanismia ovat osittain päällekkäisiä, ja klassinen virhe on reitittää kaikki ohjeiden kautta. Alla oleva taulukko tiivistää muistettavan mappingsin.

TarveRatkaisu
Käyttäjädata (nimi, rooli)Muuttujat
Agentin käyttäytyminenOhjeet (staattiset tai dynaamiset)
Keskusteluhistoriaresult.to_input_list()
Pitkäaikainen muistiTyökalut + tietokanta
Ajoaikainen konfiguraatioMuuttujat

Keskeiset asiat

  • RunContextWrapper kuljettaa tyypitettyä tilaa, joka on kaikkien työkalujen saatavilla
  • Konteksti on muokattava: työkalut voivat muuttaa sitä suorituksen aikana
  • Dynaamiset ohjeet (funktiot) mukautuvat kontekstiin jokaisella vuorolla
  • Keskusteluhistoria ylläpidetään käyttämällä result.to_input_list()
  • Pysyvää muistia varten yhdistä tallennustyökalut tietokantaan