도구 및 리소스에 인증

Agent Registry를 사용하면 조정자 에이전트가 검색된 원격 에이전트, 모델 컨텍스트 프로토콜 (MCP) 도구 모음,Google Cloud 서비스에 안전하게 인증할 수 있습니다. 에이전트 아이덴티티 및 에이전트 아이덴티티 인증 관리자를 사용하면 에이전트 레지스트리를 통해 검색된 기능을 호출할 때 사용자 인증 정보, 바인딩, 커스텀 HTTP 헤더를 구성할 수 있습니다.

시작하기 전에

도구 및 리소스에 인증하기 전에 다음을 완료하세요.

1. Agent Registry 설정
2. Agent Registry가 사용 설정된 거버넌스 프로젝트의 프로젝트 ID를 가져옵니다.

3. A2A, 에이전트 ID, MCP 종속 항목을 사용하여 에이전트 개발 키트 (ADK)를 최신 버전으로 설치하거나 업그레이드합니다.

   pip

   pip install --upgrade "google-adk[a2a,agent-identity,mcp]"
   

   uv

   uv add "google-adk[a2a,agent-identity,mcp]"
   

   google-adk>=1.29.0 이상으로 업그레이드해야 합니다.

4. 인증에 애플리케이션 기본 사용자 인증 정보 (ADC)를 사용하려면 다음을 구성합니다.

   gcloud auth application-default login
   

   ADC 사용자 인증 정보에는 에이전트 또는 도구가 상호작용하는 기본 Google Cloud 서비스에 필요한 Identity and Access Management (IAM) 권한이 있어야 합니다.

5. 다음 환경 변수를 설정합니다.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=LOCATION
   export API_KEY=EXTERNAL_API_KEY
   

   다음을 바꿉니다.

   • PROJECT_ID: 거버넌스 프로젝트의 프로젝트 ID입니다.
   • LOCATION: 레지스트리 리전 또는 위치입니다(예: us-central1).
   • EXTERNAL_API_KEY: 커스텀 헤더를 사용하는 경우 외부 API 키입니다.

인증 모델 알아보기

사용자 인증 정보를 관리하기 위해 에이전트 레지스트리는 기본 제공되는Google Cloud 인증을 위해 에이전트 ID를 사용하고 인증 제공업체 및 바인딩을 위해 인증 관리자를 사용합니다.

에이전트는 자체 ID를 사용하거나 인증 관리자를 사용하여 API 키 또는 OAuth 2.0을 통해 도구에 액세스할 수 있습니다. 에이전트 ID 또는 서비스 계정을 사용하는지 여부에 관계없이 에이전트의 자체 ID는 애플리케이션 기본 사용자 인증 정보 (ADC)를 통해 제공됩니다.

인증 관리자를 사용하지 않고 인증해야 하는 경우 ADK 요청에 커스텀 HTTP 헤더를 직접 제공합니다.

사용 사례에 가장 적합한 접근 방식을 결정하려면 인증 모델을 참조하세요.

Google Cloud 도구에 에이전트 ID 사용

Gemini Enterprise Agent Platform의 Agent Runtime 또는 Cloud Storage와 같은 Google Cloud 서비스의 경우 에이전트가 자체 ID를 사용하여 도구에 액세스합니다. 이 액세스는 에이전트 ID 또는 서비스 계정 사용 여부에 관계없이 애플리케이션 기본 사용자 인증 정보 (ADC)를 통해 관리됩니다.

에이전트와 연결된 ID에는 기본 Google Cloud 서비스에 필요한 IAM 권한이 있어야 합니다. 예를 들어 MCP 도구가 Compute Engine VM 인스턴스를 관리하는 경우 에이전트 ID에는 에이전트 레지스트리 API 뷰어 역할 외에도 Compute 인스턴스 관리자 (v1) 이상과 같은 역할이 있어야 합니다.

원격 A2A 에이전트 인증

오케스트레이터 에이전트가 자체 ID를 사용하여 원격 Google Agent2Agent (A2A) 에이전트에 연결하는 경우 Google 인증 헤더로 구성된 httpx.AsyncClient를 get_remote_a2a_agent() 메서드에 명시적으로 포함해야 합니다.

기본 HTTP 클라이언트 제한 시간 한도를 초과하지 않도록 커스텀 제한 시간을 정의합니다.

