Configuração de Ferramentas

O que Significa “Configuração de Ferramentas”

Um agente da REDA AI é a soma das suas ferramentas. Configurar o conjunto de ferramentas de um agente envolve três decisões:

• Quais ferramentas integradas o agente recebe. As 18 ferramentas fornecidas pela plataforma estão listadas na Referência de Ferramentas Integradas; atribua apenas as que cada agente realmente precisa.
• Quais ferramentas personalizadas você cria para ele. Quando as ferramentas integradas não cobrem um caso de uso, crie uma ferramenta personalizada de um dos três tipos: SOQL Template, Apex Class ou File Mapping.
• Como as ferramentas são delimitadas. Cada ferramenta pode ser restrita a canais, agentes e objetos de contexto específicos, para que a ferramenta certa apareça no contexto certo.

Atribuindo Ferramentas a um Agente

As ferramentas ficam disponíveis para um agente quando são atribuídas explicitamente. A plataforma nunca atribui ferramentas automaticamente a um novo agente.

Para efeitos de governança, a atribuição é feita por agente. Dois agentes no mesmo canal podem ter conjuntos de ferramentas completamente diferentes; a definição do agente é o limite.

Criando Ferramentas Personalizadas — o Tool Builder

Para qualquer coisa que as ferramentas integradas não cubram, o Tool Builder o guia na criação de uma ferramenta personalizada a partir de uma única tela. O builder é orientado por tipo — você escolhe que tipo de ferramenta deseja, e o formulário se adapta a essa escolha.

Etapa 1 — Escolha um tipo de ferramenta

Três cartões de tipo ficam na parte superior do builder:

O cartão escolhido é definitivo. As demais seções do builder se recolhem e se reorganizam em torno do tipo escolhido, de modo que você só vê os campos relevantes.

Etapa 2 — Bloqueio de categoria

Cada tipo de ferramenta tem uma categoria padrão sensata, e o builder a aplica de forma visível:

Quando uma categoria está bloqueada, o builder exibe um aviso de bloqueio explicando o motivo — para que os administradores não percam tempo tentando substituir uma restrição que o runtime rejeitaria de qualquer forma.

Etapa 3 — Configure os campos específicos do tipo

Cada tipo abre um conjunto diferente de blocos de configuração. Os detalhes estão nas páginas dedicadas:

• Ferramentas de Template SOQL — modelo de consulta, sintaxe de placeholders, esquema de entrada gerado automaticamente.
• Ferramentas de Classe Apex — nome da classe executora, esquema de entrada, contrato de retorno, flag de processamento de arquivo.
• Ferramentas de mapeamento de arquivos — objeto de destino, operação, mapeamento de coluna para campo, chave de correspondência.

Etapa 4 — Use o AI Generator

Para cada tipo, o builder oferece um AI Generator que produz uma ferramenta funcional a partir de uma breve descrição e de quaisquer entradas de referência que você fornecer:

• Para ferramentas SOQL Template, cole a consulta desejada (ou descreva o que você precisa) — o gerador extrai os placeholders e escreve o esquema de entrada com descrições completas.
• Para ferramentas Apex Class, descreva a operação, opcionalmente envie um arquivo de amostra quando a ferramenta for processar documentos, e o gerador produz o esquema de entrada e uma amostra dos dados que seu executor receberá.
• Para ferramentas File Mapping, envie um CSV de amostra mais uma descrição de uma linha; o gerador propõe o objeto de destino, a operação, o mapeamento e a chave de correspondência.

O resultado é sempre revisável — o gerador preenche o formulário, você edita qualquer coisa que não se encaixe e salva quando estiver satisfeito.

Etapa 5 — Acompanhe o painel de impacto ao vivo

Ao longo do builder, um painel de impacto exibe o que o agente realmente verá em tempo de execução:

• O nome e a descrição da ferramenta como aparecerão para o modelo
• O esquema de entrada no formato JSON exato enviado a cada solicitação
• A categoria, a camada e a delimitação de canais que regem quando a ferramenta é carregada
• Para ferramentas Action, uma pré-visualização do cartão de confirmação que o usuário verá
• Para ferramentas Apex Class com processamento de arquivo, uma amostra do formato dos dados extraídos que seu executor receberá

Essa é a forma mais rápida de identificar diferenças entre o que você quer e o que o agente vai ver — antes da primeira conversa real.

