Estratégias de contexto para agentes
Nesta página
O desafio do contexto para agentes
Um agente autónomo encadeia dezenas de chamadas à API: raciocina, utiliza ferramentas, lê resultados e itera. A cada passo, o contexto cresce. A diferença em relação a uma conversa comum é que este crescimento não provém do utilizador, mas do próprio agente: uma consulta SQL que devolve trezentas linhas, uma página web completa recuperada ou um ficheiro de registo inteiro lido. Sem uma estratégia de gestão, um agente atinge o limite de contexto em poucas iterações, muitas vezes antes de concluir a tarefa que lhe atribuiu.
Projetar um agente que gere a sua memória de forma eficaz resume-se, portanto, a responder a três perguntas: o que deve permanecer intacto, o que pode ser resumido e o que nunca deveria ter entrado no contexto em primeiro lugar. Abordá-las-emos por essa ordem.
Uma memória de três níveis
A estrutura que utilizamos baseia-se na distinção clássica entre memória de trabalho, memória episódica e memória semântica. A memória de trabalho contém as ações mais recentes na sua forma bruta, pois o agente precisa delas exatamente como estão para decidir o que fazer a seguir. A memória episódica guarda resumos de passos anteriores: o agente sabe que explorou determinada pista e o que isso produziu, sem reler os detalhes. Por fim, a memória semântica acumula factos estabelecidos de uma vez por todas — o ID do cliente, a versão do esquema da base de dados, a restrição orçamental — que nunca se devem perder num resumo.
from dataclasses import dataclass, field
@dataclass
class AgentMemory:
"""Sistema de memória de três níveis para um agente."""
# Nível 1: memória de trabalho (contexto atual)
working: list[dict] = field(default_factory=list)
# Nível 2: memória episódica (resumos de passos anteriores)
episodes: list[str] = field(default_factory=list)
# Nível 3: memória semântica (factos permanentes)
facts: list[str] = field(default_factory=list)
max_tokens_working: int = 20_000
max_episodes: int = 10
def add_action(self, action: str, result: str):
"""Adiciona uma ação à memória de trabalho."""
self.working.append({
"action": action,
"result": result[:2000], # Trunca resultados longos
})
self._check_compaction()
def add_fact(self, fact: str):
"""Adiciona um facto permanente."""
if fact not in self.facts:
self.facts.append(fact)
def _check_compaction(self):
tokens = sum(
len(str(e)) // 4 for e in self.working
)
if tokens > self.max_tokens_working:
self._compact()
def _compact(self):
"""Compacta a memória de trabalho num episódio."""
import openai
client = openai.OpenAI()
text = "\n".join(
f"Action: {a['action']}\nResult: {a['result']}"
for a in self.working[:-2]
)
response = client.responses.create(
model="gpt-5.6-terra",
input=(
"Summarize these agent actions in 3-5 key points. "
"Keep important facts, results, and decisions.\n\n"
f"{text}"
),
max_output_tokens=300,
)
self.episodes.append(response.output_text)
self.working = self.working[-2:] # Mantém as últimas 2 ações
# Limita o número de episódios
if len(self.episodes) > self.max_episodes:
self.episodes = self.episodes[-self.max_episodes:]
def build_context(self) -> str:
"""Constrói o contexto completo para a próxima chamada."""
parts = []
if self.facts:
parts.append(
"Established facts:\n" + "\n".join(f"- {f}" for f in self.facts)
)
if self.episodes:
parts.append(
"Summarized history:\n" + "\n---\n".join(self.episodes)
)
if self.working:
parts.append(
"Recent actions:\n" + "\n".join(
f"- {a['action']} → {a['result'][:500]}"
for a in self.working
)
)
return "\n\n".join(parts)
Dois parâmetros merecem discussão antes de os copiar tal como estão. A truncação de 2000 caracteres em add_action protege contra ferramentas verbosas, mas corta cegamente: se as suas ferramentas devolverem JSON, ficará com um objeto inválido no meio do seu contexto. E max_episodes: 10 impõe uma amnésia limitada — no décimo primeiro resumo, o primeiro desaparece. Para um agente que funcione durante muito tempo, promova factos importantes para facts antes de saírem da janela episódica, caso contrário perdê-los-á permanentemente.
Dominar os resultados das ferramentas
As ferramentas devolvem frequentemente resultados volumosos: páginas web, resultados SQL, conteúdos de ficheiros. Esta é, de longe, a principal causa de saturação do contexto para um agente, e também a mais fácil de corrigir, pois trata-se na ingestão e não depois do facto.
A função abaixo oferece três estratégias de truncação. O modo start adequa-se a documentos onde o essencial está no topo, como um artigo ou relatório. O modo start_end funciona quando o fim contém a informação decisiva: um rasto de execução onde o erro aparece por último, um ficheiro de registo ou uma resposta paginada onde o total aparece no fim. O modo summary custa uma chamada à API extra, o que só se justifica para conteúdos longos verdadeiramente úteis para o restante raciocínio.
def truncate_tool_result(
result: str,
max_tokens: int = 2000,
strategy: str = "start_end",
) -> str:
"""Trunca o resultado de uma ferramenta preservando informações chave."""
estimated_tokens = len(result) // 4
if estimated_tokens <= max_tokens:
return result
max_chars = max_tokens * 4
match strategy:
case "start":
return result[:max_chars] + "\n[... truncated]"
case "start_end":
half = max_chars // 2
return (
result[:half]
+ "\n[... middle truncated ...]\n"
+ result[-half:]
)
case "summary":
import openai
client = openai.OpenAI()
response = client.responses.create(
model="gpt-5.6-terra",
input=f"Summarize this data keeping the essentials:\n{result}",
max_output_tokens=max_tokens,
)
return response.output_text
return result[:max_chars]
Resultados tabulares exigem um tratamento especial. Cortar uma tabela SQL no meio remove o cabeçalho ou distorce a noção de volume: o agente vê vinte linhas e conclui que a tabela contém apenas vinte. O filtro abaixo mantém o cabeçalho, uma amostra do topo e da base e — este é o ponto chave — indica explicitamente o número de linhas omitidas e o total. O agente sabe então que está a ver um excerto e pode decidir executar uma consulta de agregação em vez de raciocinar sobre uma amostra.
def filter_sql_result(result: str, question: str) -> str:
"""Filtra um resultado SQL para manter apenas o relevante."""
lines = result.strip().split("\n")
if len(lines) <= 20:
return result
# Mantém o cabeçalho e as primeiras/últimas linhas
header = lines[0]
first_lines = lines[1:6]
last_lines = lines[-5:]
return (
f"{header}\n"
+ "\n".join(first_lines)
+ f"\n[... {len(lines) - 11} lines omitted ...]\n"
+ "\n".join(last_lines)
+ f"\n\nTotal: {len(lines) - 1} rows"
)
Quando vários agentes trabalham em conjunto
Quando vários subagentes trabalham em paralelo, a tentação é dar-lhes a todos o contexto completo, apenas por segurança. Essa é a melhor forma de multiplicar a sua fatura pelo número de agentes, degradando simultaneamente o seu desempenho, já que um contexto sobrecarregado torna o modelo menos preciso na sua própria tarefa. Em vez disso, partilhe o contexto mínimo: o objetivo global para que o agente compreenda a que está a contribuir, o seu próprio papel, restrições comuns e um excerto limitado dos resultados produzidos pelos seus pares.
@dataclass
class SharedContext:
"""Contexto partilhado entre subagentes."""
objective: str
constraints: list[str]
partial_results: dict[str, str] = field(default_factory=dict)
def context_for_sub_agent(self, role: str) -> str:
"""Gera um contexto direcionado para um subagente."""
return (
f"Global objective: {self.objective}\n"
f"Your role: {role}\n"
f"Constraints: {', '.join(self.constraints)}\n"
f"Results from other agents:\n"
+ "\n".join(
f"- {k}: {v[:200]}"
for k, v in self.partial_results.items()
)
)
O limite de 200 caracteres por resultado parcial reflete uma intenção: um subagente precisa de saber o que os outros encontraram, não como o encontraram. Se os seus agentes precisarem do detalhe completo dos resultados vizinhos, provavelmente precisa de repensar a forma como dividiu os papéis.
Pontos-chave
- Estruture a memória do agente em três níveis: trabalho, episódica, semântica
- Compacte automaticamente quando a memória de trabalho exceder o limiar
- Trunque os resultados das ferramentas antes de os injetar no contexto
- Sinalize sempre que um resultado foi truncado e em que medida
- Para configurações multiagente, partilhe um contexto mínimo direcionado por função