다음 예시에서는 ADC 및 커스텀 제한 시간으로 httpx.AsyncClient를 구성하는 방법을 보여줍니다.

import os
import httpx
import google.auth
from google.auth.transport.requests import Request
from google.adk.integrations.agent_registry import AgentRegistry

class GoogleAuth(httpx.Auth):
    def __init__(self):
        self.creds, _ = google.auth.default()
    def auth_flow(self, request):
        if not self.creds.valid:
            self.creds.refresh(Request())
        request.headers["Authorization"] = f"Bearer {self.creds.token}"
        yield request

# Initialize the registry client
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")

if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable not set.")

registry = AgentRegistry(
    project_id=project_id,
    location=location,
)

# Configure the HTTP client with GoogleAuth and a 60-second timeout
httpx_client = httpx.AsyncClient(auth=GoogleAuth(), timeout=httpx.Timeout(60.0))

# Connect to a remote A2A agent using its resource name in short or full format
# Short formats automatically imply the client's configured project and location
# Short format: "agents/AGENT_ID"
# Full format: f"projects/{project_id}/locations/{location}/agents/AGENT_ID"
agent_name = "agents/AGENT_ID"
my_remote_agent = registry.get_remote_a2a_agent(
    agent_name=agent_name,
    httpx_client=httpx_client,
)

AGENT_ID를 등록된 에이전트의 ID로 바꿉니다.

MCP 도구 인증

오케스트레이터 에이전트가 자체 ID를 사용하여 MCP 도구 모음에 액세스하는 경우 ADC 및 get_mcp_toolset() 메서드를 사용하여 레지스트리 클라이언트를 초기화할 수 있습니다.

import os
from google.adk.integrations.agent_registry import AgentRegistry

# Initialize the registry client
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")

if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable not set.")

registry = AgentRegistry(
    project_id=project_id,
    location=location,
)

# Retrieve an MCP toolset using its resource name in short or full format
# Short formats automatically imply the client's configured project and location
# Short format: "mcpServers/SERVER_ID"
# Full format: f"projects/{project_id}/locations/{location}/mcpServers/SERVER_ID"
mcp_server_name = "mcpServers/SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)

SERVER_ID를 등록된 MCP 서버의 ID로 바꿉니다.

커스텀 도구 및 위임된 액세스에 인증 관리자 사용

에이전트가 외부 API, 커스텀 도구 또는 외부 MCP 서버에 연결해야 하는 경우 인증 관리자를 사용하여 애플리케이션에 사용자 인증 정보를 하드코딩하지 않고도 사용자 인증 정보를 관리할 수 있습니다.

사용 사례에 따라 다음 시나리오에 대해 인증 관리자를 구성할 수 있습니다.

• 커스텀 도구 액세스: 에이전트가 자체 ID와 권한을 사용하여 도구에 액세스해야 하는 경우 API 키 또는 2-legged OAuth (2LO)를 사용하여 에이전트를 인증합니다.
• 사용자를 대신하여 도구에 액세스: 3-legged OAuth (3LO)를 사용하여 개별 사용자로 작동하는 에이전트를 인증합니다. 이 모델은 에이전트가 상호작용하는 사용자를 대신하여 도구에 액세스해야 하고 사용자 동의와 위임된 권한이 필요한 경우에 권장됩니다.

이러한 모델을 사용하려면 인증 제공업체를 만들어야 합니다. 그런 다음 에이전트 레지스트리에서 바인딩을 만들어 인증 제공업체를 레지스트리 리소스에 연결합니다.

인증 제공업체를 구성한 후 ADK는 조정자의 인증 흐름을 관리합니다. 예를 보려면 ADK 코드에서 바인딩 해결을 참고하세요.

맞춤 도구 액세스

에이전트가 자체 사용자 인증 정보를 사용하여 외부 또는 커스텀 도구에 연결하도록 하려면 API 키 또는 2-legged OAuth (2LO)를 처리하도록 인증 관리자를 구성하면 됩니다.

1. 인증 제공업체 만들기: 인증 관리자에서 인증 제공업체를 만들어 API 키 또는 OAuth 사용자 인증 정보를 저장합니다. 자세한 내용은 인증 관리자를 사용하여 2-legged OAuth로 인증 또는 인증 관리자를 사용하여 API 키로 인증을 참조하세요.

