Crie seu agente usando o Agent Script (Script do agente)

Objetivos de aprendizagem

Neste emblema:

Saiba mais sobre o Agent Script (Script do agente) e os pacotes de autoria.
Pré-visualize um agente usando seu arquivo do Agent Script (Script do agente).
Codifique um agente, atualizando e validando seu arquivo do Agent Script (Script do agente).
Publique um agente em uma organização.
Visualize o agente publicado na IU do Agentforce Builder (Criador do Agentforce) da organização.

Para esta etapa, use a mesma organização Developer Edition que você criou na Etapa 1.

Nota

Deseja aprender em português (Brasil)? Comece o desafio em um Trailhead Playground de português (Brasil) e use as traduções fornecidas entre parênteses para navegar. Copie e cole somente os valores em inglês porque as validações dos desafios dependem de dados em inglês. Se você não passar no desafio em sua organização de português (Brasil), recomendamos que (1) mude o local para os Estados Unidos, (2) mude o idioma para inglês, seguindo as instruções aqui, e (3) clique novamente no botão “Validar o desafio”.

Consulte o emblema Trailhead no seu idioma para saber mais sobre como aproveitar a experiência de Trailhead em outros idiomas.

Conheça o Agent Script (Script do agente), o Agent Blueprint (Plano do agente)

Para criar um agente, siga um ciclo específico.

Develop (Desenvolva): Codifique o arquivo do Agent Script (Script do agente) para definir a lógica e as instruções do seu agente.
Publish (Publique): Implante o arquivo do Agent Script (Script do agente) numa organização de desenvolvimento para criar os metadados do agente.
Test (Teste): Verifique o comportamento do agente em uma sandbox ou em uma organização teste.
Deploy (Implante): Migre os metadados do agente para o seu ambiente de produção.
Activate (Ative): Ative o agente para disponibilizá-lo aos seus clientes.

O foco deste emblema está nas etapas de desenvolvimento e publicação.

O Agent Script (Script do agente) é a base da próxima geração dos Agentforce agents (Agentes do Agentforce). É uma linguagem que combina a flexibilidade da utilização da linguagem natural para um código exploratório, com a confiabilidade das expressões programáticas para o tratamento de regras de negócios. O Agent Script (Script do agente) lhe proporciona todas as vantagens do acesso a um grande modelo de linguagem (LLM) e, ao mesmo tempo, provê maneiras de adicionar mais comportamentos determinísticos ao seu agente.

Assim como a maioria dos elementos no Salesforce, um arquivo do Agent Script (Script do agente) faz parte de um componente de metadados chamado AiAuthoringBundle, ou simplesmente authoring bundle (pacote de autoria). Você pode gerar um pacote de autoria do zero usando comandos de CLI ou o VS Code no seu projeto DX, ou por vibe coding (codificação exploratória). Ou você pode primeiro criar um agente na sua organização usando o Agentforce Builder (Criador do Agentforce) e, em seguida, recuperar o pacote de autoria para o seu projeto DX. O pacote de autoria inclui um arquivo com extensão .agent; este é um arquivo do Agent Script (Script do agente) que serve como plano do agente.

Neste emblema do Trailhead, você começa com um pacote de autoria existente e um arquivo do Agent Script (Script do agente) no repositório que você clonou na unidade anterior. Pronto para começar?

No VS Code, abra o arquivo do Agent Script (Script do agente) chamado Local_Info_Agent.agent, localizado no diretório force-app/main/default/aiAuthoringBundles/Local_Info_Agent do projeto DX que você clonou na unidade anterior.

VS Code exibindo um arquivo de script do agente chamado Local_Info_Agent.agent.

Observe como o arquivo do Agent Script (Script do agente) exibe um realce de sintaxe com cores atraentes, indicações visuais (como ondulações vermelhas) para erros de sintaxe, navegação pelo código e assim por diante. Essas cores aparecem porque as extensões do Salesforce para o VS Code oferecem suporte ao Agent Script (Script do agente), como linguagem de programação, assim como também oferecem suporte ao Apex e ao LWC.

Aprender sobre a linguagem do Agent Script (Script do agente) em si está fora do escopo deste emblema, mas vale a pena dedicar alguns minutos para ter uma ideia geral do arquivo. Por exemplo, o arquivo é composto por blocos, como system (sistema), config (configuração) e variables (variáveis). O bloco config (configuração) contém parâmetros de configuração que definem o agente. Você vai mudar um desses parâmetros posteriormente neste emblema.

