Referência de Ferramentas Nativas

Como Ler Esta Referência

Toda ferramenta nativa tem a mesma anatomia:

• Categoria — Tool para recuperação somente leitura, Action para qualquer coisa que grave no Salesforce.
• Confirmação — se o agente mostra um cartão de confirmação de ação antes de executar. Todas as ferramentas de ação confirmam por padrão; as ferramentas de leitura nunca confirmam.
• Canais — quais canais de implantação podem usar a ferramenta. Algumas ferramentas (exclusões, notificações internas) são intencionalmente restritas a usuários internos do Salesforce.
• Entrada em lote — se a ferramenta aceita um array de entradas em uma única chamada para reduzir idas e vindas ao modelo.
• Nível — o nível de ferramenta ao qual o agente precisa ter acesso. Consulte Sistema de Níveis de Ferramenta.

As ferramentas nativas aplicam segurança em nível de campo, CRUD e compartilhamento sob as permissões do usuário em execução — postura idêntica à de uma sessão normal do Salesforce.

Ferramentas de Leitura

As ferramentas de leitura recuperam dados e retornam JSON para o agente. Elas nunca gravam, portanto não exigem confirmação.

soql_query

Executa uma consulta SELECT somente leitura em modo usuário. CRUD, FLS e compartilhamento são aplicados. A plataforma acrescenta um LIMIT de linhas se a consulta não tiver nenhum, e limita o tamanho do resultado serializado. Consultas de agregação não agrupadas são isentas do LIMIT automático, para que os totais voltem com precisão. Use o formato em lote sempre que o agente precisar de mais de uma consulta em um turno — isso reduz substancialmente as idas e vindas ao modelo.

describe_object

Retorna o esquema de um ou mais objetos do Salesforce: nomes de API dos campos, rótulos, tipos de dados, referências de lista de seleção e campos de relacionamento. Armazenado em cache dentro da transação, de modo que chamadas repetidas no mesmo turno são gratuitas. O modo lote é a forma preferida quando o agente precisa conhecer vários objetos relacionados.

count_records

Retorna a contagem de linhas de um objeto, opcionalmente filtrada por uma cláusula WHERE. Mais barata que soql_query quando o agente só precisa de um número. Restrita a canais internos para que widgets voltados a convidados não possam enumerar o volume de registros.

get_record

Retorna um único registro pelo ID. Se fields não for especificado, a plataforma retorna até cinquenta campos do objeto que o usuário pode ler. Use-a quando o agente já souber o ID e só precisar dos valores mais recentes.

get_picklist_values

Retorna os valores ativos de lista de seleção de um campo, com rótulos, valores de API e o sinalizador de padrão. Útil antes de o agente tentar gravar em um campo de lista de seleção.

get_record_types

Retorna os tipos de registro ativos de um objeto. Use-a antes de create_record quando o objeto de destino tiver vários tipos de registro e o agente precisar escolher o correto.

Ferramentas de Ação

As ferramentas de ação alteram o estado do Salesforce. Toda ferramenta de ação exibe um cartão de confirmação por padrão; o usuário precisa aprovar antes de a plataforma executar. A confirmação pode ser desativada por agente em canais internos usando Executar Ações Automaticamente; em canais externos e de comunidade, ela permanece ativa. Consulte Confirmação de Ação para o fluxo completo.

create_record

Cria um novo registro no objeto informado com os valores de campo fornecidos. Regras de validação, campos obrigatórios e FLS se aplicam — o agente receberá uma resposta de erro estruturada se a gravação falhar.

update_record

Atualiza um registro existente pelo ID com as alterações de campo fornecidas. Somente os campos que o usuário pode editar realmente mudarão.

delete_record

Exclui um registro pelo ID. Restrita a canais internos porque é destrutiva e irreversível. A confirmação não pode ser executada automaticamente mesmo em canais internos — o usuário precisa aprovar cada exclusão.

create_task

Cria uma Tarefa do Salesforce. Por padrão, atribui a tarefa ao usuário em execução; informe assigned_to para atribuí-la a outra pessoa.

create_event

Cria um Evento de Calendário do Salesforce com carimbos de data/hora de início e término. O evento pertence ao usuário em execução.

send_email

