Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

A2A 프로토콜 도구

에이전트 간 (A2A) 프로토콜은 자율 AI 에이전트가 서로 다른 시스템 간에 통신하고 작업을 조율할 수 있도록 지원하는 개방형 메시지 표준입니다.

CX Agent Studio에서 A2A 프로토콜 도구를 사용하면 에이전트 애플리케이션이 외부 원격 에이전트에게 작업을 위임하거나 외부 애플리케이션 및 오케스트레이터가 표준화된 메시지를 사용하여 CX Agent Studio 에이전트를 호출할 수 있습니다.

A2A 작동 방식

CX Agent Studio의 A2A 프로토콜은 위임 모델을 사용하여 작동합니다.

위임 모델

위임 모델에서 시작 CX Agent Studio 에이전트는 기본 오케스트레이터 역할을 하며 전체 세션 제어를 유지합니다.

세션 소유권: 기본 상담사가 사용자 대화 세션을 유지합니다. 전문 하위 작업이 필요한 경우 기본 에이전트는 원격 에이전트를 도구로 호출합니다.
제어 흐름: 원격 에이전트가 요청을 처리하고 구조화된 응답 데이터를 반환합니다. 제어권은 즉시 기본 에이전트로 돌아가며, 기본 에이전트는 최종 사용자를 위해 결과를 요약하거나 통합합니다.
컨텍스트 전송: 기본 에이전트는 위임된 작업에 필요한 매개변수와 대화 컨텍스트만 전송합니다.

A2A 위임 시퀀스 다이어그램

텍스트 기반 커뮤니케이션

A2A 프로토콜의 모든 에이전트 간 통신은 텍스트 기반입니다.

최종 사용자가 음성 채널(예: 전화 통신 또는 WebRTC)을 통해 기본 에이전트와 상호작용하는 경우 음성이 먼저 텍스트로 변환됩니다.
기본 에이전트는 HTTP 요청 페이로드에서 텍스트 스크립트와 매개변수를 원격 하위 에이전트로 전송합니다.
원본 오디오 스트림과 삽입은 A2A 네트워크 인터페이스를 통해 전송되지 않습니다.

형식 지원

A2A 프로토콜의 모달리티 (텍스트 대 음성) 지원은 통신 방향에 따라 다릅니다.

원격 에이전트에서 CX Agent Studio로: 텍스트 모달리티만 지원합니다.
CX Agent Studio에서 원격 에이전트로: CX Agent Studio의 경우 모달리티에 구애받지 않습니다. 즉, CX Agent Studio 세션은 음성 또는 텍스트와 같은 지원되는 모달리티를 사용할 수 있지만 원격 에이전트는 텍스트만 수신합니다.

결제

기본 세션과 원격 세션이 모두 CX Agent Studio에 있고 동일한 프로젝트에 있는 경우 1세션에 대한 요금이 청구됩니다.

그렇지 않으면 여러 프로젝트 또는 서드 파티 시스템의 기본 세션과 원격 세션에 대해 세션 2개에 대한 요금이 청구됩니다.

인증 및 액세스 제어

인증 요구사항은 통신 방향과 타겟 서비스에 따라 다릅니다.

방향	타겟 도착 페이지	인증 메커니즘	필요한 IAM 역할	설명
인바운드 (CX Agent Studio 외부)	CX Agent Studio 에이전트 애플리케이션	OAuth 2.0 액세스 토큰	`roles/ces.client`	외부 호출자가 CX Agent Studio 인바운드 엔드포인트를 호출하는 데 필요합니다.
아웃바운드 (CX Agent Studio에서 CX Agent Studio로)	다른 프로젝트의 CX Agent Studio 에이전트	서비스 에이전트	`roles/ces.client`	타겟 프로젝트에서 호출 프로젝트의 서비스 에이전트에 부여됩니다.
아웃바운드 (CX Agent Studio에서 Cloud Run으로)	Cloud Run 서비스	서비스 에이전트 ID 토큰	`roles/run.invoker`	Cloud Run 서비스에서 호출 프로젝트의 서비스 에이전트에 부여됩니다.
아웃바운드 (CX Agent Studio에서 Vertex AI로)	Vertex AI Agent Engine	서비스 에이전트 OAuth	`roles/aiplatform.user`	타겟 프로젝트에서 호출 프로젝트의 서비스 에이전트에 부여됩니다.
아웃바운드 (CX Agent Studio에서 서드 파티로)	외부 엔드포인트 (예: ServiceNow 또는 Salesforce)	API 키 또는 OAuth	Secret Manager를 사용하여 관리됨	도구 실행 중에 삽입된 저장된 사용자 인증 정보입니다.

서비스 에이전트 ID

CX Agent Studio의 아웃바운드 요청은 CX Agent Studio 서비스 에이전트를 사용합니다.

