Crea un'applicazione agente

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

Prima di iniziare

Assicurati di completare le istruzioni di configurazione prima di seguire questa guida.

Crea un'applicazione agente

Crea un'applicazione agente e un agente principale:

  1. Apri la console Gemini Enterprise for CX.
  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 principale per te.

Crea la gerarchia degli agenti

Questa applicazione di agenti utilizzerà tre agenti:

  • Agente principale per salutare l'utente e delegare ad altri subagenti.
  • Agente meteo per rispondere a domande relative al meteo.
  • L'agente ti saluta per completare la conversazione.

L'agente principale è già stato creato, ma devi aggiornare le impostazioni per questo agente:

  1. Fai clic sulla barra del titolo dell'agente principale.
  2. Puoi anche modificare il nome dell'agente.
  3. Inserisci la descrizione: "Gestisce saluti semplici e delega ad altri agenti".
  4. Fai clic su Salva, poi chiudi il pannello delle impostazioni.

Crea l'agente meteo:

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

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

screenshot of agent hierarchy

Crea uno strumento meteo

Gli strumenti vengono utilizzati per connettere l'agente a sistemi esterni o al codice incorporato 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 meteo. Ai fini di questa guida, questo strumento ha una risposta simulata per l'utente. In un'applicazione meteo reale, 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 dell'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.

Crea 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 gli strumenti di citazione, utilizza {@TOOL: tool_name}.

Crea istruzioni per ogni agente:

  1. Fai clic sul pulsante + nella barra del titolo dell'agente principale.
  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 chiusura:

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

Testare l'agente

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

  1. Nell'angolo in basso a sinistra della schermata della console, fai clic sulla barra Anteprima agente per espandere la finestra se non è già espansa.
  2. Digita "hello" (ciao) e premi Invio. L'agente risponde con un saluto generico.
  3. Digita "che tempo fa a New York?" e premi Invio. L'agente risponde con informazioni meteo.
  4. Digita "Arrivederci" e 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. Ciò consente agli agenti di ricordare le informazioni nei vari turni di conversazione, portando 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 "username" come nome della variabile.
  4. Lascia il tipo impostato su 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 dell'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 principale:

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

Aggiungi la seguente frase alle istruzioni dell'agente principale, 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 precise le tue informazioni?".

Tieni presente che ora l'agente risponde usando il tuo nome per ogni risposta. Puoi anche espandere le sezioni Passaggi della conversazione del simulatore, dove puoi verificare l'esecuzione dello strumento, 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 chiusura della sessione creando istruzioni esplicite.

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

Aggiungi quanto segue alle istruzioni dell'agente di chiusura:

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 vari tipi di callback che puoi utilizzare, ognuno dei quali viene eseguito in un punto specifico del turno conversazionale.

Per questo tutorial, aggiungi un messaggio statico alla risposta del modello al termine della sessione:

  1. Fai clic sulla barra del titolo dell'agente di commiato.
  2. Fai clic su Aggiungi callback.
  3. Seleziona After LLM (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 chiusura della sessione:

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

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

Istruzioni sulla struttura

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 ciascuno dei tuoi agenti:

  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 creato un agente funzionante, hai a disposizione diverse opzioni di deployment.