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

상담사가 Google 지도 또는 날씨 API와 같은 외부 도구를 인증할 수 있도록 하려면 상담사 ID 인증 관리자에서 API 키 인증 제공업체를 사용하여 아웃바운드 인증을 구성하세요.

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

API 키 워크플로

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

시작하기 전에

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

필요한 역할

API 키 인증 프로바이더를 만들고 사용하는 데 필요한 권한을 얻으려면 운영자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

인증 제공업체를 만들려면 다음 단계를 따르세요.
- IAM 커넥터 관리자 (roles/iamconnectors.admin)
- IAM 커넥터 편집자 (roles/iamconnectors.editor)
인증 제공업체를 사용하려면 다음 단계를 따르세요.
- IAM 커넥터 사용자 (roles/iamconnectors.user)
- 에이전트 기본 액세스 (roles/aiplatform.agentDefaultAccess)
- 에이전트 컨텍스트 편집자 (roles/aiplatform.agentContextEditor)
- Vertex AI 사용자(roles/aiplatform.user)
- 서비스 사용량 소비자(roles/serviceusage.serviceUsageConsumer)

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

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

필수 권한

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

인증 제공업체를 만들려면 iamconnectors.connectors.create 권한이 필요합니다.
인증 제공업체를 사용하려면 다음 단계를 따르세요.
- iamconnectors.connectors.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

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

API 키 인증 제공업체 만들기

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

API 키 인증 제공자를 만들려면 Google Cloud 콘솔 또는 Google Cloud CLI를 사용하세요.

콘솔

Google Cloud 콘솔에서 Agent Registry 페이지로 이동합니다.
에이전트 레지스트리로 이동
인증 제공자를 만들 에이전트의 이름을 클릭합니다.
ID를 클릭합니다.
인증 제공업체 섹션에서 인증 제공업체 추가를 클릭합니다.
인증 제공업체 추가 창에서 이름과 설명을 입력합니다.

이름에는 소문자, 숫자 또는 하이픈만 포함할 수 있으며, 하이픈으로 끝나면 안 되고 소문자로 시작해야 합니다.
OAuth 유형 목록에서 API 키를 선택합니다.
만들고 계속하기를 클릭합니다.
에이전트 ID에 인증 제공자를 사용할 권한을 부여하려면 액세스 권한 부여를 클릭합니다.
이렇게 하면 인증 제공업체 리소스의 에이전트 ID에 커넥터 사용자(roles/iamconnectors.user) 역할이 자동으로 할당됩니다.
인증 제공업체 사용자 인증 정보 섹션에 API 키를 입력합니다.
공급업체 구성 추가를 클릭합니다.

새로 생성된 인증 제공자가 인증 제공자 목록에 표시됩니다.

Google Cloud CLI

인증 제공업체를 만듭니다.

gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --api-key="API_KEY"

인증 제공업체를 사용할 수 있는 권한을 에이전트 ID에 부여하려면 프로젝트 또는 특정 인증 제공업체의 IAM 허용 정책을 업데이트하고 커넥터 사용자 (roles/iamconnectors.user) 역할을 에이전트 보안 주체에 부여하세요.

상담사 ID는 업계 표준 SPIFFE ID 형식을 기반으로 합니다. IAM 허용 정책에서 에이전트 ID는 주 구성원 식별자를 사용하여 참조됩니다.
프로젝트 수준 (gcloud)

프로젝트 수준에서 역할을 부여하면 에이전트가 해당 프로젝트의 모든 인증 제공업체를 사용할 수 있습니다.
- 단일 에이전트에게 프로젝트의 인증 제공업체에 대한 액세스 권한을 부여하려면 다음 명령어를 실행합니다.
  gcloud projects add-iam-policy-binding PROJECT_ID \ --role='roles/iamconnectors.user' \ --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"
- 프로젝트의 모든 에이전트에게 인증 제공업체에 대한 액세스 권한을 부여하려면 다음 명령어를 실행하세요.
  gcloud projects add-iam-policy-binding PROJECT_ID \ --role='roles/iamconnectors.user' \ --member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER"
커넥터 수준 (curl)

단일 에이전트에게 특정 인증 제공업체에 대한 액세스 권한을 부여하려면 setIamPolicy API를 사용합니다. 이 명령어는 리소스의 기존 허용 정책을 덮어씁니다.
```
curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
  "policy": {
    "bindings": [
      {
        "role": "roles/iamconnectors.user",
        "members": ["principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"]
      }
    ]
  }
}' \
    "https://iamconnectors.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME:setIamPolicy"
```
다음을 바꿉니다.
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
- AUTH_PROVIDER_NAME: 인증 제공업체의 이름입니다.
- ORGANIZATION_ID: Google Cloud 조직 ID입니다.
- PROJECT_NUMBER: Google Cloud 프로젝트 번호.
- LOCATION: 에이전트의 위치입니다 (예: us-central1).
- ENGINE_ID: 추론 엔진의 ID입니다.

에이전트 코드에서 인증

에이전트를 인증하려면 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 the Google Cloud auth provider so the CredentialManager can use it.
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create the Google Cloud auth provider scheme using the auth provider's full resource name.
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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="YOUR_AGENT_NAME",
    model="gemini-2.0-flash",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

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
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/connectors/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="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

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

vertex_app = agent_engines.AdkApp(app_name=app)

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 by providing Auth Provider full resource name
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

에이전트 배포

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

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