Ferramentas de Template SOQL

O que é uma Ferramenta de Template SOQL?

O Template SOQL é o mais leve dos três tipos do Construtor de Ferramentas. Use-o quando:

• Você quer que o agente recupere dados com uma consulta que você controla de ponta a ponta
• Você quer expor apenas parâmetros específicos — e não deixar o modelo redigir SOQL livremente
• O resultado é somente leitura — sem inserções, atualizações ou exclusões
• Você não quer escrever Apex

A consulta em si fica bloqueada em tempo de design. O agente só pode escolher qual ferramenta chamar e o que passar para cada parâmetro declarado; ele não pode reescrever o SOQL, trocar o objeto ou remover a cláusula WHERE.

Como Funciona uma Ferramenta de Template SOQL

Escrevendo o Template

Os placeholders usam chaves e seguem as regras padrão de identificadores (letra ou underscore primeiro, depois caracteres alfanuméricos ou underscore). Por exemplo:

SELECT Id, Name, AccountId, StageName, Amount, CloseDate
FROM Opportunity
WHERE StageName = '{stage}'
  AND CloseDate >= {start_date}
  AND CloseDate <= {end_date}
ORDER BY CloseDate ASC

Em tempo de execução, o agente fornece stage, start_date e end_date. Cada valor é escapado antes da substituição, de modo que uma entrada maliciosa ou malformada não consiga escapar da consulta.

O que você pode usar

• Qualquer consulta SELECT válida, incluindo subconsultas de relacionamento pai e de relacionamento filho
• Consultas agregadas (COUNT(), SUM(), GROUP BY) — a plataforma ignora o LIMIT automático para agregações não agrupadas, para que os totais voltem corretamente
• Vários placeholders em uma única consulta, em WHERE, ORDER BY, LIMIT, ou em qualquer lugar em que normalmente apareceria um literal
• Condições fixas no código para delimitar o que o agente pode ver — por exemplo, WHERE OwnerId = '{user_id}'

O que é bloqueado

• Qualquer coisa que não seja um SELECT — as palavras-chave INSERT, UPDATE, DELETE, UPSERT, MERGE e UNDELETE são rejeitadas no momento da validação
• Consultas que não resolvem nenhum parâmetro, mas ainda assim os exigem — placeholders que não estão no schema de entrada falham na validação
• Templates acima do limite de tamanho do campo SOQL Template

Campos da Definição de Ferramenta

Comportamento em Tempo de Execução

Escape e proteção contra injeção

Cada parâmetro passa pelo escape de aspas simples do SOQL antes da substituição, e a consulta resultante é verificada novamente para confirmar que ainda é uma única instrução SELECT sem palavras-chave DML. O agente não pode transformar um SELECT em uma operação DML, comentar cláusulas ou emendar uma segunda instrução.

FLS, CRUD e compartilhamento

As consultas são executadas em modo de usuário. Objetos, campos e linhas que o usuário em execução não pode ver não são retornados. Esse é o mesmo modelo de segurança que o restante da plataforma usa para as ferramentas nativas.

A única exceção é um agente com Contexto de execução = Sistema no canal de API, em que o acesso a objetos e campos é elevado. O compartilhamento de registros nunca é elevado — o executor continua with sharing, então mesmo um agente elevado ganha mais colunas, nunca mais linhas.

Limites de linhas

Se o template não tiver uma cláusula LIMIT, a plataforma adiciona uma com base na configuração de plataforma Max Query Rows. Consultas agregadas que não agrupam são isentas, para que os totais sejam precisos. O resultado serializado também tem o tamanho limitado por Max Query Result Length — payloads grandes demais são truncados e sinalizados para que o agente não estoure o contexto do modelo.

Formato do resultado

O agente recebe um objeto JSON:

{
  "totalSize": 12,
  "showing": 12,
  "records": [
    { "Id": "006...", "Name": "Acme Renewal", "Amount": 25000 },
    ...
  ]
}

Quando a exibição é limitada (mais linhas correspondem do que as exibidas ao agente), um campo note informa ao agente quantas linhas foram retornadas em relação ao que ele está vendo.

Uma consulta por chamada

As ferramentas de Template SOQL executam exatamente uma consulta por invocação. A ferramenta nativa soql_query da plataforma oferece um modo em lote que executa várias consultas em uma única viagem de ida e volta; as ferramentas de Template SOQL não. Se precisar de comportamento em lote, exponha a ferramenta nativa soql_query ao agente ou mova a lógica para uma ferramenta de Classe Apex.

Segurança e Governança

• Os parâmetros são escapados automaticamente. Você não precisa adicionar tratamento de aspas ao template.
• Aplicação exclusiva de SELECT. A consulta é rejeitada na validação e novamente na execução caso contenha palavras-chave DML.
• Execução em modo de usuário. As regras de CRUD, FLS e compartilhamento são aplicadas; o agente não consegue ver dados que o usuário não veria em uma sessão normal do Salesforce.
• Bloqueada em tempo de design. O agente não pode editar o SOQL nem o schema de parâmetros. Alterações exigem que um administrador atualize a Definição de Ferramenta.
• Trilha de auditoria. A chamada da ferramenta e seu resultado são registrados nos registros de Conversa e Mensagem, incluindo qual ferramenta foi usada e quais parâmetros foram passados.

Quando Usar Template SOQL em vez das Alternativas

Boas Práticas

Restrinja a consulta, não o agente. Incorpore limites rígidos no template — tipos de registro específicos, filtros de proprietário, condições de status — em vez de depender do agente para adicioná-los.

Nomeie os parâmetros de forma semântica. {stage} e {close_date_after} são mais claros para o modelo do que {p1} e {p2}. Os nomes aparecem no schema que o agente lê.

Sempre inclua os campos de que o agente precisa para responder. O agente só vê o que o SELECT retorna. Se o provável acompanhamento do usuário for “quem é o dono?”, adicione Owner.Name ao SELECT desde já.

Adicione um LIMIT explícito para resultados restritos. O LIMIT automático é uma rede de segurança, não uma ferramenta de ajuste fino. Se você sabe que a consulta nunca deve retornar mais de dez linhas, declare isso no template.

Teste no Construtor de Ferramentas antes de expor. O construtor permite executar o template com valores de parâmetro de exemplo e inspecionar a consulta substituída, os resultados e quaisquer avisos de validação.

Perguntas frequentes

Próximos passos

Leia a Referência de ferramentas integradas para conhecer as ferramentas nativas da plataforma que você pode expor aos agentes sem nenhuma configuração, ou avance para Entendendo os Campos de Contexto para controlar quais dados são incluídos automaticamente em cada conversa.