Agent2Agent(A2A) 프로토콜은 에이전트를 위한 개방형 통신 프로토콜이자 범용 언어입니다. 이 프로토콜을 사용하면 다양한 빌더와 플랫폼의 에이전트가 서로를 검색하고, 공동작업하고, 작업을 안전하게 위임할 수 있습니다. 이 문서에서는 Gemini Enterprise 관리자가 A2A를 사용하여 빌드되고 모든 플랫폼에서 호스팅되는 에이전트를 Gemini Enterprise에 연결하여 Gemini Enterprise 웹 앱 사용자가 이용할 수 있도록 하는 방법을 설명합니다.
시작하기 전에
다음 항목이 있는지 확인합니다.
Discovery Engine API 사용 설정 Google Cloud프로젝트에 Discovery Engine API를 사용 설정하려면 Google Cloud 콘솔에서 Discovery Engine API 페이지로 이동합니다.
기존 Gemini Enterprise 앱. 앱을 만들려면 앱 만들기를 참조하세요.
A2A 프로토콜을 사용하는 에이전트입니다.
Gemini Enterprise는 A2A v0.3 스트리밍 메커니즘을 지원합니다.
A2A v1.0.0 이상을 사용하는 경우 SDK에서 제공하는 호환성 패키지를 사용하여 에이전트가 이전 메커니즘에서 작동하는지 확인합니다(예: Go의 경우
a2acompat/a2av0패키지, Python의 경우a2a.compat.v0_3패키지).A2A 에이전트가 Cloud Run에서 호스팅되고 기본
.run.appURL을 직접 사용하며 인증이 필요한 경우 Discovery Engine 서비스 에이전트에 Cloud Run 호출자(roles/run.invoker) 역할을 부여합니다(Cloud Run이 Apigee, 부하 분산기 또는 커스텀 도메인 뒤에 있는 경우에는 적용되지 않음).gcloud projects add-iam-policy-binding <var>PROJECT_ID</var> \ --member="serviceAccount:service-<var>PROJECT_NUMBER</var>@gcp-sa-discoveryengine.iam.gserviceaccount.com" \ --role="roles/run.invoker"다음을 바꿉니다.
PROJECT_ID: 프로젝트의 ID입니다.PROJECT_NUMBER: Google Cloud 프로젝트 수
인증 및 승인 구성
에이전트 호스팅 환경 및 보안 요구사항에 따라 Gemini Enterprise가 에이전트를 인증하는 방법, 에이전트가 최종 사용자를 대신하여 다운스트림 리소스 및 도구에 액세스하는 방법, 에이전트 엔드포인트를 보호하는 방법을 구성할 수 있습니다.
- Gemini Enterprise가 에이전트를 인증하는 방법: Gemini Enterprise가 A2A 에이전트 엔드포인트를 호출할 때 서비스 간 IAM 및 최종 사용자 OAuth 2.0 헤더를 전송하는 방법을 알아봅니다.
- 최종 사용자 승인을 위한 OAuth 2.0 구성: Gemini Enterprise에서 OAuth 2.0 승인 리소스를 구성하여 Gemini Enterprise가 최종 사용자 토큰을 획득하고 에이전트를 호출할 때
Authorization헤더에 전송하도록 합니다(예: Gemini Enterprise Agent Platform의 Agent Runtime에 호스팅된 A2A 에이전트를 호출하거나 사용자 토큰을 에이전트 컨테이너에 직접 전달). - 에이전트 아이덴티티 인증 관리자로 3-legged OAuth 구성: 에이전트 아이덴티티 인증 관리자에서 3-legged OAuth(3LO) 인증 제공업체를 구성하여 A2A 에이전트가 모델 컨텍스트 프로토콜(MCP) 서버 또는 서드 파티 API와 같은 특정 도구에 대해 필요에 따라 사용자 위임 토큰을 요청할 수 있도록 합니다.
Gemini Enterprise가 에이전트를 인증하는 방법
Gemini Enterprise가 A2A 에이전트를 호출하면 호스팅 및 보안 구성에 따라 요청 헤더에 인증 및 승인 데이터를 전송할 수 있습니다.
| 헤더 | 설명 |
|---|---|
X-Serverless-Authorization |
서비스 간 IAM 인증(Cloud Run용) A2A 에이전트가 Cloud Run에서 호스팅되고 에이전트 URL이 기본 Gemini Enterprise가 기본 |
Authorization |
최종 사용자 OAuth 2.0 승인(엔드포인트 호출, 사용자 컨텍스트, API 액세스용) A2A 에이전트에 OAuth 2.0 사용자 인증 정보를 구성하면(최종 사용자 승인을 위한 OAuth 2.0 구성 참고) Gemini Enterprise는 로그인한 최종 사용자가 동의를 부여한 후 최종 사용자를 대신하여 OAuth 2.0 액세스 토큰 또는 ID 토큰을 획득하고 이를 표준 Cloud Run에서 호스팅되는 에이전트의 경우 Cloud Run은 |
최종 사용자 승인을 위한 OAuth 2.0 구성(선택사항)
A2A 에이전트의 경우 에이전트 엔드포인트에 Authorization 헤더의 최종 사용자 OAuth 2.0 토큰이 필요한 경우(예: Agent Runtime에서 호스팅되는 A2A 에이전트를 호출하거나 사용자 토큰을 에이전트 컨테이너에 직접 전달하는 경우) Gemini Enterprise에서 OAuth 2.0 사용자 인증 정보를 구성합니다. 인증 및 승인 헤더의 작동 방식에 대한 자세한 내용은 Gemini Enterprise가 에이전트를 인증하는 방법을 참조하세요.
A2A 에이전트가 도구 수준 3-legged OAuth에 에이전트 아이덴티티 인증 관리자를 사용하는 경우(예: 사용자를 대신하여 MCP 서버 또는 서드 파티 API에 액세스) 에이전트 아이덴티티 인증 관리자로 3-legged OAuth 구성을 참조하세요.
OAuth 클라이언트 ID를 만들려면 다음 단계를 따르세요.
Google Cloud 콘솔의 API 및 서비스 페이지에서 사용자 인증 정보 페이지로 이동합니다.
-
에이전트가 액세스할 데이터 소스가 있는 Google Cloud 프로젝트를 선택합니다. 예를 들어 에이전트가 쿼리할 BigQuery 데이터 세트가 포함된 프로젝트를 선택합니다.
사용자 인증 정보 만들기를 클릭하고 OAuth 클라이언트 ID를 선택합니다.
애플리케이션 유형에서 웹 애플리케이션을 선택합니다.
승인된 리디렉션 URI 섹션에 다음 URI를 추가합니다.
https://vertexaisearch.cloud.google.com/oauth-redirecthttps://vertexaisearch.cloud.google.com/static/oauth/oauth.html
만들기를 클릭합니다.
OAuth 클라이언트 생성됨 패널에서 JSON 다운로드를 클릭합니다. 다운로드한 JSON에는 선택한Google Cloud 프로젝트의
Client ID,Authorization URI,Token URI,Client secret이 포함됩니다. 승인 리소스를 만들려면 이러한 세부정보가 필요합니다.
에이전트 아이덴티티 인증 관리자로 3-legged OAuth 구성(선택사항)
A2A 에이전트가 에이전트 개발 키트(ADK)로 빌드되고 3LO(3-legged OAuth)에 에이전트 아이덴티티 인증 관리자를 사용하는 경우 에이전트는 로그인한 사용자를 대신하여 다운스트림 MCP 서버, Google Cloud서비스 또는 서드 파티 API에 인증할 수 있습니다.
A2A 에이전트의 도구에 사용자 동의가 필요한 경우 Gemini Enterprise는 클라이언트 측 3LO 워크플로를 자동으로 관리합니다.
- 동의 프롬프트: 에이전트가
adk_request_credential도구 중단(TASK_STATE_AUTH_REQUIRED)을 반환하면 Gemini Enterprise 웹 앱에서 사용자에게 로그인하라는 메시지를 표시하고 인증 제공업체의 승인 URI를 엽니다. - 사용자 검증 및 토큰 저장: 사용자가 동의하면 인증 제공업체가 Gemini Enterprise 검증 엔드포인트(
https://vertexaisearch.cloud.google.com/validateUserId)로 리디렉션합니다. Gemini Enterprise는 세션 상태를 검증하고 에이전트 아이덴티티 인증 관리자를 통해 사용자 인증 정보를 확정합니다. - 대화 재개: Gemini Enterprise는 완료된
adk_request_credential대답을 A2A 에이전트로 다시 전송합니다. A2A 에이전트는 인증 제공업체에서 사용자의 액세스 토큰을 가져와 도구를 호출합니다.
Gemini Enterprise는 동의 프롬프트, 검증 엔드포인트, 대화 재개를 처리하므로 커스텀 클라이언트 측 UI 애플리케이션을 구현할 필요가 없습니다.
1단계: 3-Legged OAuth 인증 제공업체 설정하기
인증 관리자를 사용하여 3-legged OAuth로 인증의 단계에 따라 Agent Identity API(agentidentity.googleapis.com)를 사용 설정하고, OAuth 클라이언트 애플리케이션을 구성하고, 3-legged OAuth 인증 제공업체를 만듭니다.
Gemini Enterprise에서 사용할 OAuth 클라이언트 및 인증 제공업체를 구성할 때 다음 설정을 포함합니다.
승인된 리디렉션 URI: OAuth 클라이언트 구성에서 인증 제공업체의 콜백 리디렉션 URI를 추가합니다.
https://agentidentitycredentials.googleapis.com/v1/projects/<var>PROJECT_ID</var>/locations/<var>LOCATION</var>/authProviders/<var>AUTH_PROVIDER_NAME</var>/oauthcallbackGemini Enterprise 에이전트 승인 리소스에 동일한 OAuth 클라이언트를 재사용하는 경우(예: Gemini Enterprise가 Agent Runtime에 호스팅된 A2A 에이전트를 호출하도록 허용) Gemini Enterprise 리디렉션 URI(
https://vertexaisearch.cloud.google.com/oauth-redirect)도 포함합니다.계속 URI: 계속 URI(인증 제공업체의 기본 계속 URI 또는 에이전트 코드의
continue_uri)를 Gemini Enterprise 검증 엔드포인트로 설정합니다.https://vertexaisearch.cloud.google.com/validateUserId
2단계: A2A 에이전트 코드 구성
ADK 에이전트를 빌드하고 Agent Runtime에 배포하기 위해 A2aAgent로 래핑할 때는 에이전트 코드가 다음 요구사항을 충족해야 합니다.
- 필수 패키지 버전 설치: 배포 요구사항에
a2a-sdk[http-server]>=1.0.0,google-cloud-aiplatform[agent_engines,adk]>=1.156.0,google-adk[a2a,agent-identity,mcp]>2.7.1를 포함합니다. continue_uri를 Gemini Enterprise로 설정:GcpAuthProviderScheme또는AgentRegistry.get_mcp_toolset에서continue_uri를"https://vertexaisearch.cloud.google.com/validateUserId"로 설정합니다(인증 제공업체에서 기본 계속 URI로 구성하지 않은 경우).- 러너 빌더 함수 내에
GcpAuthProvider등록: 모듈 최상위 수준뿐만 아니라 배포된 컨테이너 워커 프로세스에서Runner를 빌드하는 함수 내에서CredentialManager.register_auth_provider(GcpAuthProvider())를 호출합니다. - 기본 제공
A2aAgentExecutor:A2aAgentExecutor(runner=build_runner)(from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor)을A2aAgent에 전달합니다.event.is_final_response()만 확인하는 맞춤AgentExecutor를 사용하지 마세요.adk_request_credential중단을TASK_STATE_AUTH_REQUIREDA2A 작업 상태로 변환하려면A2aAgentExecutor가 필요하기 때문입니다. AgentCard에 A2A 프로토콜 버전0.3포함: Gemini Enterprise가 A2A v0.3 경로를 통해 에이전트와 통신할 수 있도록 기본1.0인터페이스와 함께agent_card.supported_interfaces에protocol_version=PROTOCOL_VERSION_0_3및protocol_binding=TransportProtocol.HTTP_JSON가 있는AgentInterface를 추가합니다.
ADK + A2A
다음 예시에서는 McpToolset(또는 AgentRegistry.get_mcp_toolset)와 함께 GcpAuthProviderScheme를 사용하여 사용자를 대신해 MCP 서버에 인증하는 ADK A2A 에이전트를 구성합니다.
from a2a.types import AgentInterface, AgentSkill from a2a.utils.constants import PROTOCOL_VERSION_0_3, PROTOCOL_VERSION_1_0, TransportProtocol from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor from google.adk.agents import LlmAgent from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService from google.adk.auth.credential_manager import CredentialManager from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme from google.adk.memory.in_memory_memory_service import InMemoryMemoryService from google.adk.runners import Runner from google.adk.sessions.in_memory_session_service import InMemorySessionService from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams from google.adk.tools.mcp_tool.mcp_toolset import McpToolset from vertexai.agent_engines.templates.a2a import A2aAgent, create_agent_card # Redirect URI for Gemini Enterprise user validation CONTINUE_URI = "https://vertexaisearch.cloud.google.com/validateUserId" auth_scheme = GcpAuthProviderScheme( name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME", scopes=["OAUTH_SCOPE"], continue_uri=CONTINUE_URI, ) mcp_tools = McpToolset( connection_params=StreamableHTTPConnectionParams( url="https://YOUR_MCP_SERVER_URL" ), auth_scheme=auth_scheme, ) # Alternatively, if your MCP server is registered in Agent Registry # with an outbound auth provider binding, use AgentRegistry.get_mcp_toolset: # from google.adk.integrations.agent_registry import AgentRegistry # registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION") # mcp_tools = registry.get_mcp_toolset( # mcp_server_name="projects/PROJECT_ID/locations/LOCATION/mcpServers/MCP_SERVER_ID", # continue_uri=CONTINUE_URI, # ) adk_agent = LlmAgent( model="gemini-2.5-flash", name="AGENT_NAME", description="AGENT_DESCRIPTION", instruction="AGENT_INSTRUCTIONS", tools=[mcp_tools], ) def build_runner() -> Runner: # Register GcpAuthProvider inside the deployed worker process CredentialManager.register_auth_provider(GcpAuthProvider()) return Runner( app_name=adk_agent.name, agent=adk_agent, artifact_service=InMemoryArtifactService(), session_service=InMemorySessionService(), memory_service=InMemoryMemoryService(), ) agent_card = create_agent_card( agent_name="AGENT_DISPLAY_NAME", description="AGENT_DESCRIPTION", skills=[ AgentSkill( id="SKILL_ID", name="SKILL_NAME", description="SKILL_DESCRIPTION", tags=[], ) ], ) agent_card.supported_interfaces = [ AgentInterface( protocol_binding=TransportProtocol.HTTP_JSON, protocol_version=PROTOCOL_VERSION_1_0, url="", ), AgentInterface( protocol_binding=TransportProtocol.HTTP_JSON, protocol_version=PROTOCOL_VERSION_0_3, url="", ), ] a2a_agent = A2aAgent( agent_card=agent_card, agent_executor_builder=lambda: A2aAgentExecutor(runner=build_runner), )
ADK + A2A
다음 예시에서는 AuthenticatedFunctionTool를 GcpAuthProviderScheme와 함께 사용하여 사용자를 대신해 서드 파티 또는 Google CloudREST API를 호출하는 ADK A2A 에이전트를 구성합니다.
from a2a.types import AgentInterface, AgentSkill from a2a.utils.constants import PROTOCOL_VERSION_0_3, PROTOCOL_VERSION_1_0, TransportProtocol from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor from google.adk.agents import LlmAgent from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService 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.memory.in_memory_memory_service import InMemoryMemoryService from google.adk.runners import Runner from google.adk.sessions.in_memory_session_service import InMemorySessionService from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool import httpx from vertexai.agent_engines.templates.a2a import A2aAgent, create_agent_card # Redirect URI for Gemini Enterprise user validation CONTINUE_URI = "https://vertexaisearch.cloud.google.com/validateUserId" auth_config = AuthConfig( auth_scheme=GcpAuthProviderScheme( name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME", scopes=["OAUTH_SCOPE"], continue_uri=CONTINUE_URI, ) ) async def call_external_api(credential: AuthCredential, query: str) -> str: """Calls an external API using the end user's OAuth token.""" token = None if credential and 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://YOUR_API_ENDPOINT", headers={"Authorization": f"Bearer {token}"}, params={"q": query}, ) response.raise_for_status() return response.text authenticated_tool = AuthenticatedFunctionTool( func=call_external_api, auth_config=auth_config, ) adk_agent = LlmAgent( model="gemini-2.5-flash", name="AGENT_NAME", description="AGENT_DESCRIPTION", instruction="AGENT_INSTRUCTIONS", tools=[authenticated_tool], ) def build_runner() -> Runner: # Register GcpAuthProvider inside the deployed worker process CredentialManager.register_auth_provider(GcpAuthProvider()) return Runner( app_name=adk_agent.name, agent=adk_agent, artifact_service=InMemoryArtifactService(), session_service=InMemorySessionService(), memory_service=InMemoryMemoryService(), ) agent_card = create_agent_card( agent_name="AGENT_DISPLAY_NAME", description="AGENT_DESCRIPTION", skills=[ AgentSkill( id="SKILL_ID", name="SKILL_NAME", description="SKILL_DESCRIPTION", tags=[], ) ], ) agent_card.supported_interfaces = [ AgentInterface( protocol_binding=TransportProtocol.HTTP_JSON, protocol_version=PROTOCOL_VERSION_1_0, url="", ), AgentInterface( protocol_binding=TransportProtocol.HTTP_JSON, protocol_version=PROTOCOL_VERSION_0_3, url="", ), ] a2a_agent = A2aAgent( agent_card=agent_card, agent_executor_builder=lambda: A2aAgentExecutor(runner=build_runner), )
3단계: 에이전트 ID로 A2A 에이전트 배포 및 액세스 권한 부여
identity_type=types.IdentityType.AGENT_IDENTITY를 사용하여A2aAgent를 Agent Runtime에 배포합니다.import vertexai from vertexai import types client = vertexai.Client( project="<var>PROJECT_ID</var>", location="<var>LOCATION</var>", http_options=dict(api_version="v1beta1"), ) remote_a2a_agent = client.agent_engines.create( agent=a2a_agent, config={ "display_name": "<var>AGENT_DISPLAY_NAME</var>", "identity_type": types.IdentityType.AGENT_IDENTITY, "requirements": [ "a2a-sdk[http-server]>=1.0.0", "google-cloud-aiplatform[agent_engines,adk]>=1.156.0", "google-adk[a2a,agent-identity,mcp]>2.7.1", "google-genai", "httpx", ], }, )배포가 완료되면 배포된 에이전트의 SPIFFE 주 구성원에 인증 제공업체의 에이전트 ID 사용자(
roles/agentidentity.user) 역할을 부여합니다.gcloud agent-identity auth-providers add-iam-policy-binding <var>AUTH_PROVIDER_NAME</var> \ --project="<var>PROJECT_ID</var>" \ --location="<var>LOCATION</var>" \ --role="roles/agentidentity.user" \ --member="principal://agents.global.org-<var>ORGANIZATION_ID</var>.system.id.goog/resources/aiplatform/projects/<var>PROJECT_NUMBER</var>/locations/<var>LOCATION</var>/reasoningEngines/<var>ENGINE_ID</var>"다음을 바꿉니다.
AUTH_PROVIDER_NAME: 인증 제공업체의 이름입니다.PROJECT_ID: 프로젝트의 ID입니다.LOCATION: 인증 제공업체 및 에이전트가 배포된 리전(예:us-central1)ORGANIZATION_ID: Google Cloud조직 ID입니다.PROJECT_NUMBER: Google Cloud 프로젝트 수ENGINE_ID: 배포된reasoningEngines에이전트의 리소스 ID입니다.
Gemini Enterprise에 A2A 에이전트 등록(A2A를 통한 커스텀 에이전트) 또는 에이전트 레지스트리에서 A2A 에이전트 가져오기(Agent Runtime을 통한 커스텀 에이전트)를 사용하여 배포된 A2A 에이전트를 Gemini Enterprise에 등록합니다. 에이전트는 Agent Runtime에서 호스팅되므로 Gemini Enterprise가 Agent Runtime 엔드포인트를 호출할 수 있도록 Gemini Enterprise에서
https://www.googleapis.com/auth/cloud-platform범위를 사용하여 OAuth 2.0 승인 리소스를 구성합니다.
A2A 에이전트 엔드포인트 보호
Gemini Enterprise가 A2A 에이전트에 전송하는 인증 헤더는 Gemini Enterprise가 에이전트로 인증하는 방법을 참조하세요. 에이전트 엔드포인트 또는 그 앞의 API 게이트웨이를 보호할 때는 다음을 고려하세요.
- 에이전트 카드 보안 스키마: Gemini Enterprise는 에이전트 카드의
securitySchemes및security필드를 사용하여 에이전트를 인증하지 않습니다. - API 키 및 커스텀 헤더: Gemini Enterprise는
apiKey보안 스키마를 지원하지 않으며 에이전트에 전송하는 요청에 정적 API 키 또는 기타 커스텀 헤더 값을 추가하는 방법을 제공하지 않습니다. - 서비스 에이전트 ID 토큰: Gemini Enterprise는 에이전트 URL이
.run.app로 끝나는 기본 Cloud Run URL인 경우에만X-Serverless-Authorization헤더를 전송합니다. 에이전트 URL이 커스텀 도메인, 부하 분산기 또는 API Gateway를 사용하는 경우 Gemini Enterprise는 이 헤더를 전송하지 않습니다. - 최종 사용자 토큰: 에이전트에 OAuth 2.0을 구성하는 경우 Gemini Enterprise는
Authorization헤더에 OAuth 2.0 제공업체의 최종 사용자 토큰을 전송합니다.
Apigee를 사용하여 에이전트 엔드포인트 보호
Apigee API 프록시를 통해 A2A 에이전트를 노출하는 경우 프록시는 Authorization 헤더에서 최종 사용자 토큰을 수신하지만 X-Serverless-Authorization 헤더는 수신하지 않습니다. 프록시를 보호하려면 다음을 수행합니다.
- Google Cloud OAuth 2.0 클라이언트 ID 또는 서드 파티 OAuth 2.0 제공업체를 사용하여 에이전트에 대해 최종 사용자 승인을 위한 OAuth 2.0을 구성하고 에이전트를 등록할 때 해당 OAuth 2.0 세부정보를 제공합니다. Apigee API 프록시를 보호할 때는 OAuth 2.0을 구성해야 합니다. 등록 중에 승인 단계를 건너뛰지 마세요.
- 에이전트 카드에서
url를 Apigee API 프록시의 URL로 설정합니다. - API 프록시에서 요청을 에이전트에 전달하기 전에
Authorization헤더의 최종 사용자 토큰을 검증합니다. OAuth 2.0 제공업체에서 발급하는 토큰 형식에 따라 Apigee 정책을 선택합니다.- 서명된 JWT 액세스 토큰을 발급하는 서드 파티 OAuth 2.0 제공업체: VerifyJWT 정책을 사용하여 제공업체의 공개 JSON 웹 키 세트(JWKS) URI에 대해 토큰 서명을 확인하고 발급기관(
iss) 및 대상(aud) 클레임을 검증합니다. - Google OAuth 2.0(
accounts.google.com): Google OAuth 2.0 액세스 토큰(ya29...)은 서명된 JWT가 아닌 불투명 토큰입니다. ServiceCallout 정책을 사용하여https://oauth2.googleapis.com/tokeninfo를 호출하고 잠재고객(aud) 및scope필드를 확인합니다.
- 서명된 JWT 액세스 토큰을 발급하는 서드 파티 OAuth 2.0 제공업체: VerifyJWT 정책을 사용하여 제공업체의 공개 JSON 웹 키 세트(JWKS) URI에 대해 토큰 서명을 확인하고 발급기관(
A2A 에이전트를 Gemini Enterprise에 등록
Google Cloud 콘솔 또는 REST API를 사용하여 A2A 에이전트를 Gemini Enterprise에 등록할 수 있습니다. 이렇게 하면 Gemini Enterprise 앱 내에서 사용자가 에이전트를 사용할 수 있습니다.
콘솔
Google Cloud 콘솔을 사용하여 A2A 에이전트를 등록하려면 다음 단계를 따르세요.
Google Cloud 콘솔에서 Gemini Enterprise 페이지로 이동합니다.
에이전트를 등록할 앱의 이름을 클릭합니다.
에이전트 > 에이전트 추가를 클릭합니다.
에이전트 유형 선택 섹션에서 A2A를 통한 커스텀 에이전트의 추가를 클릭합니다.
에이전트 카드 JSON 필드에 에이전트 카드 세부정보를 JSON 형식으로 입력합니다. 사용 가능한 필드의 전체 목록은 Agent2Agent(A2A) 프로토콜 공식 사양을 참조하세요. 다음 예시에서는 필수 입력란만 사용합니다.
예를 들면 다음과 같습니다.
{ "protocolVersion": "0.3", "name": "Hello World Agent", "description": "Just a hello world agent", "url": "https://example.com/myagent", "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=", "version": "1.0.0", "capabilities": { }, "skills": [ { "id": "data-analysis", "name": "Data Analysis", "description": "Data analysis", "tags": [] } ], "defaultInputModes": [ "text/plain" ], "defaultOutputModes": [ "text/plain" ] }에이전트 세부정보 프리뷰 > 다음을 클릭합니다.
다음 방법 중 하나를 사용하여 설정을 완료합니다.
- 에이전트가 사용자를 대신하여 Google Cloud 리소스에 액세스하지 못하도록 하고 에이전트 엔드포인트에
Authorization헤더가 필요하지 않은 경우 건너뛰기 및 완료를 클릭하여 이 단계를 건너뜁니다. - 인증 관리자로 3LO를 구성한 경우 건너뛰기 및 완료를 클릭하면 에이전트가 동적으로 액세스를 요청합니다.
인증 관리자로 3LO를 구성하지 않았거나 에이전트 엔드포인트에
Authorization헤더가 필요한 경우(예: Apigee API 프록시를 보호하는 경우) 다음 단계를 따르세요.최종 사용자 승인을 위한 OAuth 2.0 구성(선택사항)에서 생성한 클라이언트 ID, 클라이언트 보안 비밀번호, 승인 URI, 토큰 URI를 입력합니다.
범위를 입력합니다.
마침을 클릭합니다.
- 에이전트가 사용자를 대신하여 Google Cloud 리소스에 액세스하지 못하도록 하고 에이전트 엔드포인트에
REST
REST API를 사용하여 A2A 에이전트를 등록하려면 다음 단계를 따르세요.
Gemini Enterprise에 승인 리소스 추가(선택사항)
에이전트가 사용자를 대신하여 Google Cloud 리소스에 액세스해야 하는 경우 다음 명령어를 실행하여 승인 세부정보 구성(선택사항) 섹션에서 만든 승인 리소스를 Gemini Enterprise에 등록합니다.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTH_ID" \
-d '{
"name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTH_ID",
"serverSideOauth2": {
"clientId": "OAUTH_CLIENT_ID",
"clientSecret": "OAUTH_CLIENT_SECRET",
"authorizationUri": "OAUTH_AUTH_URI",
"tokenUri": "OAUTH_TOKEN_URI"
}
}'
다음을 바꿉니다.
PROJECT_ID: 프로젝트의 ID입니다.PROJECT_NUMBER: Google Cloud 프로젝트 수ENDPOINT_LOCATION: API 요청의 멀티 리전입니다. 다음 값 중 하나를 지정합니다.- 미국 멀티 리전의 경우
us - EU 멀티 리전의 경우
eu - 전역 위치의 경우
global
- 미국 멀티 리전의 경우
LOCATION: 데이터 스토어의 멀티 리전입니다(global,us또는eu).AUTH_ID: 승인 리소스의 ID입니다. 이는 사용자가 정의하는 임의의 영숫자 ID입니다. OAuth 지원이 필요한 에이전트를 등록할 때 이 ID를 나중에 참조해야 합니다.OAUTH_CLIENT_ID: OAuth 사용자 인증 정보를 만들 때 획득한 OAuth 2.0 클라이언트 식별자입니다.OAUTH_CLIENT_SECRET: OAuth 사용자 인증 정보를 만들 때 획득한 OAuth 2.0 클라이언트 보안 비밀번호입니다.OAUTH_AUTH_URI: 승인 URI입니다. 앱을 승인하려면 OAuth 사용자 인증 정보 JSON 파일의 세부정보를 사용하여 특정 승인 URI를 구성합니다. 다음 템플릿을 복사하고 자리표시자를 특정 값으로 바꿉니다.https://accounts.google.com/o/oauth2/v2/auth?client_id=OAUTH_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=YOUR_CUSTOM_SCOPES&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
YOUR_CUSTOM_SCOPES: 필요한 범위를 추가할 수 있습니다. 예를 들어 다음 OAuth 범위 문자열은 Google Drive 및 Google Docs에 대한 읽기 전용 액세스를 요청합니다.scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocuments.readonly
OAUTH_TOKEN_URI: OAuth 사용자 인증 정보를 만들 때 획득한 토큰 URI입니다.
승인 URI 매개변수에 대한 자세한 정보
URI가 올바르게 작동하는지 확인하려면 다음 필드를 확인하세요.
| 매개변수 | 가치 또는 액션 |
|---|---|
client_id |
다운로드한 JSON에 있는 client_id로 바꿉니다. |
redirect_uri |
변경하지 않습니다. https://vertexaisearch.cloud.google.com/static/oauth/oauth.html이어야 합니다. |
scope |
앱이 사용자를 대신하여 액세스해야 하는 Google API 범위를 나열합니다. 예를 들어 BigQuery에 대한 액세스 권한을 부여하려면 여러 범위를 사용하는 경우 공백으로 구분합니다. URL에서는 |
include_granted_scopes |
true이어야 합니다. |
response_type |
승인 코드를 받으려면 code이어야 합니다. |
access_type |
갱신 토큰을 수신하도록 offline로 설정합니다. |
prompt |
사용자에게 항상 동의 화면이 표시되도록 하려면 consent로 설정합니다. |
A2A 에이전트 등록
Gemini Enterprise에서 에이전트를 만들고 등록하려면 agents.create 메서드를 사용합니다. 다음 명령어는 필수 필드만 사용합니다. 사용 가능한 필드의 전체 목록은 Agent2Agent(A2A) 프로토콜 공식 사양을 참조하세요.
다음 명령어를 실행하여 A2A 에이전트를 Gemini Enterprise에 등록합니다.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents \
-d '
{
"name": "AGENT_NAME",
"displayName": "AGENT_DISPLAY_NAME",
"description": "AGENT_DESCRIPTION",
"a2aAgentDefinition": {
"jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
},
"authorizationConfig": {
"agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
}
}
'
다음을 바꿉니다.
ENDPOINT_LOCATION: API 요청의 멀티 리전입니다. 다음 값 중 하나를 지정합니다.- 미국 멀티 리전의 경우
us - EU 멀티 리전의 경우
eu - 전역 위치의 경우
global
- 미국 멀티 리전의 경우
LOCATION: 데이터 스토어의 멀티 리전입니다(global,us또는eu).PROJECT_ID: 프로젝트의 ID입니다.APP_ID: 에이전트를 등록할 앱의 ID입니다.AGENT_NAME: 에이전트의 고유 식별자입니다.AGENT_DISPLAY_NAME: 웹 앱에 표시되는 에이전트의 이름입니다.AGENT_DESCRIPTION: 에이전트가 수행할 수 있는 일에 대한 설명입니다.PROTOCOLVERSION: 에이전트가 지원하는 A2A 프로토콜의 버전입니다. 지원되는 버전에 대한 자세한 내용은 A2A 출시 노트를 참조하세요.AGENT_URL: 에이전트의 엔드포인트 URL입니다.AGENT_VERSION: 에이전트의 버전입니다.INPUT_MODE: 기본 입력 미디어 유형입니다. 예를 들면application/json또는text/plain입니다.OUTPUT_MODE: 기본 출력 미디어 유형입니다. 예를 들면text/plain"또는image/png입니다.CAPABILITIES: 지원되는 A2A 기능이 포함된 JSON 객체입니다. 예를 들면\"streaming\": true또는\"pushNotifications\": false입니다.SKILLS: 에이전트가 제공하는AgentSkill객체 목록입니다.authorizationConfig: 승인 세부정보를 획득했고 에이전트가 사용자를 대신하여 Google Cloud 리소스에 액세스하도록 하려면 JSON 리소스에authorization_config필드를 추가합니다.AUTH_ID: Gemini Enterprise에 승인 리소스 추가 섹션에서 AUTH_ID에 사용한 값입니다.
에이전트의 작성자 및 연락처 정보 표시(선택사항)
기본적으로 등록한 A2A 에이전트는 Gemini Enterprise에 작성자가 표시되지 않습니다. 에이전트를 빌드한 사람과 사용자가 문의할 수 있는 사람을 표시하려면 에이전트를 등록하거나 업데이트하는 데 사용하는 에이전트 카드 JSON의 capabilities.extensions 필드에 에이전트 메타데이터 확장 프로그램을 추가합니다.
{
"capabilities": {
"extensions": [
{
"uri": "https://www.googleapis.com/gemini-enterprise/a2a/extensions/agent_metadata/v1",
"params": {
"authorName": "Example Team",
"contactEmail": "agent-support@example.com"
}
}
]
}
}
등록 예시의 다른 에이전트 카드 필드를 capabilities와 함께 유지합니다. REST API에서 확장 프로그램은 이스케이프 처리된 jsonAgentCard 문자열의 일부입니다.
params 필드는 다음 값을 지원합니다. 둘 다 선택사항입니다.
| 매개변수 | 설명 |
|---|---|
authorName |
에이전트를 빌드한 사람, 팀 또는 회사의 이름입니다. 에이전트 갤러리에서는 에이전트 카드에 AUTHOR_NAME 제공으로 표시되고 에이전트 정보 대화상자에는 작성자로 표시됩니다. 갤러리에서는 에이전트에 자체 소유자 이름이 없는 경우에만 이 이름을 표시합니다. 'Google'이라는 단어가 포함된 이름은 Google에서 빌드한 에이전트로 오인되지 않도록 표시되지 않습니다. |
contactEmail |
사용자가 작성자에게 연락할 수 있는 이메일 주소입니다. 에이전트 정보 대화상자에는 연락처로 표시됩니다. |
각 값은 256자(영문 기준) 이하의 문자열이어야 하며 contactEmail는 유효한 이메일 주소여야 합니다. Gemini Enterprise는 이러한 요구사항을 충족하지 않는 값을 무시합니다. Gemini Enterprise는 작성자 이름이나 연락처 이메일을 확인하지 않습니다.
앱에 연결된 에이전트 나열
다음 코드 샘플은 앱에 연결된 모든 에이전트의 세부정보를 가져오는 방법을 보여줍니다.
REST
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"
변수를 다음 값으로 바꿉니다.
- ENDPOINT_LOCATION: API 요청의 멀티 리전입니다. 다음 값 중 하나를 지정합니다.
- 미국 멀티 리전의 경우
us - EU 멀티 리전의 경우
eu - 전역 위치의 경우
global
- 미국 멀티 리전의 경우
- PROJECT_ID: Google Cloud 프로젝트의 ID입니다.
- LOCATION: 앱의 멀티 리전입니다(
global,us또는eu). - APP_ID: Gemini Enterprise 앱의 ID입니다.
에이전트가 Google에서 사전 빌드되지 않은 경우 응답의 처음 몇 줄에 name 필드가 포함됩니다. 이 필드의 값에는 경로 끝에 있는 에이전트 ID가 포함됩니다. 예를 들어 다음 응답에서 에이전트 ID는 12345678901234567890입니다.
{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}
A2A 에이전트 세부정보 보기
다음 코드 샘플은 Gemini Enterprise에 등록된 에이전트의 세부정보를 가져오는 방법을 보여줍니다.
REST
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"
변수를 다음 값으로 바꿉니다.
- ENDPOINT_LOCATION: API 요청의 멀티 리전입니다. 다음 값 중 하나를 지정합니다.
- 미국 멀티 리전의 경우
us - EU 멀티 리전의 경우
eu - 전역 위치의 경우
global
- 미국 멀티 리전의 경우
- PROJECT_ID: Google Cloud 프로젝트의 ID입니다.
- LOCATION: 앱의 멀티 리전입니다(
global,us또는eu). - APP_ID: Gemini Enterprise 앱의 ID입니다.
- AGENT_ID: 에이전트의 ID입니다. 앱에 연결된 에이전트를 나열하여 에이전트 ID를 확인할 수 있습니다.
A2A 에이전트 업데이트
Google Cloud 콘솔 또는 REST API를 사용하여 Gemini Enterprise에 등록된 기존 A2A 에이전트의 세부정보를 수정할 수 있습니다.
콘솔
Google Cloud 콘솔을 사용하여 A2A 에이전트를 업데이트하려면 다음 단계를 따르세요.
Google Cloud 콘솔에서 Gemini Enterprise 페이지로 이동합니다.
업데이트할 에이전트가 포함된 앱의 이름을 클릭합니다.
에이전트를 클릭합니다.
업데이트할 A2A(커스텀) 에이전트의 이름을 클릭한 다음 수정을 클릭합니다.
에이전트 카드 JSON 필드에서 에이전트 카드 세부정보를 JSON 형식으로 업데이트합니다. 사용 가능한 필드의 전체 목록은 Agent2Agent(A2A) 프로토콜 공식 사양을 참조하세요. 다음 예시에서는 필수 입력란만 사용합니다.
예를 들면 다음과 같습니다.
{ "protocolVersion": "0.3", "name": "Hello World Agent", "description": "Just a hello world agent", "url": "https://example.com/myagent", "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=", "version": "1.1.0", "capabilities": { }, "skills": [ { "id": "data-analysis", "name": "Data Analysis", "description": "Data analysis", "tags": [] } ], "defaultInputModes": [ "text/plain" ], "defaultOutputModes": [ "text/plain" ] }저장을 클릭합니다.
REST
Gemini Enterprise에 등록된 A2A 에이전트의 세부정보를 업데이트하려면 agents.patch 메서드를 사용합니다. 다음 명령어는 필수 필드만 사용합니다. 사용 가능한 필드의 전체 목록은 Agent2Agent(A2A) 프로토콜 공식 사양을 참조하세요.
다음 명령어를 실행하여 Gemini Enterprise로 A2A 에이전트를 업데이트합니다.
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID \
-d '
{
"name": "AGENT_NAME",
"displayName": "AGENT_DISPLAY_NAME",
"description": "AGENT_DESCRIPTION",
"a2aAgentDefinition": {
"jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
},
"authorizationConfig": {
"agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
}
}
'
다음을 바꿉니다.
ENDPOINT_LOCATION: API 요청의 멀티 리전입니다. 다음 값 중 하나를 지정합니다.- 미국 멀티 리전의 경우
us - EU 멀티 리전의 경우
eu - 전역 위치의 경우
global
- 미국 멀티 리전의 경우
LOCATION: 데이터 스토어의 멀티 리전입니다(global,us또는eu).PROJECT_ID: 프로젝트의 ID입니다.APP_ID: 에이전트를 등록할 앱의 ID입니다.- AGENT_ID: 에이전트의 ID입니다. 앱에 연결된 에이전트를 나열하여 에이전트 ID를 확인할 수 있습니다.
AGENT_NAME: 에이전트의 고유 식별자입니다.AGENT_DISPLAY_NAME: 웹 앱에 표시되는 에이전트의 이름입니다.AGENT_DESCRIPTION: 에이전트가 수행할 수 있는 일에 대한 설명입니다.PROTOCOLVERSION: 에이전트가 지원하는 A2A 프로토콜의 버전입니다. 지원되는 버전에 대한 자세한 내용은 A2A 출시 노트를 참조하세요.AGENT_URL: 에이전트의 엔드포인트 URL입니다.AGENT_VERSION: 에이전트의 버전입니다.INPUT_MODE: 기본 입력 미디어 유형입니다. 예를 들면application/json또는text/plain입니다.OUTPUT_MODE: 기본 출력 미디어 유형입니다. 예를 들면text/plain또는image/png입니다.CAPABILITIES: 지원되는 A2A 기능이 포함된 JSON 객체입니다. 예를 들면\"streaming\": true또는\"pushNotifications\": false입니다.SKILLS: 에이전트가 제공하는AgentSkill객체 목록입니다.authorizationConfig: 승인 세부정보를 획득했고 에이전트가 사용자를 대신하여 Google Cloud 리소스에 액세스하도록 하려면 JSON 리소스에authorization_config필드를 추가합니다.AUTH_ID: Gemini Enterprise에 승인 리소스 추가 섹션에서 AUTH_ID에 사용한 값입니다.
A2A 에이전트 삭제
다음 코드 샘플은 앱에 연결된 에이전트를 삭제하는 방법을 보여줍니다.
REST
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"
변수를 다음 값으로 바꿉니다.
- ENDPOINT_LOCATION: API 요청의 멀티 리전입니다. 다음 값 중 하나를 지정합니다.
- 미국 멀티 리전의 경우
us - EU 멀티 리전의 경우
eu - 전역 위치의 경우
global
- 미국 멀티 리전의 경우
- PROJECT_ID: Google Cloud 프로젝트의 ID입니다.
- LOCATION: 앱의 멀티 리전입니다(
global,us또는eu). - APP_ID: Gemini Enterprise 앱의 ID입니다.
- AGENT_ID: 에이전트의 ID입니다. 앱에 연결된 에이전트를 나열하여 에이전트 ID를 확인할 수 있습니다.
다음 단계
- 웹 앱에서 Gemini Enterprise에 등록한 에이전트를 사용합니다.