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

Estratégias de contexto para agentes

Aula 14 de 20 Atualizada a 28 de julho de 2026 Avancado
Nesta página
  1. O desafio do contexto para agentes
  2. Uma memória de três níveis
  3. Dominar os resultados das ferramentas
  4. Quando vários agentes trabalham em conjunto
  5. Pontos-chave

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