Creare agenti IA personalizzati con l’API Agente
Obiettivi di apprendimento
- Descrivere come iniziare a usare l’API Agente.
- Avviare una sessione con un agente IA utilizzando l’API Agente e gestire il ciclo di vita della sessione.
Iniziare a utilizzare l’API Agente
Sei uno sviluppatore e hai l’incarico di integrare Agentforce nel sito web, affinché gli agenti IA di Salesforce possano aiutare i clienti fornendo risposte rapide e utili alle loro domande.
Sai che questo semplificherà i tuoi flussi di lavoro e migliorerà le interazioni degli utenti, ma come si fa? Con l’API Agente.
Esaminiamo rapidamente i passaggi per rendere operativo Agentforce con l’API Agente.
Fase 1: abilitare Agentforce e attivare un agente
Innanzitutto devi abilitare Agentforce nell’organizzazione Salesforce. È un passaggio fondamentale, in mancanza del quale nessuna delle successive configurazioni può funzionare. Quando Agentforce è abilitato, devi attivare almeno un agente.
L’API Agente non supporta agenti del tipo “Agentforce (Default)” (Agentforce (predefinito)).
Fase 2: creare un’app client esterna e abilitare le impostazioni OAuth
Poi, devi creare un’app client esterna in Salesforce. Quest’app gestisce il flusso delle credenziali del client, che è essenziale per le chiamate API protette. Abilita le impostazioni OAuth per l’API.
Fase 3: ottenere la chiave consumatore e il segreto consumatore
Quando l’app è impostata, devi recuperare le credenziali della chiave consumatore e il segreto consumatore, che sono essenziali per autenticare le chiamate API. Le puoi trovare nell’app client esterna.
Fase 4: creare un token
Tutte le chiamate all’API Agente richiedono un token. Il token si usa per autenticare le chiamate API. Puoi creare un token usando la chiave consumatore, il segreto consumatore e il nome di dominio.
Fare la prima chiamata API di prova
Ora viene la parte divertente: effettuare chiamate all’API Agente.
Prima di effettuare una chiamata devi raccogliere alcune informazioni dall’organizzazione. Per maggiori informazioni, consulta Call the API (Chiamare l’API) nella guida per gli sviluppatori dell’API Agente.
In un’interfaccia a riga di comando, esegui questo comando curl per creare una nuova sessione agente con l’API Agente.
curl --location -X POST https://api.salesforce.com/einstein/ai-agent/v1/agents/{AGENT_ID}/sessions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--data '{
"externalSessionKey": "{RANDOM_UUID}",
"instanceConfig": {
"endpoint": "https://{MY_DOMAIN_URL}"
},
"streamingCapabilities": {
"chunkTypes": ["Text"]
},
"bypassUser": true
}'Quando la chiamata ha esito positivo, riceverai una risposta che contiene l’ID sessione e informazioni aggiuntive. Ecco un esempio di questo tipo di risposta.
{
"sessionId": "80ab2e16-392e-4c12-b80a-f028a58400b5",
"_links": {
"self": null,
"messages": {
"href": "https://api.salesforce.com/einstein/ai-agent/v1/sessions/80ab2e16-392e-4c12-b80a-f028a58400b5/messages"
},
"messagesStream": {
"href": "https://api.salesforce.com/einstein/ai-agent/v1/sessions/80ab2e16-392e-4c12-b80a-f028a58400b5/messages/stream"
},
"session": {
"href": "https://api.salesforce.com/einstein/ai-agent/v1/agents/0XxHr000000ysOSKAY/sessions"
},
"end": {
"href": "https://api.salesforce.com/einstein/ai-agent/v1/sessions/80ab2e16-392e-4c12-b80a-f028a58400b5"
}
},
"messages": [
{
"type": "Inform",
"id": "d27b7308-f1ab-47bd-949c-0225d5e21a8e",
"feedbackId": "",
"planId": "",
"isContentSafe": true,
"message": "Hi, I'm an AI service assistant. How can I help you?",
"result": [],
"citedReferences": []
}
]
}Ora puoi iniziare a inviare messaggi all’agente IA.
L’API Agente supporta sia la gestione dei messaggi sincroni sia la gestione dei messaggi in stream. I messaggi sincroni sono ideali per i casi d’uso in cui è necessario avere la risposta completa con un’unica chiamata, mentre i messaggi in stream sono più adatti alle interazioni in tempo reale, come le conversazioni via chat.
Quando hai finito, ricorda di chiudere la sessione.
Da tenere presente
-
Utilizzo dei dati: l’uso dell’API Agente comporta il consumo di crediti, secondo quanto indicato in Utilizzo e fatturazione dell’intelligenza artificiale generativa.
-
Timeout dell’API: l’API Agente scade dopo 120 secondi. Se una chiamata va oltre i 120 secondi riceverai una risposta HTTP 500.
Riepilogo
Ecco fatto. Usa l’articolo della guida Get Started with the Agent API (Iniziare a utilizzare l’API Agente) e il codice di esempio per iniziare a integrare Agentforce nel sito web e migliorare l’esperienza per i clienti.