Sviluppare ed eseguire il deployment di agenti su Agent Runtime con Agent Development Kit

Sviluppare ed eseguire il deployment di agenti su Agent Runtime con Agent Development Kit

Agent Runtime ti consente di ospitare agenti sviluppati con il Agent Development Kit (ADK). Questo documento spiega come creare, eseguire il deployment e testare un agente utilizzando ADK.

Questa guida rapida è composta dai seguenti passaggi:

• Configura il tuo Google Cloud progetto.
• Installa l'SDK Agent Platform per Python e ADK.
• Sviluppa un agente di cambio valuta.
• Esegui il deployment dell'agente su Agent Runtime.
• Testa l'agente di cui è stato eseguito il deployment.

Puoi anche utilizzare le seguenti guide rapide alternative per ADK:

• Guida rapida ADK: la guida rapida ADK viene eseguita interamente sul tuo computer e presuppone che tu stia utilizzando un IDE locale e l'accesso al terminale.
• Pacchetto di avvio dell'agente: una raccolta di modelli di agenti di AI generativa pronti per la produzione creati per Agent Platform.

Per la guida rapida che utilizza framework supportati diversi da Agent Development Kit, consulta Sviluppare ed eseguire il deployment di agenti su Agent Runtime.

Prima di iniziare

Nota: per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se non disponi di questa autorizzazione, chiedi all'amministratore di concederti il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin).

Accedi al tuo Google Cloud account. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform and Cloud Storage APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform and Cloud Storage APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Per ottenere le autorizzazioni necessarie per utilizzare Agent Runtime, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

• Utente Agent Platform (roles/aiplatform.user)
• Storage Admin (roles/storage.admin)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Installare e inizializzare l'SDK Agent Platform per Python

1. Esegui il seguente comando per installare l'SDK Agent Platform per Python e altri pacchetti richiesti:

   pip install --upgrade --quiet google-cloud-aiplatform[agent_engines,adk]>=1.112

2. Esegui l'autenticazione come utente

   Shell locale

   Esegui questo comando:

   gcloud auth application-default login

   Colab

   Esegui questo codice:

   from google.colab import auth
   
   auth.authenticate_user(project_id="PROJECT_ID")
   

   Cloud Shell

   Non occorre alcun intervento.

3. Esegui il seguente codice per importare Agent Platform e inizializzare l'SDK:

   Progetto Google Cloud

   import vertexai
   
   client = vertexai.Client(
       project="PROJECT_ID",               # Your project ID.
       location="LOCATION",                # Your cloud region.
   )
   

   Dove:

   • PROJECT_ID è l' Google Cloud ID progetto in cui sviluppi ed esegui il deployment degli agenti

   • LOCATION è una delle regioni supportate.

Sviluppare un agente

1. Sviluppa uno strumento di cambio valuta per l'agente:

   def get_exchange_rate(
       currency_from: str = "USD",
       currency_to: str = "EUR",
       currency_date: str = "latest",
   ):
       """Retrieves the exchange rate between two currencies on a specified date."""
       import requests
   
       response = requests.get(
           f"https://api.frankfurter.app/{currency_date}",
           params={"from": currency_from, "to": currency_to},
       )
       return response.json()
   

2. Crea un'istanza di un agente:

   from google.adk.agents import Agent
   from vertexai import agent_engines
   
   agent = Agent(
       model="gemini-2.0-flash",
       name='currency_exchange_agent',
       tools=[get_exchange_rate],
   )
   
   app = agent_engines.AdkApp(agent=agent)
   

3. Testa l'agente in locale:

   Nota: il test di un agente ADK in locale utilizza sessioni in memoria.

   async for event in app.async_stream_query(
       user_id="USER_ID",
       message="What is the exchange rate from US dollars to SEK today?",
   ):
       print(event)
   

   dove USER_ID è un ID definito dall'utente con un limite di 128 caratteri.

Eseguire il deployment di un agente

Esegui il deployment dell'agente creando una reasoningEngine risorsa in Agent Platform:

Nota: il deployment di un agente ADK su Agent Platform genera automaticamente una risorsa di sessione gestita. Puoi eliminare la risorsa di sessione gestita insieme all'agente nella sezione Pulizia.

remote_agent = client.agent_engines.create(
    agent=app,
    config={
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
        "staging_bucket": "STAGING_BUCKET",
        "identity_type": types.IdentityType.AGENT_IDENTITY,
    }
)

dove STAGING_BUCKET è un bucket Cloud Storage con il prefisso gs://.

Utilizzare un agente

Testa l'agente di cui è stato eseguito il deployment inviando una query:

async for event in remote_agent.async_stream_query(
    user_id="USER_ID",
    message="What is the exchange rate from US dollars to SEK today?",
):
    print(event)

Libera spazio

Per evitare che al tuo Google Cloud account vengano addebitati costi relativi alle risorse utilizzate in questa pagina, segui questi passaggi.

remote_agent.delete(force=True)

Passaggi successivi

Guida

Configurazione di Agent Platform Runtime

Configura l'ambiente per utilizzare Agent Platform Runtime.

Guida

Eseguire il deployment degli agenti

Scopri i cinque modi per eseguire il deployment di un agente su Agent Platform Runtime in base alle tue esigenze di sviluppo.

Guida

Gestire gli agenti di cui è stato eseguito il deployment

Scopri come gestire gli agenti di cui è stato eseguito il deployment nel runtime gestito di Agent Platform.

Guida

Utilizzare un agente

Utilizza un agente con Agent Platform Runtime.

Risorsa

Richiedere assistenza

Trova risorse e assistenza per Google Agent Platform.