Etapa 6 — Salve e atribua

Salvar implanta a ferramenta por meio da Metadata API. O Tool Builder acompanha a implantação e avisa quando a ferramenta está em produção. Depois de implantada, atribua-a a um ou mais agentes pelo painel de Ferramentas do agente. As ferramentas não ficam implicitamente visíveis para os agentes — a atribuição é sempre explícita.

Delimitando o Escopo de uma Ferramenta

Toda definição de ferramenta tem campos de escopo que controlam onde e quando a ferramenta aparece:

Mantendo o Conjunto de Ferramentas Enxuto

Cada ferramenta que o agente tem custa tokens em cada solicitação — o modelo vê o nome, a descrição e o esquema de entrada da ferramenta mesmo quando não a utiliza. A otimização vem de três hábitos:

Atribua conforme a necessidade. Não atribua em excesso na expectativa de que o agente possa precisar de uma ferramenta algum dia. Adicione ferramentas quando uma conversa real precisar delas; remova ferramentas que não são acionadas há semanas.

Enxugue esquemas extensos. A definição de uma ferramenta é enviada em cada turno, então um esquema de entrada inchado é um imposto por turno. Mantenha as descrições concisas e os campos no mínimo, e confirme com o Conversation Debugger o que o modelo realmente viu. Consulte Carregamento e custo de ferramentas.

Substitua ferramentas do tipo describe por prompts quando os padrões forem estáveis. Se o agente sempre faz as mesmas perguntas de lista de seleção sobre o mesmo campo, codificar esse conhecimento no prompt do agente é mais barato do que chamar get_picklist_values em toda conversa. Consulte Prompts personalizados por agente.

Defina um teto por agente. Os três hábitos acima são questão de julgamento; duas configurações por agente os transformam em limites que o agente não pode ultrapassar. Máximo de ferramentas limita quantas ferramentas este agente oferece à IA por turno (1–100; em branco equivale a 25) — um teto direto para o custo por turno da própria lista de ferramentas. Máximo de iterações de ferramentas limita quantas etapas o agente pode dar dentro de um mesmo turno ao encadear ferramentas (3–25; em branco equivale a 6), que é o que impede um agente de entrar em loop em uma tarefa que não consegue concluir. Ambos ficam na seção Controles de desempenho e custo do registro de Definição de agente; consulte Desempenho e controle de custos.

Erros de Permissão em Tempo de Execução

As ferramentas são executadas sob as permissões do usuário em execução. Quando uma chamada de ferramenta falha porque o usuário não tem acesso:

• A ferramenta retorna um erro estruturado, não um stack trace
• O agente lê o erro e o explica ao usuário de forma conversacional
• A conversa continua — erros de permissão não travam o agente

Essa é a postura desejada: a plataforma herda o modelo de permissões do Salesforce, expõe as falhas de forma clara e permite que o agente ajude o usuário a resolvê-las. Não existe nenhum caminho que eleve o agente acima do acesso normal do usuário.

Boas Práticas

Crie por intenção, não por superfície de API. Uma ferramenta chamada “Enviar Cotação de Renovação” que encapsula um método Apex focado é muito mais confiável do que uma ferramenta genérica “Atualizar Registros” que o agente precisa decifrar. Ferramentas restritas produzem conversas previsíveis.

Invista nas descrições das ferramentas. A decisão do agente de chamar uma ferramenta depende quase inteiramente da descrição. Explique com clareza o que a ferramenta faz, quando usá-la e o que ela não faz.

Trave o que não deve mudar. Use ferramentas SOQL Template e File Mapping quando quiser um contrato estável. Use ferramentas Apex Class quando precisar de flexibilidade. Não dê ao agente mais liberdade do que o caso de uso realmente exige.

Use o painel de impacto. O passo de depuração mais rápido é ler a visão do agente no painel de impacto e confirmar que ela corresponde às suas expectativas.

Itere com o Conversation Debugger. Depois que a ferramenta está em produção, o Debugger mostra cada chamada de ferramenta feita pelo agente, suas entradas e seu resultado. A maioria dos problemas de ferramentas se torna óbvia ali.

Perguntas frequentes

Próximos Passos

Leia Confirmação de Ação para entender como as ferramentas Action aparecem para os usuários, ou escolha um tipo de ferramenta para se aprofundar: SOQL Template, Apex Class, ou File Mapping.