Crea un'applicazione agente

Questa guida illustra i passaggi per creare un'applicazione agente di base in grado di rispondere alle query degli utenti sul meteo.

Prima di iniziare

Prima di seguire questa guida, assicurati di completare le istruzioni di configurazione.

Creare un'applicazione agente

Crea un'applicazione agente e un agente root:

  1. Apri la console di CX Agent Studio.
  2. Seleziona il progetto.
  3. Fai clic su Crea agente o Nuovo agente.
  4. Fornisci "app meteo" come nome dell'agente.
  5. Fai clic su Crea. Se è la prima applicazione agente che hai creato per il progetto, la creazione potrebbe richiedere 1-2 minuti. Viene visualizzato il generatore di agenti e viene creato un agente root.

Creare la gerarchia degli agenti

Questa applicazione agente utilizzerà tre agenti:

  • Agente root per salutare l'utente e delegare ad altri subagenti.
  • Agente meteo per rispondere alle domande relative al meteo.
  • Agente di saluto per completare la conversazione.

L'agente root è già stato creato, ma devi aggiornarne le impostazioni:

  1. Fai clic sulla barra del titolo dell'agente root.
  2. Se vuoi, puoi modificare il nome dell'agente.
  3. Inserisci la descrizione: "Gestisce i saluti semplici e delega ad altri agenti".
  4. Fai clic su Salva, quindi chiudi il riquadro delle impostazioni.

Crea l'agente meteo:

  1. Fai clic sul pulsante + in fondo all'agente root.
  2. Fai clic su Aggiungi nuovo subagente.
  3. Fai clic sulla barra del titolo del nuovo agente.
  4. Modifica il nome in "Agente meteo".
  5. Inserisci la descrizione: "Gestisce tutte le domande relative al meteo dell'utente".
  6. Fai clic su Salva, quindi chiudi il riquadro delle impostazioni.

In modo simile, crea un altro subagente dell'agente root chiamato "Agente di saluto" con la descrizione "Gestisce i saluti e gli addii degli utenti".

screenshot of agent hierarchy

Creare uno strumento meteo

Gli strumenti vengono utilizzati per connettere l'agente a sistemi esterni o al codice in linea fornito all'agente. In questo modo, l'agente può interagire con altri sistemi per recuperare, aggiornare, formattare o analizzare le informazioni.

In questo passaggio, crei uno strumento meteo, che viene utilizzato per recuperare le informazioni sul meteo. Ai fini di questa guida, questo strumento ha una risposta simulata per l'utente. In una vera applicazione meteo, questo strumento accederebbe a un server esterno per ottenere informazioni.

Crea lo strumento meteo:

  1. Fai clic sul pulsante degli strumenti sul lato destro del generatore di agenti.
  2. Fai clic su + per creare un nuovo strumento per l'applicazione agente.
  3. Fai clic su Codice Python.

  4. Incolla il seguente codice:

    def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city.

  Returns:
    dict: A dictionary containing the weather information.
          Includes a 'status' key ('success' or 'error').
          If 'success', includes a 'report' key with weather details.
          If 'error', includes an 'error_message' key.
  """
  city_normalized = city.lower().replace(" ", "")

  mock_weather_db = {
    "newyork": {"status": "success",
      "report": "The weather in New York is sunny and 25°C."},
    "london": {"status": "success",
      "report": "It's cloudy in London and  15°C."},
    "tokyo": {"status": "success",
      "report": "Tokyo is experiencing light rain and 18°C."},
  }
  if city_normalized in mock_weather_db:
    return mock_weather_db[city_normalized]
  else:
    return {"status": "error",
      "error_message": f"No weather information for '{city}'."}

  5. Fai clic su Crea.

Ora devi aggiungere questo strumento all'agente meteo:

  1. Fai clic sul pulsante + nella barra del titolo dell'agente meteo.
  2. Fai clic su Aggiungi strumento.
  3. Seleziona lo strumento meteo.

Creare istruzioni per l'agente

Ogni agente ha un insieme di istruzioni che definiscono cosa deve fare.

Quando fornisci istruzioni che fanno riferimento a un agente, utilizza la sintassi {@AGENT: Agent name}. Per fare riferimento agli strumenti, utilizza {@TOOL: tool_name}.

Crea istruzioni per ogni agente:

  1. Fai clic sul pulsante + nella barra del titolo dell'agente root.
  2. Fai clic su Aggiungi istruzioni.

  3. Inserisci le seguenti istruzioni:

    You are a helpful weather application.
Your job is to greet the user and delegate to other sub-agents as needed.
When greeting the user, describe how you can help them.
When the user asks for the weather, delegate to {@AGENT: Weather agent}.
When the user is ending the conversation,
delegate to {@AGENT: Farewell agent}.
Handle only weather requests, greetings, and farewells.

  4. Fai clic su Crea.

  5. In modo simile, aggiungi le seguenti istruzioni per l'agente meteo:

    You are a helpful weather agent.
When the user asks for the weather in a specific city,
use {@TOOL: get_weather} to find the information.
If the tool returns an error, inform the user politely.
If the tool is successful, present the weather report clearly.

  6. In modo simile, aggiungi le seguenti istruzioni per l'agente di saluto:

    You are the Farewell Agent.
Your ONLY task is to provide a polite goodbye message.

Testare l'agente

L'applicazione agente è ora pronta per le interazioni utilizzando il simulatore:

  1. Nell'angolo in basso a sinistra della schermata della console, fai clic sulla barra Visualizza in anteprima l'agente per espandere la finestra, se non è già espansa.
  2. Digita "ciao", quindi premi Invio. L'agente risponde con un saluto generico.
  3. Digita "qual è il meteo a New York?", quindi premi Invio. L'agente risponde con le informazioni sul meteo.
  4. Digita "arrivederci", quindi premi Invio. L'agente conclude la conversazione.

Utilizzare le variabili

Le variabili vengono utilizzate per archiviare e recuperare i dati della conversazione in fase di runtime. In questo modo, gli agenti possono ricordare le informazioni tra i turni di conversazione, il che porta a interazioni più contestuali. Per questo agente, creerai una variabile che acquisisce il nome dell'utente.

Per creare la variabile:

  1. Fai clic sul pulsante delle variabili sul lato destro del generatore di agenti.
  2. Fai clic su Crea una variabile o +.
  3. Digita "nomeutente" come nome della variabile.
  4. Lascia il tipo come Testo.
  5. Fai clic su Crea.

Ora che hai definito la variabile, devi definire uno strumento che consenta all'agente di aggiornarla:

  1. Fai clic sul pulsante degli strumenti sul lato destro del generatore di agenti.
  2. Fai clic su + per creare un nuovo strumento per l'applicazione agente.
  3. Fai clic su Codice Python.

  4. Incolla il seguente codice:

    from typing import Optional

def update_username(username: str) -> Optional[str]:
  """Updates the current user's name"""
  set_variable("username", username)

  5. Fai clic su Crea.