2. 인증 제공업체 바인딩: 조정자 에이전트가 대상에 적합한 인증 제공업체를 감지하도록 하려면 에이전트 레지스트리에서 에이전트, 대상 리소스, 인증 제공업체 간에 바인딩을 만들어야 합니다. 바인딩을 사용하면 코드에서 인증 제공업체를 수동으로 정의할 필요가 없습니다.

   gcloud

   gcloud agent-registry bindings create 명령어를 실행하여 에이전트를 대상 리소스 및 인증 제공업체에 명시적으로 연결하는 바인딩을 만듭니다. --auth-provider-binding 리소스 이름을 지정할 때는 거버넌스 프로젝트의 프로젝트 ID를 사용해야 합니다.

   gcloud agent-registry bindings create BINDING_NAME \
       --project=PROJECT_ID \
       --location=LOCATION \
       --display-name="DISPLAY_NAME" \
       --source-identifier="SOURCE_ID" \
       --target-identifier="TARGET_ID" \
       --auth-provider-binding="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_ID"
   

   Terraform

   google_agent_registry_binding 리소스를 구성하여 에이전트와 대상 리소스를 인증 제공업체에 연결합니다.

   resource "google_agent_registry_binding" "custom_tool_binding" {
     project      = "PROJECT_ID"
     location     = "LOCATION"
     binding_id   = "BINDING_NAME"
     display_name = "DISPLAY_NAME"
   
     source {
       identifier = "SOURCE_ID"
     }
   
     target {
       identifier = "TARGET_ID"
     }
   
     auth_provider_binding {
       auth_provider = "projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_ID"
     }
   }
   

   다음을 바꿉니다.

   • BINDING_NAME: 바인딩의 고유 ID입니다.
   • PROJECT_ID: 거버넌스 프로젝트의 프로젝트 ID입니다.
   • LOCATION: 레지스트리 리전 또는 위치입니다(예: us-central1 또는 global).
   • DISPLAY_NAME: 인간이 읽을 수 있는 바인딩 표시 이름입니다.
   • SOURCE_ID: URN 형식의 소스 에이전트의 에이전트 식별자입니다.
   • TARGET_ID: URN 형식의 대상 MCP 서버 또는 엔드포인트의 레지스트리 식별자입니다.
   • AUTH_PROVIDER_ID: 인증 제공업체의 ID입니다.

   이러한 연결을 관리하는 방법에 대한 자세한 내용은 바인딩 관리를 참조하세요.

사용자를 대신하여 도구에 액세스

에이전트가 개별 사용자를 대신하여 원격 MCP 서버 또는 도구에 인증하도록 하려면 인증 관리자를 통해 3-legged OAuth (3LO)를 사용합니다.

인증 관리자는 OAuth 토큰, 사용자 동의, 리디렉션을 처리하는 완전한 Google 관리형 서비스를 제공합니다. 최종 사용자가 에이전트와 상호작용하고 위임된 권한이 필요한 도구를 트리거하면 플랫폼은 자동으로 사용자에게 동의를 요청하고 사용자 인증 정보를 저장한 후 워크플로를 재개합니다.

1. 인증 제공업체 만들기: 인증 관리자에서 인증 제공업체를 만들고 OAuth 리디렉션 URI를 구성합니다. 자세한 내용은 인증 관리자와 함께 3-legged OAuth를 사용하여 인증을 참조하세요.
2. 클라이언트 애플리케이션 업데이트: adk_request_credential 함수 호출을 처리하고 사용자 동의를 관리하도록 애플리케이션 클라이언트를 업데이트합니다. 자세한 내용은 클라이언트 측 애플리케이션 업데이트를 참조하세요.

