Guida rapida all'utilizzo dell'Agent Development Kit

Dopo aver configurato l'agente Agent Development Kit (ADK) per utilizzare le sessioni e la banca di memoria di Vertex AI Agent Engine, l'agente legge e scrive automaticamente le memorie e le sessioni per te.

Per la guida rapida all'utilizzo dell'API REST, consulta Guida rapida all'utilizzo dell'API REST.

Questo tutorial mostra come utilizzare le sessioni e la banca di memoria di Vertex AI Agent Engine con l'ADK per creare e utilizzare sessioni e ricordi a lungo termine:

  1. Crea l'istanza di Vertex AI Agent Engine per accedere a Sessioni e Banca della memoria di Vertex AI Agent Engine.

  2. Crea l'agente e il runner ADK locali.

  3. Interagisci con il tuo agente per generare dinamicamente ricordi a lungo termine accessibili in tutte le sessioni.

  4. Pulisci.

Prima di iniziare

Per completare i passaggi illustrati in questo tutorial, devi prima configurare il progetto e l'ambiente.

Configura il progetto

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI API.

    Enable the API

    8.
  8. Se hai selezionato un progetto, assicurati di disporre del ruolo IAM Vertex AI User (roles/aiplatform.user) sul progetto.

    9. Autenticarsi in Vertex AI

    Per utilizzare gli esempi di Python questa pagina in un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

    1. Install the Google Cloud CLI.

    2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    3. To initialize the gcloud CLI, run the following command: 

      gcloud init

    4. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale nella documentazione sull'autenticazione Google Cloud .

    Importare librerie

    Installa l'Agent Development Kit e l'SDK Vertex AI:

    pip install google-adk>=1.5.0
pip install google-cloud-aiplatform>=1.100.0

    Imposta le variabili di ambiente

    Per utilizzare l'ADK, imposta le variabili di ambiente:

    import os

os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto.
    • LOCATION: La tua regione. Per il Memory Bank di Vertex AI Agent Engine è supportato solo us-central1.

    Crea l'istanza di Vertex AI Agent Engine

    Per accedere a Vertex AI Agent Engine Sessions e Vertex AI Agent Engine Memory Bank, devi prima creare un'istanza di Vertex AI Agent Engine. Per iniziare a utilizzare Sessioni e Banca della memoria, non devi eseguire il deployment di alcun codice. Senza il deployment del codice, la creazione di un'istanza di Vertex AI Agent Engine dovrebbe richiedere pochi secondi.

    import vertexai

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
)

agent_engine = client.agent_engines.create()

    Crea l'agente ADK

    1. Quando sviluppi il tuo agente ADK, includi uno strumento Memory, che controlla quando viene utilizzato il servizio di memoria e come i ricordi vengono inclusi nel prompt. L'agente di esempio utilizza PreloadMemoryTool, che recupera sempre i ricordi all'inizio di ogni turno e li include nell'istruzione di sistema:

      from google import adk

agent = adk.Agent(
    model="gemini-2.0-flash",
    name='stateful_agent',
    instruction="""You are a Vehicle Voice Agent, designed to assist users with information and in-vehicle actions.

1.  **Direct Action:** If a user requests a specific vehicle function (e.g., "turn on the AC"), execute it immediately using the corresponding tool. You don't have the outcome of the actual tool execution, so provide a hypothetical tool execution outcome.
2.  **Information Retrieval:** Respond concisely to general information requests with your own knowledge (e.g., restaurant recommendation).
3.  **Clarity:** When necessary, try to seek clarification to better understand the user's needs and preference before taking an action.
4.  **Brevity:** Limit responses to under 30 words.
""",
    tools=[adk.tools.preload_memory_tool.PreloadMemoryTool()]
)

    2. Crea un servizio di memoria VertexAiMemoryBankService, che il runner ADK utilizza per recuperare i ricordi.

      from google.adk.memory import VertexAiMemoryBankService

agent_engine_id = agent_engine.api_resource.name.split("/")[-1]

memory_service = VertexAiMemoryBankService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id=agent_engine_id
)

    3. Crea un runner ADK, che coordina l'esecuzione di agenti, strumenti e callback.

      from google.adk.sessions import VertexAiSessionService

# You can use any ADK session service.
session_service = VertexAiSessionService(
    project_id="PROJECT_ID",
    location="LOCATION",
    agent_engine_id=agent_engine_id
)

app_name="APP_NAME"
runner = adk.Runner(
    agent=agent,
    app_name=app_name,
    session_service=session_service,
    memory_service=memory_service
)

def call_agent(query, session, user_id):
  content = types.Content(role='user', parts=[types.Part(text=query)])
  events = runner.run(user_id=user_id, session_id=session, new_message=content)

  for event in events:
      if event.is_final_response():
          final_response = event.content.parts[0].text
          print("Agent Response: ", final_response)

      Sostituisci quanto segue:

      • APP_NAME: Il nome dell'app ADK.

    Interagire con l'agente

    Dopo aver definito l'agente e configurato Sessioni e Banca della memoria, puoi interagire con l'agente.

    1. Crea la tua prima sessione. Poiché non sono disponibili ricordi durante la prima sessione con un utente, l'agente non conosce le preferenze dell'utente, ad esempio la temperatura preferita:

      session = await session_service.create_session(
    app_name=app_name,
    user_id="USER_ID"
)

call_agent(
    "Can you update the temperature to my preferred temperature?",
    session.id,
    "USER_ID"
)

# Agent response: "What is your preferred temperature?"
call_agent("I like it at 71 degrees", session.id, "USER_ID")
# Agent Response:  Setting the temperature to 71 degrees Fahrenheit.
# Temperature successfully changed.

      Sostituisci quanto segue:

      • USER_ID: un identificatore per l'utente. I ricordi generati da questa sessione sono identificati da questo identificatore opaco. L'ambito dei ricordi generati viene memorizzato come {"user_id": "USER_ID"}.

    2. Genera ricordi per la sessione corrente. Se Memory Bank estrae ricordi dalla conversazione, questi vengono archiviati nell'ambito {"user_id": USER_ID, "app_name": APP_NAME}.

      session = await session_service.get_session(
    app_name=app_name,
    user_id="USER_ID",
    session_id=session.id
)
await memory_service.add_session_to_memory(session)

    3. Crea la seconda sessione. Se hai utilizzato PreloadMemoryTool, l'agente recupera i ricordi all'inizio di ogni turno per accedere alle preferenze che l'utente ha comunicato in precedenza all'agente.

      session = await session_service.create_session(
    app_name=app_name,
    user_id="USER_ID"
)

call_agent("Fix the temperature!", session.id, "USER_ID")
# Agent Response:  Setting temperature to 71 degrees.  Is that correct?

    Esegui la pulizia

    Per eliminare tutte le risorse utilizzate in questo progetto, puoi eliminare il Google Cloud progetto utilizzato per la guida introduttiva.

    In alternativa, puoi eliminare le singole risorse che hai creato in questo tutorial nel seguente modo:

    1. Utilizza il seguente esempio di codice per eliminare l'istanza di Vertex AI Agent Engine, che elimina anche eventuali sessioni o ricordi appartenenti a Vertex AI Agent Engine.

      agent_engine.delete(force=True)

    2. Elimina tutti i file creati localmente.

    Passaggi successivi