service-PROJECT_NUMBER@gcp-sa-ces.iam.gserviceaccount.com

PROJECT_NUMBER를 Google Cloud 프로젝트 번호로 바꿉니다.

인바운드 인증

외부 애플리케이션, 맞춤 에이전트 또는 오케스트레이터가 CX Agent Studio를 호출하는 경우 Authorization 헤더에 유효한 Google 발급 OAuth 2.0 액세스 토큰을 전달해야 합니다.

테스트: 활성 계정의 임시 액세스 토큰을 생성합니다.
```
gcloud auth print-access-token
```
프로그래매틱 클라이언트: 애플리케이션 기본 사용자 인증 정보 (ADC)를 사용합니다.
```
gcloud auth application-default print-access-token
```
프로덕션: roles/ces.client (Customer Engagement Suite Client) 역할이 있는 전용 Google 서비스 계정을 사용합니다.

기본 요건

A2A 프로토콜 도구를 구성하기 전에 다음을 확인하세요.

프로젝트에서 Gemini Enterprise for Customer Experience API (ces.googleapis.com)를 사용 설정합니다.
```
gcloud services enable ces.googleapis.com --project=PROJECT_ID
```
호출 주 구성원 또는 서비스 계정에 Customer Engagement Suite Client 역할 (roles/ces.client)이 부여되었는지 확인합니다.

A2A 프로토콜 도구 구성

기본 에이전트를 외부 원격 에이전트에 연결하려면 다음 단계를 따르세요.

CX Agent Studio 콘솔을 엽니다.
프로젝트를 선택하고 에이전트 애플리케이션을 엽니다.
에이전트 빌더에서 도구 아이콘을 클릭합니다.
+ (추가) 버튼을 클릭하여 새 도구를 만듭니다.
A2A 프로토콜 도구 카드를 선택합니다.
UI 양식 또는 JSON 편집기를 사용하여 에이전트 카드를 구성합니다.
URL 필드에 원격 에이전트의 기본 엔드포인트 URL(예: https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID 또는 Cloud Run 서비스 URL)을 입력합니다. URL에 /message:send를 추가하지 마세요. CX Agent Studio에서 런타임에 자동으로 /message:send를 추가합니다.
엔드포인트에 적합한 인증 유형을 선택합니다.
만들기를 클릭합니다.

에이전트 카드 예

다음 샘플 JSON은 원격 날씨 에이전트의 에이전트 카드를 정의합니다.

{
  "name": "weather_agent",
  "description": "Agent capable of querying weather conditions and local time for given locations.",
  "version": "0.1.0",
  "supportedInterfaces": [
    {
      "url": "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ],
  "skills": [
    {
      "id": "get_weather",
      "name": "get_weather",
      "description": "Retrieves weather conditions for a specified location.",
      "tags": [
        "weather",
        "forecast"
      ],
      "examples": [],
      "inputModes": [],
      "outputModes": []
    },
    {
      "id": "get_current_time",
      "name": "get_current_time",
      "description": "Retrieves current local time for a specified city or timezone.",
      "tags": [
        "time",
        "clock"
      ],
      "examples": [],
      "inputModes": [],
      "outputModes": []
    }
  ]
}

라우팅 요청 사항 추가

기본 에이전트에게 A2A 도구에 위임해야 하는 시점을 안내합니다. 예를 들면 다음과 같습니다.

If the user asks for weather information or local time, use {@TOOL: weather_agent}.
Pass the city or location specified by the user.
If the tool returns an error, inform the user that weather details are temporarily unavailable.

인바운드 메시지

외부 시스템은 인바운드 A2A 메시지 엔드포인트를 사용하여 CX Agent Studio 에이전트 애플리케이션에 직접 메시지를 보낼 수 있습니다.

인바운드 엔드포인트 URL

다음 엔드포인트로 HTTP POST 요청을 보냅니다.

https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID/message:send

다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
LOCATION: 에이전트 애플리케이션을 호스팅하는 리전 (예: us-central1)입니다.
APP_ID: CX Agent Studio 에이전트 애플리케이션의 고유 식별자입니다.

요청 페이로드 스키마

인바운드 메시지를 전송하기 위한 JSON 페이로드 구조는 다음과 같습니다.

{
  "message": {
    "messageId": "msg-MY_UNIQUE_MESSAGE_UUID",
    "role": "ROLE_USER",
    "content": [
      {
        "text": "Hello! I would like help checking my account balance."
      }
    ],
    "metadata": {
      "gecx_a2a_agent_context": "MY_SERIALIZED_AGENT_CONTEXT_STRING"
    }
  }
}

참고: CX Agent Studio에서 메시지 페이로드는 content 필드를 사용하여 메시지 텍스트 부분을 포함합니다.

curl을 사용한 요청 예시

curl를 사용하여 인바운드 메시지를 테스트할 수 있습니다.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "messageId": "msg-'"$(uuidgen)"'",
      "role": "ROLE_USER",
      "content": [
        {
          "text": "Hello!"
        }
      ]
    }
  }' \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID/message:send"