3. 인증 제공업체 바인딩: 조정자 에이전트가 대상에 적합한 인증 제공업체를 감지하도록 하려면 에이전트 레지스트리에서 에이전트, 대상 리소스, 인증 제공업체 간에 바인딩을 만들어야 합니다. 바인딩을 사용하면 코드에서 인증 제공업체를 수동으로 정의할 필요가 없습니다.

   gcloud

   gcloud agent-registry bindings create 명령어를 실행하여 에이전트를 대상 리소스 및 인증 제공업체에 명시적으로 연결하는 바인딩을 만듭니다. --auth-provider-binding 리소스 이름을 지정할 때는 거버넌스 프로젝트의 프로젝트 ID를 사용해야 합니다.

   gcloud agent-registry bindings create BINDING_NAME \
       --project=PROJECT_ID \
       --location=LOCATION \
       --display-name="DISPLAY_NAME" \
       --source-identifier="SOURCE_ID" \
       --target-identifier="TARGET_ID" \
       --auth-provider-binding="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_ID" \
       --auth-provider-binding-scopes=SCOPES \
       --auth-provider-binding-continue-uri="https://REDIRECT_URI"
   

   Terraform

   OAuth 2.0 범위 및 계속 URI를 사용하여 google_agent_registry_binding 리소스를 구성합니다.

   resource "google_agent_registry_binding" "user_delegated_binding" {
     project      = "PROJECT_ID"
     location     = "LOCATION"
     binding_id   = "BINDING_NAME"
     display_name = "DISPLAY_NAME"
   
     source {
       identifier = "SOURCE_ID"
     }
   
     target {
       identifier = "TARGET_ID"
     }
   
     auth_provider_binding {
       auth_provider = "projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_ID"
       scopes        = [SCOPES]
       continue_uri  = "https://REDIRECT_URI"
     }
   }
   

   다음을 바꿉니다.

   • BINDING_NAME: 바인딩의 고유 ID입니다.
   • PROJECT_ID: 거버넌스 프로젝트의 프로젝트 ID입니다.
   • LOCATION: 레지스트리 리전 또는 위치입니다(예: us-central1 또는 global).
   • DISPLAY_NAME: 인간이 읽을 수 있는 바인딩 표시 이름입니다.
   • SOURCE_ID: URN 형식의 소스 에이전트의 에이전트 식별자입니다.
   • TARGET_ID: URN 형식의 대상 MCP 서버 또는 도구 리소스의 레지스트리 식별자입니다.
   • AUTH_PROVIDER_ID: 인증 제공업체의 ID입니다.
   • SCOPES: 쉼표로 구분된 OAuth 2.0 범위 목록입니다(예: https://www.googleapis.com/auth/cloud-platform). Terraform에서 각 범위를 큰따옴표로 묶습니다.
   • REDIRECT_URI: 사용자 동의 후 인증 제공업체에 구성된 리디렉션 URI입니다.

   이러한 연결을 관리하는 방법에 대한 자세한 내용은 바인딩 관리를 참조하세요.

ADK 코드에서 바인딩 해결

에이전트 레지스트리에서 인증 제공업체 바인딩을 만든 후 ADK가 인증 흐름을 처리합니다.

AgentRegistry 클라이언트를 사용하여 MCP 도구 모음을 가져오면 ADK가 해당 서버와 연결된 모든 바인딩을 자동으로 확인하고 올바른 스키마를 적용합니다. 코드에서 사용자 인증 정보를 수동으로 구성할 필요가 없습니다.

다음 예시에서는 인증된 MCP 도구 모음을 가져와 에이전트에 연결하는 방법을 보여줍니다.

import os
from google.adk.agents.llm_agent import LlmAgent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_registry import AgentRegistry

project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")

if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable not set.")

# Register the auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Initialize the registry client
registry = AgentRegistry(
    project_id=project_id,
    location=location,
)

# Fetch the registered MCP toolset.
# The ADK applies the bindings configured in Agent Registry.
mcp_server_name = "mcpServers/SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)

# Compose the agent
maps_agent = LlmAgent(
    name="maps_agent",
    model="gemini-1.5-flash",
    instruction=(
        "You are a local guide and navigation expert. Your goal is to provide "
        "accurate location information and directions.\n\n"
        "Rules:\n"
        "1. **Planning**: Before answering, plan how to use the tools to get "
        "the best information (e.g., search for a place first, then get details "
        "or directions).\n"
        "2. **Tool Usage**: Use the Maps MCP tools to find locations, addresses, "
        "and navigation details. Do not guess locations or distances.\n"
        "3. **Output Format**: Provide clear summaries of locations, including "
        "full addresses and key details. Use formatting to make recommendations "
        "easy to read.\n"
        "4. **Tone**: Be helpful, enthusiastic, and descriptive, with "
        "appropriate emojis to enhance the experience."
    ),
    tools=[my_mcp_toolset],
)

SERVER_ID를 등록된 MCP 서버의 ID로 바꿉니다.

사용자를 대신하여 도구에 액세스하기 위해 3LO를 설정하는 경우 get_mcp_toolset 메서드에 continue_uri도 제공해야 합니다. 이 URI는 최종 사용자가 동의를 부여한 후 리디렉션되는 위치를 나타냅니다.

import os
from google.adk.agents.llm_agent import LlmAgent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_registry import AgentRegistry

project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")

if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable not set.")

# Register the auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# Initialize the registry client
registry = AgentRegistry(
    project_id=project_id,
    location=location,
)

# Fetch the registered MCP toolset.
# The ADK applies the bindings configured in Agent Registry.
# For 3-legged OAuth (3LO), provide continue_uri.
mcp_server_name = "mcpServers/SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(
    mcp_server_name=mcp_server_name,
    # Replace with your app's redirect URI:
    continue_uri="https://REDIRECT_URI"
)

