Mengautentikasi menggunakan kunci API dengan pengelola autentikasi

Agar agen Anda dapat melakukan autentikasi ke alat eksternal seperti Google Maps atau Weather API, konfigurasikan autentikasi keluar menggunakan penyedia autentikasi kunci API di pengelola autentikasi Agent Identity.

Penyedia autentikasi kunci API mengelola kunci kriptografis Anda untuk Anda. Kemampuan ini menghilangkan kebutuhan untuk melakukan hardcode kunci dalam kode agen Anda atau mengelolanya secara manual.

Alur kerja kunci API

Penyedia autentikasi kunci API menggunakan identitas agen dan tidak memerlukan izin pengguna. Google melakukan tindakan untuk membantu mengamankan kunci API selama penyimpanan. Saat Anda menggunakan Agent Development Kit (ADK), ADK akan otomatis mengambil dan memasukkan kunci API ke dalam header pemanggilan alat.

Sebelum memulai

  1. Pastikan Anda telah memilih metode autentikasi yang benar.

  2. Aktifkan Agent Identity API, jika belum diaktifkan.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

    Mengaktifkan API

  3. Membuat dan men-deploy agen.

  4. Dapatkan kunci API dari layanan pihak ketiga yang ingin Anda hubungkan.

  5. Pastikan Anda memiliki peran yang diperlukan untuk menyelesaikan tugas ini.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk membuat dan menggunakan penyedia autentikasi kunci API, minta administrator untuk memberi Anda peran IAM berikut pada project:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk membuat dan menggunakan penyedia autentikasi kunci API. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk membuat dan menggunakan penyedia autentikasi kunci API:

  • Untuk membuat penyedia autentikasi: agentidentity.authProviders.create
  • Untuk menggunakan penyedia autentikasi:
    • agentidentity.authProviders.retrieveCredentials
    • aiplatform.endpoints.predict
    • aiplatform.sessions.create

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Mendapatkan kunci API dari layanan pihak ketiga

Sebelum membuat penyedia autentikasi, dapatkan kunci API dari layanan pihak ketiga yang ingin Anda hubungkan dengan agen.

Jika Anda terhubung ke layanan pihak ketiga di luar Google Cloud, dapatkan kunci API dari portal developer layanan tersebut dan lewati langkah-langkah di bagian ini.

Jika Anda terhubung ke layanan Google Cloud (seperti Cloud Translation atau Google Maps), Anda dapat membuat dan mengonfigurasi kunci API dengan melakukan langkah-langkah berikut:

  1. Di konsol Google Cloud , aktifkan layanan API yang diperlukan untuk project Anda:

    1. Di konsol Google Cloud , buka halaman APIs & Services > Library.

      Buka APIs & Services > Library

    2. Telusuri dan aktifkan API yang digunakan agen Anda, seperti Cloud Translation API atau Google Maps Weather API.
    3. Salin string kunci API yang Anda buat.

  2. Konfigurasi kunci API Anda:

    1. Di konsol Google Cloud , buka halaman APIs & Services > Credentials.

      Buka API & Layanan > Kredensial

    2. Klik Create credentials > kunci API.
    3. Pada dialog Create kunci API, lakukan hal berikut:
      1. Masukkan nama unik untuk kunci API Anda.
      2. Untuk membatasi kunci ke API tertentu yang Anda aktifkan, pilih API tersebut dari daftar Select API restrictions.
      3. Opsional: Di bagian Restrict your key to reduce security risks, pilih jenis aplikasi untuk membatasi akses.
      4. Klik Create.

  3. Validasi kunci API Anda dengan mengirimkan permintaan pengujian ke endpoint layanan.

    • Untuk memverifikasi kunci Cloud Translation API, jalankan perintah berikut:

      curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-goog-api-key: YOUR_API_KEY" \
  -d '{"q": "Hello world", "target": "es"}' \
  "https://translation.googleapis.com/language/translate/v2"

      Ganti YOUR_API_KEY dengan kunci API yang Anda buat.

    • Untuk memverifikasi kunci Google Maps Weather API, jalankan perintah berikut:

      curl -X GET \
  "https://weather.googleapis.com/v1/currentConditions:lookup?key=YOUR_API_KEY&location.latitude=37.4220&location.longitude=-122.0841"

      Ganti YOUR_API_KEY dengan kunci API yang Anda buat.

    Jika kunci API valid dan dikonfigurasi dengan benar, layanan akan menampilkan data yang diminta.