컨텍스트 및 상태 관리

A2A 프로토콜은 AgentContext 메시지를 사용하여 에이전트 간 변수와 세션 상태를 관리합니다. 컨텍스트는 gecx_a2a_agent_context 키를 사용하여 SendMessageRequest의 메타데이터에 전달됩니다.

변수 매핑

작업을 위임할 때 기본 에이전트와 원격 에이전트 간에 변수를 매핑할 수 있습니다.

아웃바운드 매핑: RemoteAgentTool.input_variable_mapping는 원격 에이전트에 전송된 AgentContext.variables를 계산합니다.
인바운드 매핑: RemoteAgentTool.output_variable_mapping는 원격 에이전트가 응답할 때 기본 에이전트의 변수를 업데이트합니다.

인바운드 요청 (외부 클라이언트에서 CX Agent Studio로)의 경우 애플리케이션이 gecx_a2a_agent_context 메타데이터를 역직렬화하고 AgentContext.variables를 현재 세션에 직접 씁니다. 업데이트된 변수는 클라이언트에 응답할 때 AgentContext.variables에 다시 작성됩니다.

세션 종료

기본 에이전트는 AgentContext.session_metadata.closed를 모니터링하여 원격 세션이 종료되는 시점을 확인합니다.

아웃바운드 요청은 항상 closed를 false로 설정합니다. 원격 에이전트의 응답에서 closed을 true로 설정하면 A2A 연결이 종료됩니다.
클라이언트에 대한 인바운드 응답의 경우 세션이 종료되면 CX Agent Studio 앱이 closed을 true로 설정합니다.

스테이트풀 모드

CXAS 앱을 사용하는 원격 세션은 항상 상태 저장입니다. 기본 및 원격 CXAS 세션은 동일한 세션 ID를 공유하며 원격 세션은 기본 에이전트와 원격 에이전트 간의 대화 기록을 유지합니다.

서드 파티 시스템과의 원격 세션의 경우 원격 세션은 기본적으로 상태 비저장이며 원격 에이전트는 기본 에이전트로부터 각 메시지를 새 세션 (새 컨텍스트 ID)으로 수신합니다.

RemoteAgentTool.stateful_agent 필드를 사용 설정하여 원격 에이전트에서 반환된 첫 번째 컨텍스트 ID를 자동으로 캐시하고 재사용할 수 있습니다.

이 캐시된 컨텍스트 ID는 원격 에이전트가 AgentContext.session_metadata.closed == true로 응답하지 않는 한 세션의 나머지 부분에 사용됩니다. 세션이 닫히면 캐시가 재설정되고 다음 도구 호출에서 새 컨텍스트 ID가 캐시됩니다.

원격 하위 에이전트 배포

Google Cloud 서비스에 맞춤 원격 에이전트를 배포하여 CX Agent Studio의 하위 에이전트 역할을 할 수 있습니다.

Cloud Run에 배포

에이전트 개발 키트 (ADK)로 빌드된 에이전트를 Cloud Run에서 호스팅하려면 다음 단계를 따르세요.

에이전트 프로젝트 디렉터리에 Dockerfile을 만듭니다.

FROM python:3.11-slim

WORKDIR /app

COPY pyproject.toml requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
RUN pip install --no-cache-dir "google-adk[a2a]==1.32.0" "a2a-sdk[all]==0.3.26"

COPY . .

ENV PORT=8080
ENV PYTHONUNBUFFERED=1

EXPOSE 8080

CMD ["python", "-m", "app.a2a_rest_server"]

Cloud Run에 컨테이너를 배포합니다.

gcloud run deploy my-adk-agent \
  --project=PROJECT_ID \
  --region=us-central1 \
  --source=. \
  --memory=4Gi \
  --no-cpu-throttling

호출 프로젝트의 CX Agent Studio 서비스 에이전트에 Cloud Run 서비스에 대한 roles/run.invoker 역할을 부여합니다.
A2A 프로토콜 도구 구성의 단계에 따라 Cloud Run 서비스 URL을 CX Agent Studio에 연결합니다.

Vertex AI Agent Engine에 배포하기

Vertex AI Agent Engine에 ADK 에이전트를 배포하려면 다음 단계를 따르세요.

requirements.txt에서 종속 항목을 정의합니다.
```
a2a-sdk==0.3.26
google-adk[a2a]>=1.15.0,<2.0.0
```