# Compose the agent
maps_agent = LlmAgent(
    name="maps_agent",
    model="gemini-1.5-flash",
    instruction=(
        "You are a local guide and navigation expert. Your goal is to provide "
        "accurate location information and directions.\n\n"
        "Rules:\n"
        "1. **Planning**: Before answering, plan how to use the tools to get "
        "the best information (e.g., search for a place first, then get details "
        "or directions).\n"
        "2. **Tool Usage**: Use the Maps MCP tools to find locations, addresses, "
        "and navigation details. Do not guess locations or distances.\n"
        "3. **Output Format**: Provide clear summaries of locations, including "
        "full addresses and key details. Use formatting to make recommendations "
        "easy to read.\n"
        "4. **Tone**: Be helpful, enthusiastic, and descriptive, with "
        "appropriate emojis to enhance the experience."
    ),
    tools=[my_mcp_toolset],
)

다음을 바꿉니다.

• SERVER_ID: 등록된 MCP 서버의 ID입니다.
• REDIRECT_URI: 사용자가 동의를 부여한 후 전송되는 애플리케이션의 리디렉션 URI입니다.

외부 도구에 커스텀 헤더 사용

인증 관리자를 사용하지 않고 인증하거나 요청 헤더를 전달해야 하는 경우 ADK 요청에 직접 커스텀 HTTP 헤더를 제공합니다.

AgentRegistry 클라이언트를 초기화할 때 header_provider 콜백을 제공하여 커스텀 헤더를 구성합니다.

header_provider 콜백은 현재 실행 컨텍스트를 수신하고 HTTP 헤더의 사전을 반환합니다. McpToolset 구성요소는 이러한 헤더를 MCP 서버로 전송되는 다운스트림 요청에 자동으로 연결합니다.

header_provider 콜백에서 제공하는 커스텀 헤더는 대상 MCP 서버로만 전송됩니다. 커스텀 헤더는 Agent Registry API 자체에 대한 인증에 사용되지 않습니다. API는 항상 ADC를 사용합니다.

이 예시에서는 외부 도구 모음에 API 키 또는 커스텀 Bearer 토큰을 제공하는 방법을 보여줍니다.

import os
from typing import Any
from google.adk.integrations.agent_registry import AgentRegistry

project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")
external_api_key = os.environ.get("API_KEY")

# Define the custom header provider.
def my_auth_headers(context: Any) -> dict[str, str]:
    """Returns custom headers injected into MCP toolset requests."""
    return {
        "Authorization": f"Bearer {external_api_key}",
        "X-Custom-Context": "orchestrator-request"
    }

# Initialize the registry client.
# The header_provider is sent to the target MCP server during invocation.
# The header_provider is not used to authenticate against the Agent Registry API.
# The Agent Registry API always uses your Google ADC.
registry = AgentRegistry(
    project_id=project_id,
    location=location,
    header_provider=my_auth_headers
)

# Fetching the toolset automatically attaches the header_provider to the MCP server.
# Replace with the full resource name of your registered MCP server.
mcp_server_name = f"projects/PROJECT_ID/locations/LOCATION/mcpServers/EXTERNAL_SERVER_ID"
external_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)

다음을 바꿉니다.

• PROJECT_ID: 거버넌스 프로젝트의 프로젝트 ID입니다.
• LOCATION: 레지스트리 리전 또는 위치입니다(예: us-central1).
• EXTERNAL_SERVER_ID: 등록된 외부 MCP 서버의 ID입니다.

다음 단계

• Agent Gateway를 사용하여 인증된 도구 요청에 액세스 제어 및 네트워크 경계를 적용하는 방법을 알아봅니다.