Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Variáveis de Contexto e Memória do Agente

Aula 13 de 25 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Variáveis de Contexto e Memória do Agente
  2. Variáveis de Contexto: Estado Partilhado
  3. Instruções Dinâmicas
  4. Memória Conversacional de Múltiplos Turnos
  5. Padrão: Memória Persistente com uma Base de Dados
  6. Contexto vs. Instruções: Quando Usar Cada Um
  7. Pontos-chave

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.

NecessidadeSolução
Dados do utilizador (nome, função)Variáveis de contexto
Comportamento do agenteInstruções (estáticas ou dinâmicas)
Histórico da conversaresult.to_input_list()
Memória de longo prazoFerramentas + base de dados
Configuração em tempo de execuçãoVariáveis de contexto

Pontos-chave

  • RunContextWrapper transporta 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