Integre com o Google Drive usando o OAuth2

Este tutorial de introdução mostra as etapas essenciais para começar a usar o Amazon Bedrock AgentCore Identity para seus agentes de IA. Você aprenderá como configurar seu ambiente de desenvolvimento, instalar os SDKs necessários, criar sua primeira identidade de agente e permitir que seu agente acesse recursos externos com segurança.

Ao final deste tutorial, você terá um agente ativo que pode recuperar tokens de acesso do Google com o AgentCore Identity OAuth2 Credential Provider e ler arquivos do Google Drive usando tokens de acesso. Para obter informações detalhadas sobre fluxos do OAuth2, consulte Gerenciar provedores de credenciais com identidade. AgentCore

Pré-requisitos

Antes de começar, você precisa:

Instalar o SDK

Para começar, instale o bedrock-agentcore pacote:

pip install bedrock-agentcore

Obtenha o ID do cliente e o segredo do cliente do Google

Para permitir que seu agente acesse o Google Drive, você precisa obter um ID de cliente do Google e um segredo de cliente para seu agente. Acesse o Google Developer Console e siga estas etapas:

Etapa 1: configurar um provedor de credenciais do OAuth 2.0

Crie um novo provedor de credenciais do OAuth 2.0 com o ID e o segredo do cliente do Google obtidos anteriormente usando o seguinte comando da CLI AWS :

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"

Etapa 2: Importar módulos de identidade e autenticação

Adicione esta instrução de importação ao seu arquivo Python:

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

Etapa 3: Obter um token de acesso OAuth 2.0

Depois de criar o provedor de credenciais do Google na etapa anterior, adicione o @requires_access_token decorador ao código do seu agente que exige um token de acesso do Google. Copie o URL de autorização da saída do console, cole-o no navegador e conclua o fluxo de consentimento com o Google Drive.

O exemplo de código a seguir deve ser integrado ao código do seu agente para invocar um fluxo de trabalho de autorização. Esse não é um código autônomo que pode ser copiado e executado de forma independente.

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=""))

Nos bastidores, o @requires_access_token decorador percorre a seguinte sequência:

Etapa 4: Usar o token de acesso OAuth2 para invocar recursos externos

Depois que o agente obtém um token de acesso do Google com as etapas acima, ele pode usar o token de acesso para acessar o Google Drive. Aqui está um exemplo completo que lista os nomes e IDs dos primeiros 10 arquivos aos quais o usuário tem acesso.

Primeiro, instale a biblioteca cliente do Google para Python:

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

Em seguida, copie o código a seguir:

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=""))

E depois?

O exemplo nesta seção se concentra em padrões práticos de implementação que você pode adaptar para seus casos de uso específicos. Você pode incorporar o código como parte de um agente ou de uma ferramenta do Model Context Protocol (MCP). Se você quiser hospedar seu código de agente ou ferramenta MCP com AgentCore Runtime, siga Host agent ou tools with Amazon Bedrock AgentCore Runtime para copiar o código acima para AgentCore Runtime.