Envia um e-mail pelo Salesforce como o usuário em execução. O agente deve resolver o e-mail do destinatário a partir de um registro de Contato ou Lead antes de chamar. related_to_id anexa o e-mail a um registro para o histórico de atividades; group_key agrupa vários e-mails enviados em uma única entrada de trilha de auditoria.

Escolhendo de quem o e-mail vem. Três entradas opcionais controlam a identidade do remetente, e as três são definidas pelas instruções do agente, e não por uma configuração. from_address indica o endereço de e-mail em nome da organização a partir do qual enviar — ele já precisa existir e estar verificado na Configuração e, se não puder ser associado, o e-mail ainda assim é enviado pelo remetente padrão e a divergência fica registrada, de modo que um agente nunca fica em silêncio por causa de um erro de digitação. sender_display_name define o nome exibido que o destinatário vê e se aplica apenas quando nenhum endereço em nome da organização está em uso. reply_to decide para onde as respostas vão — aponte-o para um endereço ligado ao roteamento de entrada e a resposta volta para a conversa. Um agente cujas instruções não passem nenhuma dessas entradas se comporta exatamente como antes. Consulte Canal de e-mail — Envio.

Carimbar seus próprios campos no e-mail. Cada e-mail que o agente envia cria um registro EmailMessage no Salesforce. Se você adicionou seus próprios campos personalizados a esse objeto — uma categoria, um código de campanha, um indicador de nível de serviço —, a entrada opcional field_values permite que o agente os preencha no envio, de modo que o e-mail chega já classificado em vez de precisar de uma atualização posterior. Ela é passada como um mapa de nome de API do campo para valor, por exemplo {"Outreach_Category__c": "Renovação", "Campaign_Code__c": "Q3-RENEW"}. Três regras a governam, e cada uma existe para impedir que um valor gerado pelo modelo cause dano:

• Apenas campos personalizados. Os nomes devem terminar em __c. Campos padrão como Subject, Status ou FromAddress são recusados: eles são definidos pelo próprio envio, e deixar o agente sobrescrevê-los corromperia o registro do que foi de fato enviado.
• O campo deve existir e ser gravável pelo usuário em execução. Os nomes são verificados contra o esquema real da sua organização antes de qualquer gravação. O que não for reconhecido é ignorado, não adivinhado.
• O e-mail nunca é perdido por causa de um campo inválido. Se um valor não puder ser aplicado, o envio ainda assim é bem-sucedido e o agente é informado exatamente de quais campos foram definidos e quais foram ignorados — para que possa relatar com precisão em vez de alegar uma classificação que não fez.

Nada disso é automático: o agente fornece field_values apenas quando suas instruções mandam, então agentes existentes não são afetados. Se você quiser que todos os e-mails de um agente sejam marcados da mesma forma, diga isso no prompt de Instruções personalizadas desse agente e nomeie o campo e o valor esperados.

send_custom_notification

Publica uma notificação de sino no aplicativo para um usuário do Salesforce (esta é a notificação do ícone de sino, não um e-mail). Útil para lembrar um colega sobre um registro que o agente acabou de criar ou atualizar.

link_file_to_record

Anexa um arquivo enviado a um registro do Salesforce criando um ContentDocumentLink. Se content_document_id for omitido, é usado o arquivo enviado mais recentemente na conversa. Esta é a combinação padrão para qualquer agente que processa documentos e depois precisa anexá-los ao registro relacionado.

schedule_action

Adia outra ação para ser executada mais tarde. Agende por carimbo de data/hora absoluto, por deslocamento relativo, ou por gatilho de resposta (por exemplo, “enviar quando o contato responder a este e-mail”). O trabalho adiado é criado como um registro de Ação Agendada e executado por um trabalho agendado. Consulte Ações Agendadas para o modelo de execução completo.

Condições. Os campos opcionais condition_field, condition_operator e condition_value são verificados novamente no momento em que a ação dispara, de modo que ela só é executada se a situação ainda for a mesma de quando foi agendada. condition_operator precisa ser um destes: equals, not_equals, contains, not_contains, is_blank ou not_blank — digitado exatamente assim, em todos os idiomas — e qualquer outro valor é rejeitado ao agendar a ação. Uma condição que não pode ser verificada ignora a ação em vez de deixá-la ser executada.

get_context_prompts

