Um agente de IA é um modelo de linguagem rodando em um laço com ferramentas: ele decide o que fazer, chama uma ferramenta, lê o resultado e continua até a tarefa terminar. Escrever prompts para um agente é diferente de fazê-lo para uma única resposta. Você não está mais escrevendo uma pergunta. Está escrevendo as instruções de operação de algo que tomará muitas decisões sem você.
Fluxo de trabalho ou agente
Primeiro decida se você precisa de um agente.
| Fluxo de trabalho de IA | Agente de IA | |
|---|---|---|
| Quem decide os passos | Seu código | O modelo |
| Previsibilidade | Alta | Menor |
| Custo e latência | Menores, conhecidos de antemão | Maiores, variáveis |
| Bom para | Tarefas com procedimento conhecido | Tarefas em que o caminho depende do que for encontrado |
| Depuração | Passo a passo | Ler todo o rastro |
Se você consegue desenhar o fluxograma, construa um fluxo de trabalho com cadeias de prompts. Use um agente quando o número e a ordem dos passos não podem ser conhecidos de antemão, como ao investigar um bug ou pesquisar uma pergunta.
As partes de um prompt de agente
O comportamento de um agente vem de quatro coisas que ele lê: o prompt de sistema, as definições de ferramentas, a tarefa e os resultados que voltam. Cada uma exige uma redação deliberada.
1. O prompt de sistema
Cubra seis coisas.
Papel e objetivo. Para que serve o agente, em duas frases.
Regras de operação. Como trabalhar: investigar antes de mudar qualquer coisa, preferir passos pequenos, verificar os resultados.
Limites. O que ele não deve fazer e o que precisa de aprovação.
Como lidar com problemas. Erros de ferramenta, informação ausente, ambiguidade.
Quando parar. A condição que significa que a tarefa está concluída e um limite de esforço.
Como relatar. O que a resposta final contém.
You are a coding agent working in the user's repository.
## How to work
- Read the relevant files before proposing a change.
- Make the smallest change that satisfies the task.
- After editing, run the tests that cover the change.
## Boundaries
- Do not modify files outside the repository.
- Do not delete files or run destructive commands without asking.
- Do not change public interfaces unless the task says so.
## When things go wrong
- If a command fails, read the error and try a different approach once.
If it fails again, stop and report what you tried.
- If the task is ambiguous, ask one question before starting.
## When to stop
- Stop when the acceptance criteria are met and the tests pass.
## Final report
- What changed and why, files touched, how it was verified, and
anything left undone.
Explique o motivo de uma regra quando não for óbvio. Um agente encontra situações que você não listou, e uma regra com motivo generaliza melhor que uma proibição seca.
2. Definições de ferramentas
O modelo escolhe as ferramentas lendo seus nomes e descrições. Definições vagas são a causa mais comum de agentes usarem a ferramenta errada.
- Dê às ferramentas nomes pelo que fazem:
search_orders, nãoquery2. - Descreva quando usar cada uma e quando não usar.
- Diga o que volta, incluindo o formato e os limites.
- Torne os parâmetros inequívocos: tipos, formatos, valores permitidos, um exemplo.
- Evite ferramentas sobrepostas. Se duas ferramentas puderem fazer o trabalho, o modelo escolherá de forma inconsistente.
- Retorne erros acionáveis: “a data deve ser AAAA-MM-DD”, não “entrada inválida”.
Poucas ferramentas bem descritas superam um grande conjunto de ferramentas parecidas. O Model Context Protocol padroniza como as ferramentas são descritas e oferecidas aos agentes.
3. O prompt da tarefa
Dê ao agente uma especificação, não uma frase. Quanto mais autonomia ele tem, mais importa o briefing inicial.
## Objective
Add rate limiting to the public API.
## Requirements
- 100 requests per minute per API key.
- Return 429 with a Retry-After header when exceeded.
## Constraints
- Existing clients must keep working: no changes to response schemas.
## Acceptance criteria
- New tests cover the limit and the 429 response.
- The existing test suite passes.
Os critérios de aceitação dão ao agente uma forma de saber que terminou e a você uma forma de conferir. A extensão do VS Code do PromptFlowEngine transforma uma tarefa de uma linha nessa estrutura e anexa os arquivos relevantes.
4. Gerenciamento de contexto
Tudo o que o agente lê permanece em seu contexto e é relido a cada passo. Deixado sozinho, o contexto se enche de saídas de ferramentas obsoletas, o custo sobe e a qualidade cai.
- Retorne resultados de ferramentas compactos. Os campos necessários, não toda a carga.
- Resuma ou descarte resultados antigos depois de usados.
- Mantenha anotações duradouras fora do contexto, em um arquivo que o agente possa ler e atualizar, para tarefas longas.
- Delegue. Entregue uma subtarefa autônoma a um subagente com um contexto novo e traga de volta apenas a conclusão dele.
Veja a otimização de tokens.
Escrevendo prompts para subagentes
Quando um agente instrui outro, o briefing é tudo o que o destinatário sabe. Um bom prompt de delegação declara:
- O objetivo e por que ele importa.
- O que já se sabe, para não repetir trabalho.
- A saída exata desejada e seu formato.
- Os limites: no que mexer e o que deixar em paz.
Um agente orquestrador que escreve briefings vagos recebe trabalho vago de volta. Este é um lugar em que uma verificação automática ajuda: um agente pode passar o rascunho do briefing pelas ferramentas MCP do PromptFlowEngine para achar um objetivo ou formato de saída ausente antes de delegar.
Segurança para agentes
Os agentes agem, então erros e ataques têm consequências.
- Privilégio mínimo. Cada ferramenta tem a permissão mais estreita que funcione. Somente leitura por padrão.
- Aprovação para ações irreversíveis. Apagar, enviar, pagar, implantar.
- Trate os resultados de ferramentas como não confiáveis. Uma página web ou um arquivo pode conter instruções dirigidas ao agente. Veja a injeção de prompt.
- Limites. Máximo de passos, gasto máximo e tempos limite.
- Mantenha segredos fora do contexto. Entregue as credenciais diretamente às ferramentas. Veja a detecção de dados pessoais e segredos.
- Registre cada chamada de ferramenta para que uma execução possa ser revisada.
Modos de falha comuns
| Sintoma | Causa provável | Correção |
|---|---|---|
| Entra em laço na mesma ação | Sem regra de parada nem limite de passos | Adicionar ambos |
| Declara sucesso cedo demais | Sem critérios de aceitação | Defini-los; exigir verificação |
| Usa a ferramenta errada | Descrições sobrepostas ou vagas | Reescrever as descrições das ferramentas |
| Faz muito mais do que o pedido | Escopo não declarado | Declarar os limites explicitamente |
| Esquece instruções anteriores | Contexto sobrecarregado | Reduzir resultados, resumir, usar anotações |
| Segue o texto encontrado em um arquivo | Conteúdo não confiável sem marcação | Marcá-lo como dados; restringir ferramentas |
Avaliando agentes
Pontue o resultado, não o caminho: os testes passaram, o registro certo foi atualizado, a resposta está correta? Depois revise os rastros em busca de passos desperdiçados e ações arriscadas. Mantenha um conjunto de tarefas com bons resultados conhecidos e reexecute-o quando o prompt, as ferramentas ou o modelo mudarem. Veja os testes e a avaliação de prompts.
Para o laço de raciocínio por baixo de tudo isso, veja o prompting ReAct.