Pi Agent: Context Management
Última atualização: 2026-08-31
--- title: "Gerenciamento de Contexto" description: "Aprofunde-se no mecanismo de contexto do Pi Agent, incluindo janelas de contexto, estrategias de truncamento, metodos de injecao e tecnicas de otimizacao." order: 7 lang: pt-br
O contexto é a "memória de curto prazo" do Agent — gerencie-o bem, ou o Agent vai "esquecer do que estava falando."
1. O que é Contexto
Contexto é toda a informação acumulada durante uma sessão:
- Prompt do Sistema
- Histórico de Chat
- Registros de Chamadas de Ferramentas
- Informações Extra Injetadas
TEXT
📖 Somente leitura
Context Structure
├── System Prompt -> Fixed instructions (role definition, behavioral constraints)
├── Chat History -> Dynamic accumulation (user messages + Agent responses)
├── Tool Calls -> Tool call process and results
└── Injected Context -> Extra injections (file contents, API data, etc.)
2. Janela de Contexto
A janela de contexto determina quanto o Agent pode "lembrar" de uma vez:
(1) Definir Tamanho da Janela
PYTHON
from pi_agent import Agent
agent = Agent(name="quick", context_window=2048) # Pequena: economiza tokens
agent = Agent(name="long", context_window=16384) # Grande: lembra mais
agent = Agent(name="full", context_window=65536) # Máxima: capacidade total do modelo
(2) Janela vs Custo
| Tamanho da Janela | Melhor Para | Custo de Tokens |
|---|---|---|
| 2K | Q&A, instruções simples | Baixo |
| 8K | Conversas multi-turno, revisão de código | Médio |
| 32K | Análise de documentos longos | Alto |
| 64K | Análise de projetos grandes | Muito alto |
3. Estratégias de Truncamento
Quando a conversa excede a janela, Pi Agent oferece múltiplas estratégias:
PYTHON
from pi_agent import Agent
agent = Agent(truncation_strategy="remove_oldest") # Remove mensagens mais antigas
agent = Agent(truncation_strategy="summarize") # IA resume mensagens antigas
agent = Agent(truncation_strategy="sliding_window", keep_recent=10) # Manter últimos N turnos
| Estratégia | Prós | Contras |
|---|---|---|
| remove_oldest | Simples e eficiente | Perde informações antigas |
| summarize | Preserva pontos-chave | Custo extra de tokens |
| sliding_window | Controlável | Pode perder contexto importante |
4. Injeção de Contexto
(1) Injeção Manual
PYTHON
from pi_agent import Agent
agent = Agent(name="coder")
with open("main.py") as f:
agent.inject_context("current_file", f.read())
agent.inject_context("project_info", {
"name": "my_app",
"framework": "FastAPI",
"python_version": "3.11"
})
response = agent.chat("Help me add a health check endpoint")
# Agent knows the project uses FastAPI, generates FastAPI-style code
(2) Injeção Automática
PYTHON
agent = Agent(name="auto", auto_context=True)
# Automatically injects working directory structure, git info, etc.
5. Técnicas de Otimização
(1) Prompts de Sistema Concisos
PYTHON
# Verboso
agent = Agent(system_prompt="You are a very excellent programming assistant, skilled in Python, respond in detail...")
# Conciso
agent = Agent(system_prompt="Python expert. Be concise.")
(2) Limpar Histórico Desnecessário
PYTHON
agent.clear_history() # Limpar tudo ao trocar de assunto
agent.keep_recent(5) # Manter apenas os últimos 5 turnos
(3) Resumo Automático
PYTHON
agent.summarize_context() # Gatilho manual
agent = Agent(auto_summarize_threshold=3000) # Automático no limite
❓ Perguntas Frequentes
P: Janela de contexto vs comprimento de contexto do modelo? R: A janela é seu limite no nível do Agent e não pode exceder o máximo do modelo. Ex.: deepseek-chat suporta 64K; definir 100K é ineficaz. P: inject_context vs escrever nas mensagens? R: Conteúdo de inject_context persiste (não é removido por truncamento), enquanto conteúdo de mensagens pode ser truncado. Melhor para informações importantes do projeto. P: Quantos tokens extras o resumo automático consome? R: Cerca de 10-20% do conteúdo resumido. Ex.: resumir 4000 tokens custa ~400-800 extras.
❓ Resumo
- Contexto = prompt do sistema + histórico de chat + chamadas de ferramentas + conteúdo injetado
- Janela de contexto determina o limite de memória; maior é mais forte, porém mais caro
- Três estratégias de truncamento: remove_oldest, summarize, sliding_window
- inject_context para informações persistentes que não serão truncadas
- Três técnicas de otimização: prompts concisos, limpar histórico, resumo automático
📝 Exercícios
- Básico (Dificuldade: ⭐): Crie um Agent com diferentes valores de context_window, observe quando ele começa a "esquecer" em conversas multi-turno.
- Intermediário (Dificuldade: ⭐⭐): Compare as estratégias de truncamento remove_oldest vs summarize.
- Avançado (Dificuldade: ⭐⭐⭐): Implemente um "gerenciador de contexto inteligente" que detecte automaticamente quando limpar o histórico e quando resumir.