Confira Get Started with Agent Script (Introdução ao Script do agente) para obter mais informações e detalhes.

Pré-visualize o agente usando apenas seu arquivo do Agent Script (Script do agente)

À medida que você codifica o arquivo do Agent Script (Script do agente) do seu agente, é útil interagir com ele de vez em quando. Você pode verificar como ele reage à medida que você vai fazendo alterações e atualizações em tempo real. Essas pré-visualizações de conversas funcionam como testes interativos para garantir que o agente se comporte conforme o esperado.

Comece pré-visualizando um agente no modo simulado, que utiliza apenas o arquivo do Agent Script (Script do agente) para interagir e simular todas as ferramentas. Este módulo é particularmente útil se as classes do Apex, fluxos ou modelos de prompts que implementam as ferramentas ainda não estiverem disponíveis. O LLM usa as informações que você adicionou sobre os subagentes no arquivo do Agent Script (Script do agente) para simular o que a ferramenta faz ou como ela responde. Você vai acessar o LLM através da sua organização, e é por isso que você ainda necessita estar autorizado pela sua organização, mesmo no modo simulado.

No VS Code, abra o menu de contexto (clique com o botão direito do mouse) no arquivo do Agent Script (Script do agente) Local_Info_Agent.agent.
Selecione AFDX: Preview This Agent (Pré-visualizar este agente).
Um painel do Agentforce DX abre a esquerda.
Na lista suspensa Select agent… (Selecionar agente…), selecione Local_Info_Agent, que talvez já esteja selecionado.
Observe sua localização na seção do Agent Script (Script do agente) da lista. A menos que você tenha criado um agente novo, Local_Info_Agent deve ser o único agente na lista.
Na lista suspensa, selecione Simulation (Simulação) e, em seguida, clique em Start Simulation (Iniciar simulação) para iniciar a pré-visualização.
Na caixa de chat, digite esta pergunta para demonstrar o que o agente pode fazer: What can you help me with? (Em que você pode me ajudar?)
O agente fica pensando um pouco e então oferece uma resposta.
Insira esta pergunta:
```
What’s the weather like?
```

Você receberá um resumo do clima, mas você observou que o agente está falando como se fosse um pirata? Por exemplo, a resposta provavelmente começará com Arrr matey (Arr, marujo). Que estranho! O motivo pelo qual o agente está respondendo dessa forma é que seu arquivo do Agent Script (Script do agente) o está instruindo a falar como um pirata ao descrever o clima local.

Enquanto uma persona pirata é um jeito engraçado para testar a personalidade, agentes profissionais requerem uma voz de marca consistente. Saiba como modificar o arquivo do Agent Script (Script do agente) para refinar as respostas das interações com seu agente.

Codifique o arquivo do Agent Script (Script do agente)

Se você quiser alterar o comportamento do agente, basta codificar seu arquivo do Agent Script (Script do agente). À medida que você vai programando, valide o arquivo para garantir que não tenha introduzido nenhum erro. Provavelmente agora é um bom momento para que o agente pare de responder como um pirata. Você está pronto para aprender como fazer isso?

No VS Code, examine o arquivo do Agent Script (Script do agente) para verificar se você consegue encontrar a instrução que faz com que o agente responda como um pirata ao informar sobre o clima local.
Dica: Verifique as instruções de raciocínio para local_weather. Ainda não conseguiu encontrar? Procure por volta da linha 117, uma linha que comece com Finally, ALWAYS give answers (Finalmente, SEMPRE dê respostas).
Para editar o arquivo, remova toda a linha que começa com Finally, ALWAYS give answers (Finalmente, SEMPRE dê respostas). Não mude mais nada, a menos que você saiba o que está fazendo!
Salve o arquivo.
Abra o menu de contexto (clique com o botão direito do mouse) do arquivo do Agent Script (Script do agente) e selecione AFDX: Validate this Agent (Validar este agente).
Surge uma janelinha no canto inferior direito do VS Code enquanto o arquivo está sendo validado. Se a validação não for bem-sucedida, a guia Problems (Problemas) abre com as mensagens de erro e com dicas para ajudar você a resolver as questões. Mas, se você estiver acompanhando, o arquivo do Agent Script (Script do agente) deve ser validado com sucesso.
Clique em Restart Options (Reiniciar opções) e, em seguida, clique em Compile & Restart (Compilar & Reiniciar) no canto superior direito da janela de pré-visualização do Agentforce DX.
Insira a mesma pergunta (What’s the weather like? ) (Como está o clima?) na caixa de chat. Você também pode selecionar a seta para cima para usar o histórico do chat.
Dessa vez, a resposta deverá ser mais profissional, o que é bom, embora um pouco enfadonho.
Clique em Stop Simulation (Parar simulação) quando terminar de fazer perguntas.

