Integrazione con Google Drive tramite OAuth2

Questo tutorial introduttivo illustra i passaggi essenziali per iniziare a utilizzare Amazon Bedrock AgentCore Identity per i tuoi agenti AI. Imparerai come configurare il tuo ambiente di sviluppo, installare gli SDK necessari, creare la tua prima identità di agente e consentire al tuo agente di accedere alle risorse esterne in modo sicuro.

Alla fine di questo tutorial, avrai un agente funzionante in grado di recuperare i token di accesso da Google con AgentCore Identity OAuth2 Credential Provider e leggere i file da Google Drive utilizzando i token di accesso. Per informazioni dettagliate sui flussi OAuth2, consulta Gestire i provider di credenziali con Identity. AgentCore

Prerequisiti

Prima di iniziare, devi:

Installazione dell'SDK

Per iniziare, installa il bedrock-agentcore pacchetto:

pip install bedrock-agentcore

Ottieni Google Client ID e Client Secret

Per consentire al tuo agente di accedere a Google Drive, devi ottenere un ID cliente Google e un client secret per il tuo agente. Vai alla Google Developer Console e segui questi passaggi:

Passaggio 1: configurare un provider di credenziali OAuth 2.0

Crea un nuovo provider di credenziali OAuth 2.0 con l'ID client di Google e il segreto del client ottenuti in precedenza utilizzando il seguente comando AWS CLI:

OAUTH2_CREDENTIAL_PROVIDER_RESPONSE=$(aws bedrock-agentcore-control create-oauth2-credential-provider \
  --region us-east-1 \
  --name "google-provider" \
  --credential-provider-vendor "GoogleOauth2" \
  --oauth2-provider-config-input '{
      "googleOauth2ProviderConfig": {
        "clientId": "<your-google-client-id>",
        "clientSecret": "<your-google-client-secret>"
      }
    }' \
--output json)

OAUTH2_CALLBACK_URL=$(echo $OAUTH2_CREDENTIAL_PROVIDER_RESPONSE | jq -r '.callbackUrl')

echo "OAuth2 Callback URL: $OAUTH2_CALLBACK_URL"

Fase 2: Importazione dei moduli Identity e Auth

Aggiungi questa dichiarazione di importazione al tuo file Python:

from bedrock_agentcore.services.identity import IdentityClient
from bedrock_agentcore.identity.auth import requires_access_token, requires_api_key

Passaggio 3: ottenere un token di accesso OAuth 2.0

Dopo aver creato il Google Credential Provider nel passaggio precedente, aggiungi il @requires_access_token decoratore al codice del tuo agente che richiede un token di accesso Google. Copia l'URL di autorizzazione dall'output della console, quindi incollalo nel browser e completa il flusso di consenso con Google Drive.

Il seguente esempio di codice è destinato a essere integrato nel codice dell'agente per richiamare un flusso di lavoro di autorizzazione. Non si tratta di codice autonomo che può essere copiato ed eseguito indipendentemente.

import asyncio

# Injects Google Access Token
@requires_access_token(
    # Uses the same credential provider name created above
    provider_name="google-provider",
    # Requires Google OAuth2 scope to access Google Drive
    scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"],
    # Sets to OAuth 2.0 Authorization Code flow
    auth_flow="USER_FEDERATION",
    # Prints authorization URL to console
    on_auth_url=lambda x: print("\nPlease copy and paste this URL in your browser:\n" + x),
    # If false, caches obtained access token
    force_authentication=False,
    # The callback URL to redirect to after the OAuth 2.0 token retrieval is complete
    callback_url='oauth2_callback_url_for_session_binding',
)
async def write_to_google_drive(*, access_token: str):
    # Prints the access token obtained from Google
    print(access_token)

asyncio.run(write_to_google_drive(access_token=""))

Dietro le quinte, il @requires_access_token decoratore esegue la seguente sequenza:

Passaggio 4: utilizzare il token di accesso OAuth2 per richiamare una risorsa esterna

Una volta che l'agente ottiene un token di accesso Google con i passaggi precedenti, può utilizzare il token di accesso per accedere a Google Drive. Ecco un esempio completo che elenca i nomi e gli ID dei primi 10 file a cui l'utente ha accesso.

Innanzitutto, installa la libreria client di Google per Python:

pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

Quindi, copia il seguente codice:

import asyncio
from bedrock_agentcore.identity.auth import requires_access_token, requires_api_key
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

SCOPES = ["https://www.googleapis.com/auth/drive.metadata.readonly"]

def main(access_token):
    """Shows basic usage of the Drive v3 API.

    Prints the names and ids of the first 10 files the user has access to.
    """
    creds = Credentials(token=access_token, scopes=SCOPES)

    try:
        service = build("drive", "v3", credentials=creds)

        # Call the Drive v3 API
        results = (
            service.files()
            .list(pageSize=10, fields="nextPageToken, files(id, name)")
            .execute()
        )
        items = results.get("files", [])

        if not items:
            print("No files found.")
            return

        print("Files:")
        for item in items:
            print(f"{item['name']} ({item['id']})")

    except HttpError as error:
        # TODO(developer) - Handle errors from drive API.
        print(f"An error occurred: {error}")

if __name__ == "__main__":
    # This annotation helps agent developer to obtain access tokens from external applications
    @requires_access_token(
        provider_name="google-provider",
        # Google OAuth2 scopes
        scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"],
        # 3LO flow
        auth_flow="USER_FEDERATION",
        # prints authorization URL to console
        on_auth_url=lambda x: print("Copy and paste this authorization url to your browser", x),
        force_authentication=True,
        callback_url='oauth2_callback_url_for_session_binding',
    )
    async def read_from_google_drive(*, access_token: str):
        print(access_token)  # You can see the access_token
        # Make API calls...
        main(access_token)

    asyncio.run(read_from_google_drive(access_token=""))

Fasi successive

L'esempio in questa sezione si concentra su modelli di implementazione pratici che è possibile adattare a casi d'uso specifici. È possibile incorporare il codice come parte di un agente o di uno strumento Model Context Protocol (MCP). Se desideri ospitare il tuo codice Agent o lo strumento MCP con AgentCore Runtime, segui Host agent o tools with Amazon Bedrock AgentCore Runtime per copiare il codice precedente in Runtime. AgentCore