Membuat penyedia autentikasi kunci API

Buat penyedia autentikasi untuk menentukan konfigurasi dan kredensial bagi aplikasi pihak ketiga.

Untuk membuat penyedia autentikasi kunci API, gunakan konsol Google Cloud , Google Cloud CLI, atau REST API.

Konsol

  1. Di konsol Google Cloud , buka halaman Agent Registry.

    Buka Agent Registry

  2. Klik nama agen yang ingin Anda buatkan penyedia autentikasinya.
  3. Klik Identity.
  4. Di bagian Auth Providers, klik Add auth provider.

  5. Di panel Add auth provider, masukkan nama dan deskripsi.

    Nama hanya boleh berisi huruf kecil, angka, atau tanda hubung, tidak boleh diakhiri dengan tanda hubung, dan harus diawali dengan huruf kecil.

  6. Dari daftar OAuth Type, pilih kunci API .
  7. Klik Create and continue.
  8. Untuk memberikan izin identitas agen Anda agar dapat menggunakan penyedia autentikasi, klik Grant access.

    Proses ini otomatis menetapkan peran Agent Identity User (roles/agentidentity.user) ke identitas agen di resource penyedia autentikasi.

  9. Di bagian Auth provider credentials, masukkan kunci API.
  10. Klik Add provider config.

Penyedia autentikasi yang baru dibuat akan muncul dalam daftar Auth Providers.

gcloud CLI

  1. Buat penyedia autentikasi:

    gcloud agent-identity auth-providers create AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --api-key="API_KEY"
  2. Pastikan penyedia autentikasi Anda muncul dalam daftar dan statusnya adalah ENABLED: 
    gcloud agent-identity auth-providers list \
   --project="PROJECT_ID" \
   --location="LOCATION"

  3. Berikan izin akses untuk mengizinkan agen dan lingkungan pengembangan lokal Anda mengambil kredensial dari penyedia autentikasi. Agar agen yang di-deploy dan akun pengguna pribadi Anda dapat mengakses penyedia autentikasi, berikan peran Agent Identity User (roles/agentidentity.user) pada resource penyedia autentikasi:

    1. Berikan akses ke ID SPIFFE agen yang di-deploy (Identitas Agen):

      gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/agentidentity.user" \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

    2. Berikan akses ke akun pengguna pribadi Anda untuk pengembangan dan pengujian lokal (adk web):

      gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/agentidentity.user" \
    --member="user:USER_EMAIL"

Ganti kode berikut:

  • PROJECT_ID: Project ID Google Cloud Anda.
  • LOCATION: Lokasi tempat penyedia autentikasi dan agen Anda di-deploy (misalnya, us-west1).
  • AUTH_PROVIDER_NAME: Nama untuk penyedia autentikasi Anda (misalnya, maps-api-key-authprovider).
  • API_KEY: Kunci API yang Anda buat dari layanan pihak ketiga.
  • ORGANIZATION_ID: ID organisasi Google Cloud Anda.
  • PROJECT_NUMBER: Nomor project Google Cloud Anda.
  • ENGINE_ID: ID agen mesin penalaran yang di-deploy.
  • USER_EMAIL: Alamat email akun pengguna pribadi Anda.