Pré-visualize o agente usando o modo ao vivo

Quando você pré-visualiza o agente no modo ao vivo, ele usa as classes do Apex, fluxos e modelos de prompts reais na sua organização em desenvolvimento, para proporcionar uma visualização mais acurada do comportamento do seu agente.

Você já implantou as classes do Apex obrigatórias e os recursos relacionados na sua organização como parte da configuração inicial para este emblema do Trailhead. Se você alterar tudo isso posteriormente no seu projeto DX local, será necessário reimplantar, para garantir que a visualização ao vivo os utilize.

Você também utilizará um usuário real da organização nesta pré-visualização ao vivo, especificamente aquele que foi criado na unidade anterior. Isso requer uma alteração no arquivo do Agent Script (Script do agente). Mãos à obra!

No VS Code, abra o arquivo do Agent Script (Script do agente) Local_Info_Agent.agent no editor.
Na seção de configuração (por volta da linha 11), localize a propriedade default_agent_user.
Edite o arquivo do Agent Script (Script do agente), atualizando o espaço reservado UPDATE_WITH_YOUR_DEFAULT_AGENT_USER com o nome de usuário gerado pelo script na unidade anterior.
- Por exemplo, se o nome de usuário gerado for afdx-agent@testdrive.org98eca4a312-3456xyz, a propriedade atualizada ficará assim:
  default_agent_user: “afdx-agent@testdrive.org98eca4a312-3456xyz”
Valide o agente — uma das melhores práticas – sempre que você modificar um arquivo do Agent Script (Script do agente).
Se o painel do Agentforce DX não estiver aberto, selecione o menu de contexto (clique com o botão direito do mouse) em qualquer lugar do arquivo de script e selecione AFDX: Preview This Agent (Pré-visualizar este agente).
No menu suspenso, selecione Live Test (Teste ao vivo) e, em seguida, clique em Start Live Test (Iniciar teste ao vivo) para pré-visualizar o agente.
Faça a pergunta novamente: What’s the weather like? (Como está o clima?)

A resposta é semelhante à obtida quando você executou uma simulação, mas, desta vez, a faixa de temperatura deve estar exactly (exatamente) entre 65,3 °F e 81,1 °F. Isso ocorre porque o agente está utilizando a classe Apex real (WeatherService) na organização, a qual, para fins de teste, codifica a temperatura nessa faixa. Gostaria de ver por si mesmo? Confira o arquivo force-app/main/default/classes/WeatherService.cls.

Visualizar e alterar o agente no Agentforce Builder (Criador do Agentforce)

Volte para a IU do Agentforce Builder (Criador do Agentforce) da sua organização. Aqui você pode pré-visualizar e codificar seu agente, exatamente como você fez no VS Code. De fato, você vai alterar o agente para responder como um palhaço, porque nós decidimos que gostamos de palhaçadas e não de parecermos profissionais!

Mas antes de fazer isso, lembre-se de que você fez algumas alterações no arquivo do Agent Script (Script do agente) local. Para garantir que você está trabalhando com o mesmo código quando está usando o criador interno, você deve implantar o pacote de autoria Local_Info_Agent. Quando estiver usando ferramentas tanto profissionais quando as de pouco código, é importante que você mantenha sincronizados seu projeto DX e sua organização.

No VS Code, implante o pacote de autoria atualizado na sua organização executando este comando de CLI no terminal integrado.
sf project deploy start --metadata aiAuthoringBundle:Local_Info_Agent
O terminal exibe o status de implantação a seguir.
Para abrir o Agentforce Studio em um navegador, execute o seguinte comando CLI no termina integrado no VS Code:
sf org open authoring-bundle
Se aparecer uma mensagem indicando que você está no local errado, clique em Take me There (Leve-me até lá).
Na tabela, clique em Local Info Agent (Agente de informações locais) para abri-lo no Agentforce Builder (Criador do Agentforce). Se o agente não estiver disponível na tabela, execute novamente o comando sf org open authoring-bundle no VS Code.

