Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

인증 관리자로 API 키를 사용하여 인증

에이전트가 Google 지도 또는 날씨 API와 같은 외부 도구를 인증하도록 하려면 에이전트 ID 인증 관리자에서 API 키 인증 제공업체를 사용하여 아웃바운드 인증을 구성합니다.

API 키 인증 제공업체는 암호화 키를 관리합니다. 이 기능을 사용하면 에이전트의 코드에서 키를 하드 코딩하거나 수동으로 관리할 필요가 없습니다.

API 키 워크플로

API 키 인증 제공업체는 에이전트의 ID를 사용하며 사용자 동의가 필요하지 않습니다. Google은 저장 중에 API 키를 보호하기 위한 조치를 취합니다. 에이전트 개발 키트 (ADK)를 사용하면 API 키가 자동으로 검색되어 도구 호출 헤더에 삽입됩니다.

시작하기 전에

올바른 인증 방법을 선택했는지 확인합니다.
Agent Identity API를 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할(roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기
API 사용 설정하기
에이전트를 만들고 배포합니다.
연결하려는 서드 파티 서비스에서 API 키를 가져옵니다.
이 작업을 완료하는 데 필요한 역할이 있는지 확인합니다.

필요한 역할

API 키 인증 제공업체를 만들고 사용하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대해 다음 IAM 역할을 부여해 달라고 요청하세요.

인증 제공업체를 만들려면 다음 안내를 따르세요.
- 에이전트 ID 관리자 (roles/agentidentity.admin)
- 에이전트 ID 편집기 (roles/agentidentity.editor)
인증 제공업체를 사용하려면 다음 안내를 따르세요.
- 에이전트 ID 사용자 (roles/agentidentity.user)
- Vertex AI 사용자 (roles/aiplatform.user)
- 서비스 사용량 소비자 (roles/serviceusage.serviceUsageConsumer)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이러한 사전 정의된 역할에는 API 키 인증 제공업체를 만들고 사용하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

API 키 인증 제공업체를 만들고 사용하려면 다음 권한이 필요합니다.

인증 제공업체를 만들려면 다음 안내를 따르세요. agentidentity.authProviders.create
인증 제공업체를 사용하려면 다음 안내를 따르세요.
- agentidentity.authProviders.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

서드 파티 서비스에서 API 키 가져오기

인증 제공업체를 만들기 전에 에이전트가 연결할 서드 파티 서비스에서 API 키를 가져옵니다.

외부의 서드 파티 서비스에 연결하는 경우 Google Cloud 해당 서비스의 개발자 포털에서 API 키를 가져오고 이 섹션의 단계를 건너뜁니다.

서비스 ( Google Cloud 예: Cloud Translation 또는 Google 지도)에 연결하는 경우 다음 단계를 실행하여 API 키를 생성하고 구성할 수 있습니다.

콘솔에서 프로젝트에 필요한 API 서비스를 사용 설정합니다. Google Cloud
1. 콘솔에서 API 및 서비스>라이브러리 페이지로 이동합니다. Google Cloud
  API 및 서비스 >라이브러리로 이동
2. 에이전트가 사용하는 API(예: Cloud Translation API 또는 Google 지도 날씨 API)를 검색하고 사용 설정합니다.
3. 생성된 API 키 문자열을 복사합니다.
API 키를 구성합니다.
1. Google Cloud 콘솔에서 API 및 서비스>사용자 인증 정보 페이지로 이동합니다.
  API 및 서비스>사용자 인증 정보로 이동
2. 사용자 인증 정보 만들기 >API 키를 클릭합니다.
3. API 키 만들기 대화상자에서 다음 단계를 따르세요.
  1. API 키의 고유한 이름을 입력합니다.
  2. 키를 사용 설정한 특정 API로 제한하려면 API 제한사항 선택 목록에서 해당 API를 선택합니다.
  3. 선택사항: 보안 위험을 줄이기 위해 키를 제한하세요 섹션에서 액세스를 제한할 애플리케이션 유형을 선택합니다.
  4. 만들기 를 클릭합니다.
서비스 엔드포인트에 테스트 요청을 전송하여 API 키의 유효성을 검사합니다.
- Cloud Translation API 키를 확인하려면 다음 명령어를 실행합니다.
```
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"
```
  YOUR_API_KEY를 생성한 API 키로 바꿉니다.
- Google 지도 날씨 API 키를 확인하려면 다음 명령어를 실행합니다.
```
curl -X GET \
  "https://weather.googleapis.com/v1/currentConditions:lookup?key=YOUR_API_KEY&location.latitude=37.4220&location.longitude=-122.0841"
```
  YOUR_API_KEY를 생성한 API 키로 바꿉니다.
API 키가 유효하고 올바르게 구성된 경우 서비스는 요청된 데이터를 반환합니다.

API 키 인증 제공업체 만들기

인증 제공업체를 만들어 서드 파티 애플리케이션의 구성 및 사용자 인증 정보를 정의합니다.

에이전트 코드에서 인증

에이전트를 인증하려면 ADK를 사용하면 됩니다.

ADK

ADK의 MCP 도구 모음을 사용하여 에이전트의 코드에서 인증 제공업체를 참조합니다.

from google.adk.agents.llm_agent import LlmAgent
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 = LlmAgent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

예: Google 지도 MCP에 연결

다음 예에서는 에이전트를 Google 지도 MCP 서버에 연결하는 agent.py 구성을 보여줍니다.

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"

# 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

ADK의 인증된 함수 도구를 사용하여 에이전트의 코드에서 인증 제공업체를 참조합니다.

import httpx
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_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 = LlmAgent(
    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)

예: Google 지도 날씨 API에 연결

다음 예에서는 인증된 함수 도구를 사용하여 에이전트를 Google 지도 날씨 API에 연결하는 agent.py 구성을 보여줍니다.

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"

# 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

ADK의 에이전트 레지스트리 MCP 도구 모음을 사용하여 에이전트의 코드에서 인증 제공업체를 참조합니다.

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_identity import 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
from google.adk.integrations.agent_registry import AgentRegistry

# First, 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"
)

# Set Agent Registry
registry = AgentRegistry(project_id="PROJECT_ID", location="global")

toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/locations/"
        "global/mcpServers/"
        "agentregistry-00000000-0000-0000-0000-000000000000"
    ),
    auth_scheme=auth_scheme,
)

# Example MCP tool
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="MCP_URL"),
    auth_scheme=auth_scheme,
)

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

에이전트 배포

에이전트를 Google Cloud에 배포할 때는 에이전트 ID가 사용 설정되어 있는지 확인합니다.

Gemini Enterprise Agent Platform의 Agent Runtime 에 배포하는 경우 identity_type=AGENT_IDENTITY 플래그를 사용합니다.

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

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

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(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]"],
    },
)