Vertex AI SDK를 사용하여 엔진을 배포합니다.

import os
import sys
from google.protobuf import json_format
import vertexai
from vertexai.agent_engines import _agent_engines

sys.path.append("./")
from app.agent_runtime_app import agent_runtime

client = vertexai.Client(project="PROJECT_ID", location="us-central1")

ops = agent_runtime.register_operations()
class_methods_proto = _agent_engines._generate_class_methods_spec_or_raise(
    agent_engine=agent_runtime,
    operations=ops
)
class_methods_list = [
    json_format.MessageToDict(cm, preserving_proto_field_name=True)
    for cm in class_methods_proto
]

agent_config = {
    "entrypoint_module": "app.agent_runtime_app",
    "entrypoint_object": "agent_runtime",
    "source_packages": ["app", "requirements.txt"],
    "requirements_file": "requirements.txt",
    "class_methods": class_methods_list,
    "agent_framework": "google-adk",
    "env_vars": {
        "GOOGLE_CLOUD_LOCATION": "us-central1",
    },
    "min_instances": 1,
    "max_instances": 10,
    "resource_limits": {"cpu": "4", "memory": "8Gi"},
}

engine = client.agent_engines.create(config=agent_config)
print(f"Deployed Engine Resource Name: {engine.api_resource.name}")

호출 프로젝트의 CX Agent Studio 서비스 에이전트에 타겟 프로젝트의 roles/aiplatform.user 역할을 부여합니다.
A2A 프로토콜 도구 구성의 단계에 따라 Agent Engine 엔드포인트를 CX Agent Studio에 연결합니다.

서드 파티 엔드포인트에 연결

CX Agent Studio는 ServiceNow 또는 Salesforce와 같은 외부 서드 파티 엔드포인트에 작업을 위임할 수 있습니다.

콘솔에서 도구를 구성할 때는 다음을 참고하세요.

A2A 프로토콜 도구 구성의 단계를 따릅니다.
서드 파티 엔드포인트에 필요한 인증 방법(예: API 키 또는 OAuth)을 선택합니다.
Secret Manager를 사용하여 사용자 인증 정보를 안전하게 저장합니다.

A2A 프로토콜 도구와 에이전트의 도구 비교

CX Agent Studio는 멀티 에이전트 워크플로를 조정하는 여러 방법을 제공합니다.

기능	도구로서의 에이전트	A2A 프로토콜 도구
범위	애플리케이션 내 (동일한 CX Agent Studio 앱 내의 에이전트)	애플리케이션 간 (외부 에이전트, 원격 서비스 또는 서드 파티 플랫폼)
커뮤니케이션	직접 인메모리 / 내부 실행	A2A 메시지 표준을 사용하는 네트워크 HTTP 요청
사용 사례	세션을 핸드오프하지 않고 내부 하위 에이전트를 재사용합니다.	Cloud Run, Vertex AI 또는 외부 API에서 커스텀 ADK 에이전트를 호출합니다.
프로토콜	플랫폼 내부 도구 실행입니다.	REST를 통한 표준화된 A2A JSON 페이로드

LLM 도구 실행

내부적으로 A2A 프로토콜 호출은 표준 LLM 도구 호출을 통해 작동합니다.

A2A 도구가 에이전트에 할당되면 도구 설명과 스킬 정의가 함수 선언으로 모델에 제공됩니다.
모델이 하위 작업을 위임하기로 결정하면 함수 호출 이벤트를 생성합니다.
CX Agent Studio 런타임은 함수 호출을 가로채고, 매개변수를 A2A HTTP 요청으로 변환하여 구성된 원격 엔드포인트로 전송합니다.
원격 에이전트에서 반환된 대답은 대화 응답을 계속 생성하기 위해 모델에 다시 전달됩니다.

에이전트가 호출 가능한 도구로 캡슐화되는 방법을 자세히 알아보려면 GitHub의 ADK AgentTool 구현을 참고하세요.

A2A 프로토콜 도구 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

A2A 작동 방식

위임 모델

텍스트 기반 커뮤니케이션

형식 지원

결제

인증 및 액세스 제어

서비스 에이전트 ID

인바운드 인증

기본 요건

A2A 프로토콜 도구 구성

에이전트 카드 예

라우팅 요청 사항 추가

인바운드 메시지

인바운드 엔드포인트 URL

요청 페이로드 스키마

curl을 사용한 요청 예시

컨텍스트 및 상태 관리

변수 매핑

세션 종료

스테이트풀 모드

원격 하위 에이전트 배포

Cloud Run에 배포

Vertex AI Agent Engine에 배포하기

서드 파티 엔드포인트에 연결

A2A 프로토콜 도구와 에이전트의 도구 비교

LLM 도구 실행

A2A 프로토콜 도구