Variáveis de Contexto e Memória do Agente
Nesta página
Variáveis de Contexto e Memória do Agente
Um agente sem memória esquece tudo entre execuções: pede o nome do cliente em cada mensagem e recomeça do zero a cada turno. Dois mecanismos complementares resolvem este problema. As variáveis de contexto injetam estado partilhado no agente e nas suas ferramentas, enquanto a memória conversacional mantém o fio condutor de uma conversa com múltiplos turnos.
Variáveis de Contexto: Estado Partilhado
O RunContextWrapper é um objeto tipado que circula entre o agente, as suas ferramentas e as suas barreiras de segurança. Concretamente, define uma dataclass que descreve a sessão — identidade, carrinho, preferências — e cada ferramenta recebe-a como primeiro parâmetro. No exemplo abaixo, adicionar_ao_carrinho escreve neste objeto e ver_carrinho lê-o de volta: ambas as ferramentas partilham o mesmo carrinho sem que quaisquer dados passem pelo prompt.
from dataclasses import dataclass, field
from agents import Agent, Runner, RunContextWrapper, function_tool
@dataclass
class SessaoUtilizador:
user_id: str
nome: str
email: str
carrinho: list[dict] = field(default_factory=list)
preferencias: dict = field(default_factory=dict)
@function_tool
def adicionar_ao_carrinho(
ctx: RunContextWrapper[SessaoUtilizador],
produto: str,
quantidade: int = 1,
) -> str:
"""Adiciona um produto ao carrinho do utilizador."""
ctx.context.carrinho.append({"produto": produto, "quantidade": quantidade})
total = len(ctx.context.carrinho)
return f"{produto} (x{quantidade}) adicionado ao carrinho. Total: {total} item(s)."
@function_tool
def ver_carrinho(ctx: RunContextWrapper[SessaoUtilizador]) -> str:
"""Mostra o conteúdo do carrinho."""
if not ctx.context.carrinho:
return "O seu carrinho está vazio."
linhas = [f"- {item['produto']} x{item['quantidade']}" for item in ctx.context.carrinho]
return f"Carrinho de {ctx.context.nome}:\n" + "\n".join(linhas)
agente = Agent(
name="Agente de Loja",
instructions="Ajuda os clientes com as suas compras.",
tools=[adicionar_ao_carrinho, ver_carrinho],
model="gpt-5.6-terra",
)
sessao = SessaoUtilizador(
user_id="usr_789",
nome="Marie Dupont",
email="[email protected]",
)
# O contexto é partilhado por todas as ferramentas
resultado = Runner.run_sync(agente, "Adiciona um portátil e dois ratos ao meu carrinho", context=sessao)
print(resultado.final_output)
print(f"Carrinho após execução: {sessao.carrinho}")
O contexto é mutável: as ferramentas podem modificá-lo e as alterações persistem após a execução. É isto que torna a última linha interessante — após run_sync, o objeto sessao da sua aplicação contém efetivamente os dois itens, prontos para serem enviados para o seu sistema de encomendas.
Instruções Dinâmicas
Este estado não serve apenas para as ferramentas: pode também moldar o comportamento do agente. As instruções podem ser uma função que recebe o contexto e constrói o prompt do sistema em tempo real, incluindo o nome do cliente e o idioma preferido.
def instrucoes_dinamicas(ctx: RunContextWrapper[SessaoUtilizador]) -> str:
prefs = ctx.context.preferencias
idioma = prefs.get("idioma", "português")
return f"""Você é um assistente de vendas.
O nome do cliente é {ctx.context.nome}.
O email dele é {ctx.context.email}.
Ele tem {len(ctx.context.carrinho)} item(s) no carrinho.
Comunique em {idioma}."""
agente = Agent(
name="Agente Personalizado",
instructions=instrucoes_dinamicas,
tools=[adicionar_ao_carrinho, ver_carrinho],
model="gpt-5.6-terra",
)
As instruções são avaliadas em cada turno do ciclo do agente, permitindo uma personalização em tempo real: se uma ferramenta acabou de adicionar um item, o turno seguinte toma-o imediatamente em conta no prompt do sistema.
Memória Conversacional de Múltiplos Turnos
O contexto transporta dados, não o próprio diálogo. Para manter uma conversa ao longo de várias trocas, passe o histórico. O princípio resume-se a três passos: adiciona a mensagem do utilizador, executa o agente na lista completa e, em seguida, substitui o seu histórico pelo devolvido pelo resultado — incluindo mensagens, chamadas de ferramentas e respostas.
from agents import Agent, Runner
agente = Agent(
name="Assistente",
instructions="Você é um assistente que se lembra da conversa.",
model="gpt-5.6-terra",
)
historico = []
async def conversar(mensagem_utilizador: str) -> str:
# Adiciona a mensagem do utilizador ao histórico
historico.append({"role": "user", "content": mensagem_utilizador})
# Executa o agente com o histórico completo
resultado = await Runner.run(agente, historico)
# Guarda as novas trocas para o próximo turno
historico.clear()
historico.extend(resultado.to_input_list())
return resultado.final_output
# Simula uma conversa
async def demo():
print(await conversar("O meu nome é Thomas."))
print(await conversar("Qual é o meu primeiro nome?")) # O agente lembra-se
print(await conversar("Recomenda um bom restaurante em Paris."))
Esta memória reside na RAM. Desaparece quando redeploya o seu serviço e cresce indefinidamente se a conversa durar: dois limites a ter em mente antes de ir para produção.
Padrão: Memória Persistente com uma Base de Dados
Para uma memória que sobreviva a reinícios, guarde o histórico numa base de dados. A abordagem aqui apresentada vai um passo além: em vez de guardar tudo, o agente decide por si próprio o que merece ser retido, através de um par de ferramentas de guardar e recuperar. O cliente diz “sou alérgico a amendoins”, o agente chama guardar_nota e a informação permanece disponível três semanas depois.
import json
from agents import Agent, Runner, function_tool
@function_tool
async def guardar_nota(ctx: RunContextWrapper, chave: str, valor: str) -> str:
"""Guarda informação para lembrar mais tarde."""
# Em produção: escrever na base de dados
notas = ctx.context.notas
notas[chave] = valor
return f"Nota guardada: {chave} = {valor}"
@function_tool
async def recuperar_nota(ctx: RunContextWrapper, chave: str) -> str:
"""Recupera informação guardada anteriormente."""
notas = ctx.context.notas
valor = notas.get(chave)
if valor:
return f"{chave} = {valor}"
return f"Nenhuma nota encontrada para '{chave}'"
@dataclass
class ContextoMemoria:
user_id: str
notas: dict = field(default_factory=dict)
agente = Agent(
name="Assistente com Memória",
instructions="""Você é um assistente com memória persistente.
Use guardar_nota para reter informação importante
e recuperar_nota para a obter.""",
tools=[guardar_nota, recuperar_nota],
model="gpt-5.6-terra",
)
Contexto vs. Instruções: Quando Usar Cada Um
Estes quatro mecanismos sobrepõem-se parcialmente e o erro clássico é encaminhar tudo através das instruções. A tabela abaixo resume o mapeamento a recordar.
| Necessidade | Solução |
|---|---|
| Dados do utilizador (nome, função) | Variáveis de contexto |
| Comportamento do agente | Instruções (estáticas ou dinâmicas) |
| Histórico da conversa | result.to_input_list() |
| Memória de longo prazo | Ferramentas + base de dados |
| Configuração em tempo de execução | Variáveis de contexto |
Pontos-chave
RunContextWrappertransporta estado tipado acessível por todas as ferramentas- O contexto é mutável: as ferramentas podem modificá-lo durante a execução
- Instruções dinâmicas (funções) adaptam-se ao contexto em cada turno
- O histórico conversacional é mantido com
result.to_input_list() - Para memória persistente, combine ferramentas de guarda com uma base de dados