REST

  1. Buat penyedia autentikasi:

    Metode authProviders.create Agent Identity API membuat penyedia autentikasi kunci API di project dan lokasi.

    Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

    • PROJECT_ID: Project ID Google Cloud Anda. Project ID adalah string alfanumerik, seperti my-project.
    • LOCATION: Lokasi tempat penyedia autentikasi dan agen Anda di-deploy (misalnya, us-west1).
    • AUTH_PROVIDER_NAME: Nama untuk penyedia autentikasi Anda (misalnya, maps-api-key-authprovider). Nama hanya boleh berisi huruf kecil, angka, atau tanda hubung, tidak boleh diakhiri dengan tanda hubung, dan harus diawali dengan huruf kecil.
    • API_KEY: Kunci API yang Anda buat dari layanan pihak ketiga.

    Metode HTTP dan URL: 

    POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME

    Meminta isi JSON: 

    {
  "authProviderTypeParams": {
    "apiKey": {
      "apiKey": "API_KEY"
    }
  }
}

    Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

    Anda akan melihat respons JSON seperti berikut:

    {
  "name": "projects/my-project/locations/us-west1/authProviders/maps-api-key-authprovider",
  "createTime": "2026-04-03T21:15:41.367155Z",
  "updateTime": "2026-04-03T21:15:41.367155Z",
  "authProviderTypeParams": {
    "apiKey": {}
  },
  "state": "ENABLED"
}

  2. Agar agen yang di-deploy dan akun pengguna pribadi Anda dapat mengambil kredensial dari penyedia autentikasi, berikan peran Agent Identity User (roles/agentidentity.user) pada resource penyedia autentikasi:

    Metode authProviders.setIamPolicy Agent Identity API menetapkan kebijakan izin pada resource penyedia autentikasi.

    Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

    • PROJECT_ID: Project ID Google Cloud Anda. Project ID adalah string alfanumerik, seperti my-project.
    • LOCATION: Lokasi tempat penyedia autentikasi dan agen Anda di-deploy (misalnya, us-west1).
    • AUTH_PROVIDER_NAME: Nama untuk penyedia autentikasi Anda.
    • ORGANIZATION_ID: ID organisasi Google Cloud Anda.
    • PROJECT_NUMBER: Nomor project numerik Google Cloud dari project tempat agen Anda di-deploy (misalnya, 987654321098).
    • ENGINE_ID: ID agen mesin penalaran yang di-deploy.
    • USER_EMAIL: Alamat email akun pengguna pribadi Anda.

    Metode HTTP dan URL: 

    POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy

    Meminta isi JSON: 

    {
  "policy": {
    "bindings": [
      {
        "role": "roles/agentidentity.user",
        "members": [
          "principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID",
          "user:USER_EMAIL"
        ]
      }
    ]
  }
}

    Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

    Anda akan melihat respons JSON seperti berikut:

    {
  "version": 1,
  "etag": "BwYKmjvelug=",
  "bindings": [
    {
      "role": "roles/agentidentity.user",
      "members": [
        "principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/987654321098/locations/us-west1/reasoningEngines/112233445566778899",
        "user:alex@example.com"
      ]
    }
  ]
}

Melakukan autentikasi dalam kode agen Anda

Untuk mengautentikasi agen, Anda dapat menggunakan ADK.

ADK

Referensi penyedia autentikasi dalam kode agen Anda menggunakan toolset MCP di ADK.

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.auth.auth_tool import AuthConfig

# Register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create Google Cloud auth provider scheme
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
)

# Configure an MCP tool with the authentication scheme.
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"),
    auth_scheme=auth_scheme,
)

# Initialize the agent with the authenticated tools.
agent = Agent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Contoh: Menghubungkan ke MCP Google Maps

Contoh berikut menunjukkan konfigurasi agent.py yang menghubungkan agen ke server MCP Google Maps:

import os
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.models import Gemini
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset

os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
os.environ["GOOGLE_API_USE_CLIENT_CERTIFICATE"] = "false"

# Register Google Cloud auth provider for Agent Identity Credentials service
CredentialManager.register_auth_provider(GcpAuthProvider())

maps_auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
)

maps_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://mapstools.googleapis.com/mcp"),
    auth_scheme=maps_auth_scheme,
    errlog=None,
)

root_agent = Agent(
    name="root_agent",
    model=Gemini(model="gemini-2.5-flash"),
    instruction=(
        "You are a helpful AI assistant designed to provide accurate and useful "
        "information. You can also use your Google Maps tools to look up "
        "locations and directions."
    ),
    tools=[maps_tools],
)

app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

ADK

Referensikan penyedia autentikasi dalam kode agen Anda menggunakan alat fungsi yang diautentikasi di ADK.

import httpx
from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_identity import GcpAuthProviderScheme
from google.adk.apps import App
from google.adk.auth.auth_credential import AuthCredential
from google.adk.auth.auth_tool import AuthConfig
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool
from vertexai import agent_engines

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create Auth Config
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
    )
)

# Use the Auth Config in Authenticated Function Tool
spotify_search_track_tool = AuthenticatedFunctionTool(
    func=spotify_search_track, auth_config=spotify_auth_config
)

# Sample function tool
async def spotify_search_track(credential: AuthCredential, query: str) -> str | list:
    token = None
    if credential.http and credential.http.credentials:
        token = credential.http.credentials.token

    if not token:
        return "Error: No authentication token available."

    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.spotify.com/v1/search",
            headers={"Authorization": f"Bearer {token}"},
            params={"q": query, "type": "track", "limit": 1},
        )
        # Add your own logic here

