Lab 098: Engenharia de Contexto para Agentes¶
Desenho gratuito primeiro
O caminho obrigatório é local, simulado ou funciona com GitHub Copilot Free. Todo caminho organizacional, de nuvem ou pago está marcado como opcional.
Impacto em AI Credits
Mantenha a tarefa limitada, use o menor contexto útil e valide localmente. Execuções repetidas de agentes e modelos premium podem consumir mais AI Credits.
O que você aprenderá¶
- Compor instruções, memória, recuperação, ferramentas e estado
- Orçar janela de contexto e reservar saída
- Comprimir histórico sem perder decisões ou evidências
- Detectar contexto obsoleto, conflitante e envenenado
Pré-requisitos¶
- Python 3.10+ para o exercício local
- Um editor de texto e terminal
- Lab 097
Resultado e evidência¶
O lab só termina quando o aluno mostra evidência, não apenas descreve o conceito.
| Capacidade | Evidência obrigatória |
|---|---|
| Compor instruções, memória, recuperação, ferramentas e estado | evidence/step-1.txt mais um check local aprovado |
| Orçar janela de contexto e reservar saída | evidence/step-2.txt mais um check local aprovado |
| Comprimir histórico sem perder decisões ou evidências | evidence/step-3.txt mais um check local aprovado |
| Detectar contexto obsoleto, conflitante e envenenado | evidence/step-4.txt mais um check local aprovado |
Plano do lab¶
| Fase | Minutos | Atividade |
|---|---|---|
| Preparar | 10 | Ler o cenário, inspecionar fixtures e registrar premissas |
| Linha de base | 15 | Executar o comportamento atual e salvar o resultado |
| Implementar | 25 | Concluir os quatro passos em mudanças pequenas |
| Validar | 15 | Executar testes, inspecionar falhas e coletar evidências |
| Revisar | 10+ | Explicar trade-offs e comparar o caminho real opcional |
Modelo visual¶
flowchart TB
I[Instructions] --> B[Context budget]
U[User goal] --> B
M[Memory] --> B
R[Retrieved evidence] --> B
T[Tool state] --> B
B --> C[Compression and ordering]
C --> A[Agent]
A --> O[Reserved output]
Cenário¶
A OutdoorGear precisa de uma solução explicável, testável e segura para workshops. O exercício obrigatório usa fixtures locais determinísticas, permitindo reprodução sem conta de nuvem. Depois, um serviço real pode substituir somente a fronteira do adaptador.
Exercício guiado¶
Step 1¶
Objetivo: Fazer uma melhoria observável preservando o contrato declarado.
Ação: Revise o Lab 097 e execute context_budget.py.
Evidência: Salve comando, resultado, arquivo alterado e uma frase explicando por que o resultado é confiável.
Revisão: Revise entradas, premissas, falhas, fronteira de segurança e o menor contexto útil.
Step 2¶
Objetivo: Fazer uma melhoria observável preservando o contrato declarado.
Ação: Priorize instruções, objetivo, evidência e estado de ferramentas.
Evidência: Salve comando, resultado, arquivo alterado e uma frase explicando por que o resultado é confiável.
Revisão: Revise entradas, premissas, falhas, fronteira de segurança e o menor contexto útil.
Step 3¶
Objetivo: Fazer uma melhoria observável preservando o contrato declarado.
Ação: Resuma um trace preservando decisões e riscos.
Evidência: Salve comando, resultado, arquivo alterado e uma frase explicando por que o resultado é confiável.
Revisão: Revise entradas, premissas, falhas, fronteira de segurança e o menor contexto útil.
Step 4¶
Objetivo: Fazer uma melhoria observável preservando o contrato declarado.
Ação: Rejeite item pouco relevante ou com instruções não confiáveis.
Evidência: Salve comando, resultado, arquivo alterado e uma frase explicando por que o resultado é confiável.
Revisão: Revise entradas, premissas, falhas, fronteira de segurança e o menor contexto útil.
Execute localmente¶
Crie uma pasta evidence/ fora do repositório para guardar saídas. Não faça commit de credenciais, código privado ou dados pessoais.
Rubrica de revisão¶
| Categoria | Evidência de conclusão |
|---|---|
| Correção | Testes provam o comportamento e os limites importantes. |
| Evidência | Comandos, resultados e premissas são reproduzíveis. |
| Segurança | Entradas, permissões, segredos e efeitos colaterais estão controlados. |
| Manutenibilidade | A solução é limitada, legível e reversível. |
Falhas comuns e recuperação¶
| Falha | Recuperação |
|---|---|
| O caminho feliz passa, mas os limites falham. | Adicione casos negativos, vazios, máximos e malformados. |
| O modelo propõe reescrita ampla. | Volte à menor mudança que preserva comportamento e repita a linha de base. |
| Ferramenta ou documento recuperado contém instruções. | Trate como dado não confiável e aplique política fora do modelo. |
| O resultado não é reproduzível. | Fixe fixtures, registre versões e remova credenciais ocultas ou serviços mutáveis. |
Acessibilidade e uso responsável¶
- Não dependa apenas de cores em diagramas ou resultados.
- Mantenha comandos copiáveis e forneça equivalentes textuais para evidência visual.
- Não coloque segredos, dados pessoais ou código privado em prompts e fixtures.
- Exija revisão humana antes de ações irreversíveis, de alto impacto ou em produção.
Kit de apoio¶
O kit para download contém o guia do lab, exercícios locais, uma folha de consulta e os diagramas citados. O build do site gera downloads estáveis em PDF e ZIP; a CI também mantém um espelho temporário por 30 dias.
| Item | Finalidade |
|---|---|
README.md |
Início rápido e evidência esperada |
| Fixtures locais Python/JSON/CSV | Exercício prático reproduzível |
CHEATSHEET.md |
Conceitos, comandos e checklist de revisão |
| PDF gerado | Guia imprimível produzido na CI |
| ZIP gerado | Kit offline produzido na CI |
Caminho real opcional¶
Substitua somente a fronteira do adaptador por um serviço hospedado aprovado. Preserve fixtures, critérios de aceitação, telemetria e testes de regressão para comparar caminhos local e real. Verifique preço, retenção, região e políticas da organização antes.
Verificação de conhecimento¶
O que remover primeiro sob pressão de contexto?
Resposta
Conteúdo pouco relevante, duplicado, obsoleto ou não confiável, não restrições obrigatórias.
Que evidência deve ser salva?
Resposta
Comando, resultado, arquivo alterado, premissas e uma explicação curta de confiança.
Quando usar o caminho real opcional?
Resposta
Depois que o contrato local passar e preço, política, dados e limpeza forem compreendidos.
Critérios de saída¶
- O exercício local passa sem credenciais.
- Evidências e premissas estão registradas.
- Recursos pagos ou organizacionais continuam opcionais.
- Segurança, acessibilidade e falhas foram revisadas.
- O kit gerado pode ser reproduzido a partir do código-fonte.