Se você ainda não conhece o Agentforce Builder (Criador do Agentforce), explore seus recursos. Observe que a versão do Local Info Agent (Agente de informações locais) é a Version 1 (Draft) (Versão 1 (Rascunho)).

No Agentforce Builder (Criador do Agentforce), selecione a visualização do Script e adicione a seguinte instrução numa linha nova imediatamente depois da linha ALWAYS Provide forecasts that include a temperature range (SEMPRE forneça previsões que incluam uma faixa de temperatura) (por volta da linha 116):
```
Finally, ALWAYS give answers like you're a clown in a circus, using clown-themed language and expressions to make the interaction more engaging and fun for the user.
```
Clique em Save (Salvar).
Opcionalmente, use o botão Preview (Pré-visualização) para pré-visualizar o agente diretamente dentro da organização.
No VS Code, recupere o pacote de autoria atualizado para o seu projeto DX da sua organização executando este comando de CLI no terminal.
sf project retrieve start --metadata AiAuthoringBundle:Local_Info_Agent
Compile e reinicie a pré-visualização do modo ao vivo e então pergunte de novo sobre o clima. O agente deverá responder como um palhaço!

Publique o pacote de autoria

Quando você publica um pacote de autoria na sua organização, a organização usa o arquivo de Agent Script (Script do agente) para gerar os metadados do agente associado, sendo a versão inicial desses metadados ou versões novas. Os metadados do agente incluem componentes como Bot, BotVersion, GenAiPlannerBundle, GenAiFunction e outros. Esses metadados do agente resultam em um novo agente na sua organização, ou em uma nova versão de um agente existente. Você pode então testar esse agente publicado e, posteriormente, implantá-lo na sua organização de produção, para ativá-lo e disponibilizá-lo aos seus usuários. Por fim, seu projeto DX recupera todos os metadados novos ou atualizados da organização.

No VS Code, abra o arquivo do Agent Script (Script do agente) Local_Info_Agent.agent no editor.
Abra o menu de contexto (clique com o botão direito do mouse) do arquivo do Agent Script (Script do agente) e selecione AFDX: Publish this Agent (Publique este agente).
Verifique a guia Output (Saída) para acompanhar as etapas da publicação em andamento à medida que elas ocorrem. Confirme se você está usando o menu suspenso para filtrar as informações do Agentforce DX.
Use o Explorer para visualizar os metadados que foram recuperados no diretório do pacote force-app/main/default do seu projeto DX. Este exemplo mostra o arquivo XML do componente de metadados GenAiPlannerBundle aberto no editor.
Volte para o Agentforce Builder (Criador do Agentforce) na sua organização e atualize a página. Agora você deve ter uma versão confirmada do Local Info Agent (Agente de informações locais): Version 1 (Committed) Versão 1 (Confirmada).

Publicar um pacote de autoria gera novas versões dos metadados do agente, incluindo a BotVersion e o GenAiPlannerBundle. Você pode identificar estes como v1 na imagem anterior.

Ative seu agente

Disponibilize o agente de informações locais para que os hóspedes do Coral Cloud Resorts possam usá-lo. No VS Code, você pode ativar um agente usando seu arquivo de metadados BotVersion.

No VS Code, use o Explorer para navegar até o diretório force-app/main/default/bots/Local_Info_Agent.
Abra o menu de contexto (clique com o botão direito do mouse) no arquivo Local_Info_Agent.bot-meta.xml e selecione AFDX: Activate Agent (Ativar agente).
Clique em Version 1 (Versão 1) na lista suspensa no topo do VS Code.
Vá para o Agentforce Builder (Criador do Agentforce) na sua organização e atualize a página do Local Info Agent (Agente de informações locais). Agora você deve ter uma versão ativa do agente, como Version 1 (Active) (Versão 1 (Ativa)).

Parabéns! Você usou o Agentforce DX com sucesso para codificar um arquivo do Agent Script (Script do agente), pré-visualizar o agente e publicá-lo na sua organização. Com essas ferramentas de códigos profissionais à sua disposição, você já está pronto para criar seus próprios agentes. Antes de publicar um agente de produção, lembre-se de ajustar o tom de voz dele para garantir que seja adequado ao seu caso de uso específico.

Tempo estimado

Tópicos

Procurando ajuda?

Agentforce Recursos