agent = Agent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="APP_NAME",
    root_agent=agent,
)

vertex_app = agent_engines.AdkApp(app_name=app)

Contoh: Menghubungkan ke Google Maps Weather API

Contoh berikut menunjukkan konfigurasi agent.py yang menghubungkan agen ke Google Maps Weather API menggunakan alat fungsi yang diautentikasi:

import os
import httpx
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.auth.auth_credential import AuthCredential
from google.adk.auth.auth_tool import AuthConfig
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.models import Gemini
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool

os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
os.environ["GOOGLE_API_USE_CLIENT_CERTIFICATE"] = "false"

# Register Google Cloud auth provider for Agent Identity Credentials service
CredentialManager.register_auth_provider(GcpAuthProvider())

weather_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
    )
)

async def get_weather(credential: AuthCredential, latitude: float, longitude: float) -> str | dict:
    """Gets current weather conditions for a location."""
    api_key = None
    if http := credential.http:
        if http.additional_headers and "X-GOOG-API-KEY" in http.additional_headers:
            api_key = http.additional_headers["X-GOOG-API-KEY"]
        elif http.credentials and http.credentials.token:
            api_key = http.credentials.token

    if not api_key:
        return "Error: No API key available from the auth provider."

    params = {"location.latitude": latitude, "location.longitude": longitude, "key": api_key}
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://weather.googleapis.com/v1/currentConditions:lookup",
            params=params,
        )
        if response.status_code != 200:
            return f"Error from Weather API: {response.status_code} - {response.text}"
        return response.json()

get_weather_tool = AuthenticatedFunctionTool(
    func=get_weather, auth_config=weather_auth_config
)

root_agent = Agent(
    name="root_agent",
    model=Gemini(model="gemini-2.5-flash"),
    instruction=(
        "You are a helpful AI assistant. You will use your weather tool to "
        "look up current conditions."
    ),
    tools=[get_weather_tool],
)

app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

ADK

Referensi penyedia autentikasi dalam kode agen Anda menggunakan set alat MCP Agent Registry di ADK.

Anda tidak membuat skema autentikasi untuk alur ini. Binding keluar server MCP sudah mencatat penyedia autentikasi yang akan digunakan.

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_registry import AgentRegistry

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Set Agent Registry. LOCATION must be the same region as the auth provider.
registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION")

# The auth provider is resolved from the MCP server's outbound binding.
toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/locations/"
        "LOCATION/mcpServers/"
        "agentregistry-00000000-0000-0000-0000-000000000000"
    ),
)

agent = Agent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Men-deploy agen

Saat Anda men-deploy agen ke Google Cloud, pastikan Identitas Agen diaktifkan.

Agent CLI

Jika Anda menggunakan Agent Development Kit (ADK) dan Agent CLI, lakukan hal berikut untuk men-deploy agen dengan Identitas Agen diaktifkan:

  1. Di folder aplikasi agen Anda, buat file konfigurasi bernama .agent_engine_config.json untuk mengaktifkan Identitas Agen:

    echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

  2. Men-deploy agen Anda ke Agent Runtime di Gemini Enterprise Agent Platform :

    uv run adk deploy agent_engine AGENT_NAME \
    --project="PROJECT_ID" \
    --region="LOCATION"

    Ganti kode berikut:

    • AGENT_NAME: Nama folder aplikasi agen Anda (misalnya, maps_agent).
    • PROJECT_ID: Project ID Google CloudAnda.
    • LOCATION: Wilayah yang didukung tempat Anda ingin men-deploy agen (misalnya, us-west1).

Python SDK

Jika Anda men-deploy secara terprogram menggunakan Vertex AI Python SDK, gunakan flag identity_type=AGENT_IDENTITY:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Register the auth provider in set_up() so that it runs in the deployed
# container. Use the proper wrapper class for your Agent Framework (for example, AdkApp).
class AuthenticatedAdkApp(AdkApp):
    def set_up(self):
        CredentialManager.register_auth_provider(GcpAuthProvider())
        super().set_up()

app = AuthenticatedAdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": [
            "google-cloud-aiplatform[agent_engines,adk]",
            "google-adk[agent-identity,mcp]>=2.7.1",
        ],
    },
)

Ganti kode berikut:

  • PROJECT_ID: Project ID Google Cloud Anda.
  • LOCATION: Wilayah yang didukung tempat Anda ingin men-deploy agen (misalnya, us-west1).

Langkah berikutnya