Aggiungi questo strumento all'agente root:

  1. Fai clic sul pulsante + nella barra del titolo dell'agente root.
  2. Fai clic su Aggiungi strumento.
  3. Seleziona lo strumento update_username.

Aggiungi la seguente frase alle istruzioni dell'agente root, che fa riferimento alla variabile utilizzando la sintassi {variable_name}:

If provided, the current user is {username},
and you should address them with this name.
You can use {@TOOL: update_username} to update the user's name if they provide
it.

Puoi testare di nuovo l'agente per verificare l'utilizzo delle variabili:

  1. Fai clic su Avvia nuova conversazione nella barra del titolo del simulatore.
  2. Inserisci "Ciao, mi chiamo Frank".
  3. Inserisci "Quanto sono accurate le tue informazioni?".

Tieni presente che l'agente ora risponde utilizzando il tuo nome per ogni risposta. Puoi anche espandere le sezioni Passaggi della conversazione del simulatore, dove puoi verificare l'esecuzione degli strumenti, tra le altre cose.

Controllare come terminare la sessione

Per impostazione predefinita, ogni agente è configurato per utilizzare lo end_session strumento di sistema, tuttavia, puoi migliorare l'affidabilità e il controllo della modalità di terminazione della sessione creando istruzioni esplicite.

Rimuovi gli strumenti end_session dagli agenti root e meteo facendo clic sulla x accanto allo strumento in ogni agente. In questo modo, solo l'agente di saluto terminerà la sessione.

Aggiungi quanto segue alle istruzioni dell'agente di saluto:

After providing the goodbye message and confirming the user has no more
questions, execute the tool {@TOOL: end_session}(reason="success").

Utilizzare un callback per applicare un messaggio statico alla fine della sessione

I callback forniscono un meccanismo per collegarsi al processo di esecuzione di un agente specifico utilizzando il codice Python. Ti consentono di osservare, personalizzare e persino controllare il comportamento dell'agente in punti specifici e predefiniti.

Esistono diversi tipi di callback che puoi utilizzare, ognuno dei quali viene eseguito in un punto specifico del turno di conversazione.

Per questo tutorial, aggiungi un messaggio statico alla risposta del modello quando termini la sessione:

  1. Fai clic sulla barra del titolo dell'agente di saluto.
  2. Fai clic su Aggiungi callback.
  3. Seleziona Dopo LLM.

  4. Inserisci il seguente codice:

    SURVEY_MESSAGE = "Click here to take our post call survey."

def after_model_callback(
    callback_context: CallbackContext,
    llm_response: LlmResponse
) -> Optional[LlmResponse]:
  for index, part in enumerate(llm_response.content.parts):
    if part.has_function_call('end_session'):
      return LlmResponse.from_parts(parts=[
        *llm_response.content.parts,
        Part.from_text(SURVEY_MESSAGE)

    ])
  return None

  5. Fai clic su Fine.

  6. Fai clic su Salva.

Puoi testare di nuovo l'agente per verificare il comportamento di terminazione della sessione:

  1. Fai clic su Avvia nuova conversazione nella barra del titolo del simulatore.
  2. Inserisci "Ciao".
  3. Inserisci "Arrivederci".

Tieni presente che l'agente ora risponde utilizzando il messaggio aggiunto.

Strutturare le istruzioni

Per migliorare il comportamento dell'agente, puoi strutturare tutte le istruzioni dell'agente in un formato XML a forma libera ottimale per l'elaborazione del modello. Esegui le seguenti operazioni per ogni agente:

  1. Apri il riquadro delle istruzioni per un agente.
  2. Fai clic sul pulsante Struttura in alto a destra.
  3. Fai clic su Salva.

Esegui il deployment

Una volta che hai un agente funzionante, hai a disposizione diverse opzioni di deployment.