단계 3: Connectivity Agent 설정

이 단계에서는 A2A Connectivity Agent를 AWS ECS의 컨테이너화된 서비스로 배포하여 에이전트 간 통신의 기반을 구축합니다. 이 에이전트는 DNS, 연결성, 경로 분석 기능을 포함한 필수 네트워크 진단 기능을 제공합니다.

A2A Connectivity Agent 배포

workshop-module-3 디렉토리 내의 a2a-connectivity-agent 폴더로 이동합니다:

cd /workspace/workshop-module-3/a2a/a2a-connectivity-agent

A2A Connectivity Agent를 AWS ECS의 컨테이너화된 서비스로 배포합니다:

chmod +x deploy.sh && ./deploy.sh

🔍 이 스크립트는 무엇을 하나요?

deploy.sh는 배포 스크립트를 순차적으로 실행하는 wrapper입니다:

# deploy.sh의 핵심 부분
SCRIPTS=(
    "03-connect-service-to-alb.sh"
)

# 각 스크립트를 순서대로 실행
for script in "${SCRIPTS[@]}"; do
    if run_script "$script"; then
        ((success_count++))
    else
        log_error "Stopping deployment due to failure in: $script"
        break
    fi
done

실제 작업은 03-connect-service-to-alb.sh가 수행합니다:

# 03-connect-service-to-alb.sh의 주요 단계

# 1. module3-config.json에서 설정 로드
VPC_ID=$(jq -r '.vpc_id' "$CONFIG_FILE")
TARGET_GROUP_ARN=$(jq -r '.agentcore_troubleshooting.target_group_arn' "$CONFIG_FILE")
ALB_DNS_NAME=$(jq -r '.agentcore_troubleshooting.alb_dns' "$CONFIG_FILE")

# 2. ECS 서비스 보안 그룹 업데이트 (ALB만 접근 허용)
aws ec2 authorize-security-group-ingress \
  --group-id $ECS_SG_ID \
  --protocol tcp \
  --port 10003 \
  --source-group $ALB_SG_ID

# 3. ALB와 ECS의 가용 영역(AZ) 정렬
# ALB가 활성화된 AZ와 동일한 AZ에 있는 서브넷만 사용하도록 ECS 서비스 업데이트
aws ecs update-service \
  --cluster $CLUSTER_NAME \
  --service a2a-connectivity-agent-service \
  --network-configuration "awsvpcConfiguration={subnets=$ALB_COMPATIBLE_SUBNETS_ARRAY,...}"

# 4. 실행 중인 Task의 Private IP를 Target Group에 등록
TASK_IP=$(aws ecs describe-tasks ... --query "tasks[0].attachments[0].details[?name=='privateIPv4Address'].value")
aws elbv2 register-targets \
  --target-group-arn $TARGET_GROUP_ARN \
  --targets Id=$TASK_IP,Port=10003

# 5. 헬스체크 검증
curl -f "http://$ALB_DNS_NAME/health"

주요 작업:

1. 기존 ECS 클러스터(a2a-agents-cluster)의 Connectivity Agent 서비스를 ALB에 연결

2. Target Group 헬스체크 설정 및 서비스 등록

