도구 및 리소스에 인증

오케스트레이터 에이전트가 에이전트 레지스트리를 통해 검색된 원격 에이전트 또는 모델 컨텍스트 프로토콜(MCP) 도구 세트를 호출하는 경우 이러한 기능을 제공하는 기본 서비스로 인증해야 합니다.

이 문서에서는 Agent Registry 리소스의 인증을 처리하는 방법을 설명합니다.

시작하기 전에

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

  1. 프로젝트에서 에이전트 레지스트리 설정

  2. 에이전트 개발 키트 (ADK)의 최신 버전을 설치하거나 업그레이드합니다.

    pip install --upgrade google-adk

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

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

    gcloud auth application-default login

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

  4. 이 가이드의 예시를 따르려면 다음과 같이 환경 변수를 설정해야 합니다.

    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 인증 관리자를 사용합니다.

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

또는 타겟 에이전트에 고급 컨텍스트를 전송하거나 외부 도구 모음에서 에이전트 ID 인증 관리자를 지원하지 않는 경우 ADK 요청에서 직접 맞춤 HTTP 헤더를 제공할 수 있습니다.

사용 사례에 가장 적합한 방법을 확인하려면 인증 모델을 참고하세요.

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

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

에이전트와 연결된 ID에 기본 서비스에 필요한 Identity and Access Management 권한이 있어야 합니다. 예를 들어 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,
)

MCP 도구 인증

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

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,
)

# 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)

맞춤 도구 및 위임된 액세스 권한에 인증 관리자 사용

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

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

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

인증 제공업체를 구성하면 ADK가 오케스트레이터의 인증 흐름을 관리합니다. 예를 보려면 ADK 코드에서 바인딩 해결을 참고하세요.

맞춤 도구 액세스

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

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

  2. 인증 프로바이더 바인딩: 오케스트레이터 에이전트가 타겟의 올바른 인증 프로바이더를 감지하도록 하려면 에이전트와 인증 프로바이더 간에 에이전트 레지스트리의 바인딩을 만들어야 합니다. 바인딩을 사용하면 코드에서 인증 제공업체를 수동으로 정의하지 않아도 됩니다.

    에이전트를 인증 제공업체에 명시적으로 연결하는 바인딩을 만듭니다. --auth-provider 리소스 이름을 지정할 때는 프로젝트 ID를 사용해야 합니다.

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

    이러한 연결 관리에 대한 자세한 내용은 바인딩 관리를 참고하세요.

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

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

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

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

  3. 인증 프로바이더 바인딩: 오케스트레이터 에이전트가 타겟의 올바른 인증 프로바이더를 감지하도록 하려면 에이전트와 인증 프로바이더 간에 에이전트 레지스트리의 바인딩을 만들어야 합니다. 바인딩을 사용하면 코드에서 인증 제공업체를 수동으로 정의하지 않아도 됩니다.

    에이전트를 인증 제공업체에 명시적으로 연결하는 바인딩을 만듭니다. --auth-provider 리소스 이름을 지정할 때는 프로젝트 ID를 사용해야 합니다.

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

    이러한 연결 관리에 대한 자세한 내용은 바인딩 관리를 참고하세요.

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],
)

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

[...]

# 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],
)

외부 도구에 맞춤 헤더 사용

타겟 에이전트에 고급 컨텍스트를 전송하거나 외부 도구 모음에서 에이전트 ID 인증 관리자를 지원하지 않는 경우 ADK 요청에서 직접 맞춤 HTTP 헤더를 제공할 수 있습니다.

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

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

header_provider 콜백에서 제공하는 맞춤 헤더는 에이전트 또는 도구인 타겟 서비스에만 전송됩니다. 커스텀 헤더는 에이전트 레지스트리 API 자체에 대해 인증하는 데 사용되지 않습니다. API는 항상 ADC를 사용합니다.

이 예에서는 외부 도구 모음에 API 키 또는 맞춤 베어러 토큰을 제공하는 방법을 보여줍니다.

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 the tool or agent requests."""
    return {
        "Authorization": f"Bearer {external_api_key}",
        "X-Custom-Context": "orchestrator-request"
    }

# Initialize the registry client.
# The header_provider is sent to the MCP server or agent 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)

다음 단계

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