Como um agente difere de um chat comum
Se alguém me mostrasse cinco passos fixos e chamasse isso de agente, eu perguntaria: o sistema consegue escolher outra ferramenta quando a situação muda? Se não, é um workflow — e isso é perfeitamente ok.
O erro que eu eliminaria primeiro: Adicionar dez ferramentas «para depois» é o jeito mais rápido de obter um sistema imprevisível. Um agente não precisa de acesso máximo — precisa de um trabalho e de uma lista curta de ações permitidas.
O que preparar e qual resultado esperar
- Resultado: Você vai entender se precisa mesmo de um agente, quais permissões conceder e quais ações deixar só depois da aprovação.
- Desenhe o mapa objetivo → contexto → ferramentas → verificação → ação, e marque à parte onde a confirmação humana é necessária.
- Mantenha os dados de origem e os direitos de acesso separados da saída para auditar o que o AI agent with a tool fez.
- Teste três pedidos: uma pergunta sem ação, uma leitura e um pedido para alterar um registro. O agente precisa distingui-los.
Construa o primeiro agente sem permissões em excesso
- Descreva o objetivo em uma frase
Escreva: «Ajudar um gestor a triar uma solicitação e propor o próximo passo.» Não comece com «construir um agente universal para o negócio».
Проверьте: O objetivo tem um resultado claro que se pode aceitar ou rejeitar.
Если не сработало: Estreite o objetivo a um papel e um processo.
- Crie um assistente com instrução limitada
Na UI do serviço de IA, abra Create assistant/agent e defina: «Coletar dados da solicitação, propor o próximo passo, não enviar mensagens sem confirmação.»
Проверьте: A instrução lista separadamente o permitido e o proibido.
Если не сработало: Reescreva as proibições como condições verificáveis, não como desejos.
- Conecte uma ferramenta
Comece com leitura de registro CRM ou busca em banco. Descreva as entradas record_id e requested_fields, e proíba acesso a todo o CRM.
Проверьте: A ferramenta retorna só os campos necessários e não tem acesso de escrita.
Если не сработало: Substitua o CRM real por uma tabela de teste.
- Coloque a aprovação antes da ação
Ative logs de execução e confirmação antes de write, send, delete ou mudanças de permissão. Mantenha o plano de ação ao lado do resultado.
Проверьте: Sem confirmação, o agente fisicamente não consegue executar uma ação sensível.
Если не сработало: Não confie no prompt: remova a ferramenta ou limite-a a somente leitura.
Uma checagem de um único fluxo
Desenhe a cadeia objetivo → contexto → escolha de ferramenta → verificação → ação → log. Exemplo: nova solicitação → ler o texto → achar duplicata no CRM → validar e-mail → criar tarefa em rascunho. Se você remover a ferramenta e o resultado não mudar, não precisa de um agente.
Descreva cada ferramenta como um contrato: nome, campos de entrada, valores permitidos, o que retorna e quando parar em erro. Não conecte o agente a todo o Google Drive nem a todo o CRM.
- Primeiro somente leitura, depois rascunho e só então uma ação limitada.
- Não confunda a capacidade de chamar uma API com o direito de tomar sozinho uma decisão de negócio.
Um teste que mostra o risco rápido
Dê ao agente uma entrada normal, um campo vazio, um conflito de dados, um documento vencido e um pedido fora do escopo. O resultado certo nem sempre é uma ação: muitas vezes é recusa, needs_human ou uma pergunta de esclarecimento. São esses ramos que você mostra ao responsável antes do lançamento.
O contrato da ferramenta importa mais que uma demo bonita
Para cada ferramenta, descreva name, input, allowed values, response e stop condition. Comece com `find_contact`, `get_open_deal`, `get_last_meeting` e `draft_followup`; ainda não conecte envio de e-mail. Mantenha só essa lista em `allowed_tools`.
Campos de run: `run_id`, `goal`, `allowed_tools`, `max_steps`, `tool_calls`, `requires_approval`, `final_output`, `error_code`, `started_at` e `finished_at`. No primeiro piloto, defina `max_steps = 6`, `max_retries_per_tool = 2` e persista o estado em uma tabela externa.
{
"type": "function",
"name": "find_contact",
"strict": true,
"parameters": {
"type": "object",
"properties": {"email": {"type": ["string", "null"]}},
"required": ["email"],
"additionalProperties": false
}
}Cinco entradas em que o agente deve parar
Teste uma solicitação normal, um campo vazio, um conflito de dados, um documento vencido e uma tarefa fora do escopo. O resultado certo nem sempre é uma ação: pode ser `needs_approval`, `needs_clarification` ou `failed` com um motivo claro.
Quando você precisa de um agente vs automação comum
| Critério | Pergunta | Bom sinal |
|---|---|---|
| Entrada | O que exatamente entra no AI agent with a tool? | Desenhe o mapa objetivo → contexto → ferramentas → verificação → ação, e marque à parte onde a confirmação humana é necessária. |
| Ação | O que o sistema pode fazer sozinho? | Apenas ações pré-listadas, sem acesso a toda a conta |
| Verificação | Como você sabe que o resultado é aceitável? | Teste três pedidos: uma pergunta sem ação, uma leitura e um pedido para alterar um registro. O agente precisa distingui-los. |
| Falha | Para onde vai um caso pouco claro? | Pare a execução e devolva o resultado como rascunho se o agente não puder explicar qual ação está prestes a tomar. |
O que deve mudar depois da configuração
Você vai entender se precisa mesmo de um agente, quais permissões conceder e quais ações deixar só depois da aprovação.
Onde a autonomia vira risco
Chamar de agente qualquer chatbot mesmo quando só gera texto.
Dar direitos amplos ao agente e esperar que o prompt o pare.
Adicionar memória e cinco ferramentas antes de validar uma.
Não registrar qual ação o agente escolheu e por quê.
Quando o experimento já precisa de uma camada de engenharia
Traga um especialista quando o agente precisar trabalhar com vários sistemas, manter memória longa, executar ações em agenda ou lidar com dados sensíveis.
O que esclarecer antes de conectar ferramentas
Um agente sempre roda de forma autônoma?
Não. A autonomia é definida por ferramentas, permissões, regras e pontos de aprovação.
Quando um workflow comum basta?
Quando o caminho é conhecido de antemão: evento → filtro → ação. Um agente é necessário onde a próxima ação precisa ser escolhida.
Um agente precisa de memória?
Só se o contexto passado realmente afetar a decisão. Caso contrário, armazene os dados no sistema, não em memória oculta.
Qual primeira ferramenta conectar?
Uma ferramenta de leitura fácil de substituir por uma tabela de teste e validar em dez exemplos.