Busca as instruções adicionais configuradas para o objeto e o tipo de registro de um registro específico — útil quando o usuário menciona um registro que não fazia parte do contexto da conversa. Retorna uma lista vazia quando não há nenhuma, o que é normal, e o agente é instruído a não chamá-la repetidamente para o mesmo registro.

continue_workflow

Solicita um turno autônomo adicional para que um fluxo de trabalho continue em uma transação nova. Existe para o caso gravar–chamar–gravar: o agente acabou de criar ou atualizar um registro e agora precisa de uma chamada externa (ou de outra ferramenta) que depende do resultado confirmado. O turno seguinte é executado depois que as alterações atuais são confirmadas, então os novos registros e seus Ids ficam disponíveis para ele. Não é um botão genérico de “continuar”: um agente já pode ler, raciocinar e gravar vários registros dentro de um mesmo turno.

call_agent

Faz uma pergunta a outro agente no meio de uma conversa e retorna a resposta dele, para que um assistente geral possa consultar o agente que domina um assunto especializado em vez de tentar adivinhar. O agente consultado responde com as próprias instruções, ferramentas e acesso aos dados, é executado como a pessoa que está usando o assistente — portanto não enxerga nada além do que ela já poderia ver — e não pode realizar alterações por conta própria: tudo o que ele propõe volta para a conversa original para confirmação. Cada consulta custa um turno adicional e é mantida como uma conversa própria.

Só funciona depois que um administrador marca tanto Agente Invocável quanto Permitir Solicitações Automatizadas no agente que será consultado, e o quanto as consultas podem encadear é definido por Profundidade Máxima de Chamadas entre Agentes no agente que pergunta. A disponibilidade por si só não muda nada — são as instruções do agente que chama que decidem quando consultar. Consulte Delegação entre agentes.

Disponibilidade por Canal em Resumo

Modo de Entrada em Lote

Três das ferramentas de leitura aceitam um array de entradas em uma única chamada:

• soql_query — array queries (máx. 5)
• describe_object — array object_names (máx. 5)
• count_records — array counts (máx. 5)

O modo lote reduz as idas e vindas ao modelo quando o agente legitimamente precisa de mais de uma informação do mesmo tipo em um turno — por exemplo, descrever três objetos relacionados antes de compor uma consulta, ou contar registros em dois filtros de uma vez. O formato de entrada única continua funcionando; o lote é opcional.

Boas práticas

Atribua somente o que o agente precisa. Uma lista de ferramentas focada produz conversas mais rápidas e previsíveis. Não há benefício em atribuir todas as ferramentas nativas a todos os agentes.

Fique atento ao canal. Uma ferramenta restrita a canais internos não aparecerá para um usuário convidado no Widget Externo — mesmo que esteja atribuída ao agente. Verifique a coluna de canais quando um agente “esquecer” uma capacidade.

Prefira as ferramentas de leitura antes das gravações. Combine describe_object e get_picklist_values com create_record para que o agente escolha nomes de campo e valores de lista de seleção válidos; isso reduz drasticamente as falhas de regras de validação.

Escolha a ferramenta certa para a pergunta. count_records é muito mais barata que soql_query quando o agente só precisa de um número; get_record é muito mais barata que uma consulta completa quando o ID já é conhecido.

Ações de e-mail, registros e agendamento

Ações de e-mail distinguem o destinatário Contato ou Lead do registro de negócio relacionado, aceitam listas Para/Cc e verificam os casos compatíveis de recusa de e-mail. Contatos/Leads fornecidos como registros relacionados são tratados como destinatários. Confirmações de registros mostram campos não aplicados. As etapas do plano são conciliadas individualmente e horários relativos preservam UTC. Agentes desativados e ações aninhadas não permitidas são verificados antes de executar confirmações. Vínculos de arquivos usam a rota com controle de acesso. Novas ações pendentes ou reagendadas por horário exigem processador disponível; rastreamento de respostas e atualizações normais de histórico/status continuam válidos. Jobs posteriores usam seu proprietário de agendamento, sem personificar o solicitante. Orientações reduzem duplicação por outro conector, mas não garantem o comportamento do assistente.

Perguntas frequentes

Próximos passos

Leia Sistema de Níveis de Ferramenta para entender como funciona o acesso baseado em nível, ou Confirmação de Ação para o fluxo completo de confirmação que envolve toda ferramenta de ação.