3. ALB 리스너 규칙으로 /connectivity/* 경로 라우팅 구성

4. A2A 프로토콜 엔드포인트(/.well-known/agent-card.json) 접근 가능하게 됨

A2A Connectivity 배포

이 단계는 완료하는 데 약 1-2분이 소요됩니다.

검증

모든 구성 요소가 제대로 작동하는지 확인하려면 다음 명령어를 실행합니다:

printf "=== Load Balancer Status ===\n" && \
aws elbv2 describe-load-balancers --names a2a-connectivity-alb \
  --query 'LoadBalancers[0].{Name:LoadBalancerName,State:State.Code}' && \
printf "\n=== ECS Cluster Status ===\n" && \
aws ecs describe-clusters --clusters a2a-agents-cluster \
  --query 'clusters[0].{Cluster:clusterName,Status:status,Services:activeServicesCount,Tasks:runningTasksCount}' && \
printf "\n=== Service Status ===\n" && \
aws ecs describe-services --cluster a2a-agents-cluster \
  --services a2a-connectivity-agent-service \
  --query 'services[0].{Service:serviceName,Status:status,Running:runningCount,Desired:desiredCount}'

A2A Connectivity 검증

Load Balancer State: active, Service Running: 1이면 배포 성공입니다.

선택 사항: 콘솔 기반 검증: ECS로 이동하여 a2a-agents-cluster를 확인함으로써 AWS 콘솔을 통해서도 배포를 확인할 수 있습니다.

코드 분석: Connectivity Agent

요청 흐름: 2개의 컨테이너와 Lambda 연결

Connectivity Agent 시스템은 2개의 서로 다른 컨테이너로 구성됩니다. 이 단계에서 배포하는 것은 ① A2A Server(ECS)이며, ② AgentCore Runtime(microVM)은 단계 1에서 확인한 사전 프로비저닝된 에이전트입니다.

① A2A Server (ECS) — 프로토콜 변환만 담당

이 단계에서 배포하는 ECS 컨테이너입니다. Lambda를 직접 호출하지 않습니다.

# a2a/a2a-connectivity-agent/agent_executer.py
class ConnectivityTroubleshootingAgentCoreExecutor(AgentExecutor):
    """A2A 프로토콜 → AgentCore Runtime HTTP 호출로 변환"""

    async def execute(self, context, event_queue):
        bearer = self._bearer()  # Cognito OAuth 토큰 획득

        # AgentCore Runtime API에 HTTP POST
        url = f"https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{agent_arn}/invocations"
        resp = self.http.post(url, json={"prompt": user_text}, headers=headers)

② AgentCore Runtime (microVM) — 에이전트 실행 + Lambda 호출

단계 1에서 확인한 a2a_troubleshooting_agent_runtime입니다. BedrockAgentCoreApp()으로 시작합니다.

# agentcore-connectivity-agent/main.py
app = BedrockAgentCoreApp()

@app.entrypoint
async def invoke(payload, context):
    # TroubleshootingAgent 생성 → 내부에서 MCP Gateway 연결
    agent_task(user_message=payload["prompt"], ...)

# agentcore-connectivity-agent/agent_config/agent.py
class TroubleshootingAgent:
    def __init__(self, bearer_token, ...):
        # MCP Gateway에 연결 → Lambda 도구 목록 로드
        gateway_url = get_ssm_parameter("/a2a/app/troubleshooting/agentcore/gateway_url")
        self.gateway_client = MCPClient(
            lambda: streamablehttp_client(gateway_url, headers={"Authorization": f"Bearer {bearer_token}"})
        )
        self.gateway_client.start()
        mcp_tools = self.gateway_client.list_tools_sync()  # Lambda 도구가 여기서 로드됨
        self.tools.extend(mcp_tools)

        # Strands Agent에 도구 등록 → LLM이 자율적으로 선택·호출
        self.agent = Agent(model=self.model, tools=self.tools, ...)

계층별 역할 정리

계층	코드	역할
A2A Server (ECS)	agent_executer.py	A2A 프로토콜 수신 → OAuth 토큰 획득 → AgentCore API 호출
AgentCore Runtime (microVM)	main.py → agent.py	BedrockAgentCoreApp으로 요청 수신 → TroubleshootingAgent 생성
MCP Gateway	AWS 관리형	MCPClient가 연결 → Lambda 도구 목록 제공 및 호출 중계
Lambda 도구	lambda-dns, lambda-fix	dns-resolve (DNS 해석), connectivity (VPC 경로 분석 및 보안 그룹 수정)

핵심 포인트: ECS의 A2A Server는 프로토콜 변환기일 뿐, Lambda를 직접 호출하지 않습니다. Lambda 호출은 AgentCore Runtime 안의 TroubleshootingAgent가 MCP Gateway를 통해 수행합니다. 이 구조 덕분에 A2A 프로토콜 계층과 에이전트 로직이 완전히 분리됩니다.

아래에서는 Connectivity Agent의 시스템 프롬프트와 Agent Card를 살펴봅니다.

Connectivity Agent 시스템 프롬프트 (동의 기반 워크플로우)

# agentcore-connectivity-agent/agent_config/agent.py
system_prompt = """
You are a Troubleshooting Agent with DNS resolution and connectivity analysis capabilities.

## SPECIFIC WORKFLOW FOR CONNECTIVITY REQUESTS:

### Scenario 1: "Check connectivity" → 즉시 도구 호출
1. dns-resolve → 호스트명을 인스턴스 ID로 변환
2. connectivity(action="check") → VPC Reachability Analyzer 실행
3. 결과 보고

### Scenario 2: "Fix connectivity" → 반드시 동의 먼저
- CRITICAL: 도구 호출 금지, 먼저 동의 요청
- "보안 그룹을 수정해도 될까요?" 라고 물어야 함

### Scenario 3: 사용자 동의 후 → 즉시 수정
1. dns-resolve → connectivity(action="fix") → connectivity(action="check") 검증
"""

A2A Agent Card 설정 (config.yaml)

# a2a-connectivity-agent/config.yaml
agent_metadata:
  name: Connectivity_Troubleshooting_Agent
  description: "DNS resolution and connectivity analysis"
  capabilities:
    push_notifications: true
    streaming: true
  version: 1.0.0

agent_skills:
  - id: dns_connectivity_troubleshooting
    name: "DNS Resolution and Connectivity Troubleshooting"
    tags: [dns-resolution, connectivity-analysis, security-groups]

server:
  default_port: 10003

Agent Card (필수): A2A 프로토콜에서 에이전트의 "명함" 역할을 하는 필수 구성 요소입니다.

• 표준 경로: /.well-known/agent-card.json (A2A 프로토콜 표준)

• 역할: Collaborator Agent가 이를 조회하여 어떤 에이전트에게 어떤 요청을 보낼지 결정

• 필수 정보:

  • agent_metadata: 이름, 설명, 버전, 능력(capabilities)

  • agent_skills: 에이전트가 수행할 수 있는 작업 목록과 태그

Agent Card가 없으면 Collaborator Agent가 해당 에이전트를 발견하거나 사용할 수 없습니다.

이 단계가 완료되었습니다. 다음 단계로 진행하세요.