Conectar um modelo a banco de dados, e-mail, terminal e serviços externos muda a natureza do sistema. Ele deixa de apenas produzir texto e passa a executar operações com consequências.
O desafio principal não é ensinar o agente a chamar uma função. É garantir que ele use a função certa, com argumentos válidos, dentro do escopo autorizado e com uma forma clara de recuperar ou interromper a operação.
Ferramentas pequenas são mais seguras
Uma ferramenta genérica como executar_comando oferece flexibilidade, mas transfere quase toda a política de segurança para o prompt. Uma ferramenta específica carrega intenção no próprio contrato:
type PublishPostInput = {
postId: string;
expectedRevision: number;
};
async function publishPost(input: PublishPostInput) {
// valida autorização, revisão e estado antes de publicar
}O agente não precisa inventar o procedimento de publicação. Ele escolhe uma operação explícita, e o servidor continua responsável por autenticação, autorização, validação e concorrência.
Uma boa ferramenta:
- executa uma ação reconhecível pelo usuário;
- recebe apenas os dados necessários;
- valida regras fora do modelo;
- retorna resultado estruturado;
- pode ser testada sem chamar o modelo.
Permissão deve acompanhar impacto
Ler uma lista pública, salvar um rascunho e apagar dados de produção não pertencem à mesma classe de risco.
Organize operações por impacto e defina controles proporcionais:
| Impacto | Exemplo | Controle |
|---|---|---|
| Baixo | consultar documentação | execução direta |
| Médio | criar rascunho | escopo limitado e registro |
| Alto | publicar ou enviar mensagem | confirmação humana |
| Crítico | excluir ou movimentar dinheiro | autorização forte e política determinística |
O modelo pode explicar e preparar a ação. A decisão final para operações irreversíveis deve permanecer em uma camada que não dependa apenas de interpretação probabilística.
Contexto precisa ter origem
Mais contexto não significa contexto melhor. Misturar instruções do sistema, dados recuperados e texto fornecido por terceiros aumenta o risco de o agente tratar conteúdo como ordem.
Registre a origem de cada bloco e mantenha separadas:
- políticas que o agente não pode alterar;
- instruções diretas do usuário;
- dados recuperados para consulta;
- resultados de ferramentas;
- memória derivada de interações anteriores.
Quando dados externos entram no processo, trate-os como dados. Uma página, um e-mail ou um documento não ganha autoridade para redefinir as regras do agente.
Toda ação precisa deixar rastro
Para depurar um agente, não basta salvar a resposta final. É necessário conhecer a sequência de decisões:
- modelo e versão usados;
- ferramentas oferecidas;
- ferramenta escolhida e argumentos;
- resultado retornado;
- permissões avaliadas;
- confirmações solicitadas;
- duração e custo de cada etapa.
Não registre segredos nem conteúdo sensível sem necessidade. O objetivo é reconstruir o comportamento com segurança, comparar versões e identificar onde uma decisão se desviou.
Falhar de forma controlada é parte do produto
Uma chamada pode expirar, um resultado pode ser ambíguo e uma dependência pode ficar indisponível. O agente precisa saber quando tentar novamente, quando pedir informação e quando parar.
Defina limites de tentativas, tempo e custo. Use chaves de idempotência em operações repetíveis. Valide o estado real antes de informar sucesso. E nunca transforme uma falha de ferramenta em uma afirmação inventada.
Agentes úteis não precisam de liberdade total. Precisam de um espaço de ação bem projetado, no qual capacidade e responsabilidade crescem juntas.