Preparação para criar uma ação do Apex
Objetivos de aprendizagem
Após concluir esta unidade, você estará apto a:
- Preparar sua organização para criar ações.
- Verificar se seu Apex está pronto para ações.
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.
O novo Agentforce Builder já está disponível para o público em geral!
O Agentforce foi atualizado! Em fevereiro de 2026, a nova experiência de criação de agentes foi disponibilizada para o público em geral. Este emblema utiliza o Builder antigo em vez do novo, mas será atualizado em breve. Para começar a usar o novo Builder agora, conclua a trilha Faça um tour pelo novo Agentforce Builder ou leia mais na documentação do Agentforce.
Previsão: céu ensolarado pela frente
Como qualquer pessoa que já tenha tirado férias sabe, ficar de olho no tempo é essencial para aproveitar ao máximo seus planos de viagem. E no Coral Cloud Resorts, os hóspedes podem esperar que o tempo esteja ensolarado e quente... até que não esteja mais. Para garantir que os hóspedes aproveitem ao máximo sua estadia, independentemente do clima, a equipe do Coral Cloud deseja adicionar a capacidade de coletar informações meteorológicas aos seus agentes de IA. Para isso, eles precisam criar uma ação que extraia dados meteorológicos de uma classe do Apex usando uma API externa.
Inscrever-se em uma organização Developer Edition com Agentforce
Para concluir este módulo, você precisará de uma organização Developer Edition especial que contenha o Agentforce e nossos dados de exemplo. Inscreva-se para obter essa organização Developer Edition com Agentforce personalizada e gratuita, clicando no link e conecte-a ao Trailhead agora para poder concluir os desafios deste módulo. Observe que essa organização foi projetada para lidar com os desafios deste emblema e pode não funcionar para outros emblemas. Verifique sempre se está usando o Trailhead Playground ou a organização Developer Edition especial recomendada.
- Inscreva-se para obter gratuitamente uma organização Developer Edition com Agentforce.
- Preencha o formulário:
- Em Email, insira um endereço de email ativo.
- Em Username (Nome de usuário), insira um nome de usuário que seja parecido com um endereço de email e seja exclusivo, mas não precisa ser uma conta de email válida (por exemplo, seunome@example.com).
- Em Email, insira um endereço de email ativo.
- Após preencher o formulário, clique em Inscrever-me. Uma mensagem de confirmação aparece.
- Quando receber o email de ativação (pode demorar alguns minutos), abra-o e clique em Verificar conta.
- Conclua seu registro ao configurar sua senha e pergunta de segurança. Dica: Salve seu nome de usuário, senha e URL de login em um local seguro, como um gerenciador de senhas, para facilitar o acesso posterior.
- Você está conectado à Developer Edition.
Agora, conecte sua nova organização Developer Edition ao Trailhead.
- Verifique se você está conectado à sua conta do Trailhead.
- Na seção Challenge (Desafio) no final desta página, clique no nome do organização e em Connect Org (Conectar a organização).
- Na tela de login, insira o nome de usuário e a senha da Developer Edition que você acabou de configurar.
- Na tela Permitir acesso?, clique em Permitir.
- Na tela Want to connect this org for hands-on challenges? (Deseja salvar essa organização para os desafios práticos?), clique em Yes! (Sim!) Save it (Salve). Você será redirecionado para a página de desafio e poderá usar sua nova Developer Edition para ganhar este emblema.
Preparar a organização para agentes
Antes de começar a personalizar os agentes, habilite todos os recursos de organização necessários.
- Clique em Setup (Configuração)
e selecione Setup (Configuração).
- Em Setup (Configuração), na caixa Quick Find (Busca rápida), procure e selecione Einstein Setup (Configuração do Einstein).
- Verifique se o Einstein está na posição On (Ativado). Se já estiver On (Ativado), ponha-o na posição Off (Desativado) e novamente na posição On (Ativado).
- Atualize seu navegador para recarregar Setup (Configuração).
- Em Setup (Configuração), na caixa Quick Find (Busca rápida), procure e selecione Salesforce Go.
- Na caixa de texto Search features... (Recursos de pesquisa...), digite e selecione Agentforce (Default) (Agentforce (Padrão)).
- Clique em Get Started (Começar a usar).
- Clique em Turn On (Habilitar).
- Clique em Confirm (Confirmar).
Criar ações de agente com a funcionalidade que você já possui
Muito bem! Você está quase pronto para criar uma ação personalizada para seu agente. Uma das principais razões para criar agentes de IA com o Salesforce é que você pode usar a funcionalidade que já está incorporada à sua organização. Neste caso, você deseja adicionar as informações meteorológicas do Coral Cloud Resort a um agente de IA. O Coral Cloud já possui uma classe WeatherService do Apex para obter as condições meteorológicas da localização do Coral Cloud Resort a partir de uma API externa. Vamos ver como isso se aplica a uma ação.
public with sharing class WeatherService {
/**
* Gets the weather at Coral Cloud Resorts for the provided date
*/
public static Weather getResortWeather(Datetime dateToCheck) {
Integer currentYear = Date.today().year();
Integer yearDelta = currentYear - dateToCheck.year();
dateToCheck = dateToCheck.addYears(yearDelta);
String isoDate = dateToCheck.format('yyyy-MM-dd');
String dateString = dateToCheck.format('MMMM d');
// Prepare API request
HttpRequest req = new HttpRequest();
req.setEndpoint(
'callout:Weather_Endpoint/weather?lat=37.789782764570425&lon=-122.39723702244089&date=' +
isoDate
);
req.setMethod('GET');
// Make callout
Http http = new Http();
HttpResponse res = http.send(req);
if (res.getStatusCode() != 200) {
throw new CalloutException('Bad response: ' + res);
}
// The response contains a list of temperatures for different times of the day
// We parse the response and find the min and max temperatures
String body = res.getBody();
WeatherApiResponse weatherResponse = (WeatherApiResponse) JSON.deserialize(
body,
WeatherAPIResponse.class
);
List<Decimal> temperatures = new List<Decimal>();
for (TemperatureWrapper item : weatherResponse.weather) {
if (item.temperature != null) {
temperatures.add(item.temperature);
}
}
temperatures.sort();
// Prepare temperatures and description
Decimal minTempC = temperatures[0];
Decimal maxTempC = temperatures[temperatures.size() - 1];
Decimal minTempF = toFahrenheit(minTempC);
Decimal maxTempF = toFahrenheit(maxTempC);
String description =
'On ' +
dateString +
', temperature should be between ' +
minTempC +
'°C (' +
minTempF +
'°F) and ' +
maxTempC +
'°C (' +
maxTempF +
'°F) at Coral Cloud Resorts.';
// Return weather info
Weather weather = new Weather();
weather.minTemperatureC = minTempC;
weather.minTemperatureF = minTempF;
weather.maxTemperatureC = maxTempC;
weather.maxTemperatureF = maxTempF;
weather.description = description;
return weather;
}
private static Decimal toFahrenheit(Decimal celsius) {
return (celsius * 9 / 5 + 32).setScale(1);
}
private class WeatherApiResponse {
public List<TemperatureWrapper> weather;
}
private class TemperatureWrapper {
public Decimal temperature;
}
public class Weather {
public Decimal minTemperatureC;
public Decimal minTemperatureF;
public Decimal maxTemperatureC;
public Decimal maxTemperatureF;
public String description;
}
}Esta é uma classe do Apex simples que faz uma solicitação HTTP a um serviço meteorológico para obter a previsão do tempo para o dia inserido. No entanto, a classe do Apex não está disponível para uso pelo Criador do Agentforce. Você poderia atualizar essa classe para torná-la um método invocável, mas a melhor prática é criar uma nova classe do Apex definida como InvocableMethod que chame o WeatherService original. A anotação InvocableMethod permite chamar códigos Apex personalizados a partir de ferramentas declarativas como Fluxos, aplicativos externos via REST e Agentforce.
A boa notícia é que a equipe do Coral Cloud criou uma classe do Apex que já está fazendo chamadas para WeatherService. Vamos dar uma olhada na classe e ver como ela implementa o WeatherService.
public with sharing class CheckWeather {
@InvocableMethod(
label='Check Weather'
description='Check weather at Coral Cloud Resorts at a specific date'
)
public static List<WeatherResponse> getWeather(
List<WeatherRequest> requests
) {
// Retrieve the date for which we want to check the weather
Datetime dateToCheck = (Datetime) requests[0].dateToCheck;
WeatherService.Weather weather = WeatherService.getResortWeather(
dateToCheck
);
// Create the response for Copilot
WeatherResponse response = new WeatherResponse();
response.minTemperature = weather.minTemperatureC;
response.maxTemperature = weather.maxTemperatureC;
response.temperatureDescription =
'Temperatures will be between ' +
weather.minTemperatureC +
'°C (' +
weather.minTemperatureF +
'°F) and ' +
weather.maxTemperatureC +
'°C (' +
weather.maxTemperatureF +
'°F) at Coral Cloud.';
return new List<WeatherResponse>{ response };
}
public class WeatherRequest {
@InvocableVariable(
required=true
description='Date for which we want to check the temperature. The variable needs to be an Apex Date type with format yyyy-MM-dd.'
)
public Date dateToCheck;
}
public class WeatherResponse {
@InvocableVariable(
description='Minimum temperature in Celsius at Coral Cloud Resorts location for the provided date'
)
public Decimal minTemperature;
@InvocableVariable(
description='Maximum temperature in Celsius at Coral Cloud Resorts location for the provided date'
)
public Decimal maxTemperature;
@InvocableVariable(
description='Description of temperatures at Coral Cloud Resorts location for the provided date'
)
public String temperatureDescription;
}
}A primeira coisa a se notar é a anotação @InvocableMethod para o método getWeather. Os dois parâmetros passados são usados no processo Create an Agent Action (Criar uma ação do agente). O parâmetro label (rótulo) é exibido como Agent Action Label (Rótulo da ação do agente). O parâmetro description (descrição) é exibido como Agent Action Instructions (Instruções de ação do agente). As descrições são importantes para os agentes de IA e para a forma como o agente compreende o método.
Existem duas classes públicas, WeatherRequest e WeatherResponse , que têm anotações @InvocableVariable para as entradas e saídas da ação Create an Agent Action (Criar uma ação do agente), respectivamente.
Para WeatherRequest, a anotação @InvocableVariable para dateToCheck, tem o parâmetro required (obrigatório) definido como true (verdadeiro). Isso faz com que a configuração Require Input (Solicitar entrada) da ação Create an Agent Action (Criar uma ação do agente) seja marcada por padrão. O parâmetro description (descrição) será exibido como Input Instructions (Instruções de entrada). Além disso, ao configurar o tipo de variável como Date (Data) para dateToCheck define-se o tipo de dados de entrada.
Para WeatherResponse, existem três variáveis com a anotação @InvocableVariable: minTemperature, maxTemperature e temperatureDescription. Cada uma delas tem um conjunto de parâmetros description (descrição) que é exibido em Outputs Instructions (Instruções de saída) da ação Create an Agent Action (Criar uma ação do agente). Além disso, os tipos de variáveis Decimal, Decimal e String (Sequência de caracteres) são exibidos como Output Rendering (Renderização de saída). O tipo de variável String (Sequência de caracteres) será definido como Text for Output Rendering (Texto para renderização de saída).
Configurar as permissões
Assim como qualquer funcionalidade do Apex, você precisa ter o acesso correto ao arquivo do Apex. Essa etapa já foi concluída na organização de desenvolvimento personalizada que você está usando para este emblema. As permissões já foram configuradas, dando ao agente de IA acesso à classe do Apex que contém o método invocável por meio de um conjunto de permissões. Do contrário, o agente não poderia considerá-lo ao criar um plano, mesmo que você criasse uma ação e a adicionasse a um agente. A falta de permissão adequada é uma das principais razões pelas quais as ações do Apex não funcionam como esperado no Agentforce.
Agora você tem uma ideia melhor do que é necessário para que o Apex seja usado para ações. É um pouco difícil de assimilar, mas fará mais sentido quando você desenvolver a ação na próxima unidade.