Apigee 확장 프로그램 프로세서를 Agent Gateway에 연결

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

이 페이지에서는 Apigee 확장 프로그램 프로세서를 Agent Gateway에 연결하여 AI 에이전트가 모델, 도구, 사용하는 모델 컨텍스트 프로토콜 (MCP) 서버에 대해 호출할 때 에이전트를 변경하지 않고 Apigee 정책이 적용되도록 하는 방법을 설명합니다.

Agent Gateway는 에이전트 트래픽의 네트워크 진입점 및 종료점입니다. 부하 분산기가 아니므로 트래픽 확장 프로그램을 사용하지 않습니다. 대신 게이트웨이는 승인 확장 프로그램에 승인을 위임하고 확장 프로그램 프로세서를 해당 확장 프로그램으로 구성합니다. 연결되면 게이트웨이는 각 에이전트 요청과 응답을 Apigee로 전송하여 처리하고 Apigee는 평결을 반환합니다.

다음 그림은 이 페이지에서 만드는 리소스와 단일 에이전트 요청이 이러한 리소스를 통과하는 경로를 보여줍니다.

그림 1. Apigee 확장 프로그램 프로세서가 Agent Gateway의 승인 확장 프로그램인 경우의 구성요소 및 요청 흐름

그림 1에서 요청은 다음과 같이 처리됩니다.

1. 에이전트가 모델, 도구 또는 MCP 서버에 일반 HTTPS 요청을 합니다. 에이전트는 생성될 때 게이트웨이에 바인딩되며 변경할 필요가 없습니다.
2. 게이트웨이는 요청을 보류하고 승인 확장 프로그램을 호출하여 결정을 요청합니다.
3. 콜아웃은 네트워크 연결을 통해 나가므로 VPC 네트워크 내에서 시작됩니다.
4. 비공개 DNS 영역은 콜아웃 호스트 이름을 Private Service Connect 엔드포인트의 내부 IP 주소로 확인합니다.
5. 엔드포인트는 콜아웃을 Apigee 인스턴스의 서비스 연결로 전달합니다.
6. 환경 그룹은 호스트 이름별로 콜아웃을 타겟이 없는 프록시로 라우팅하며, 여기서 정책이 실행됩니다.
7. 프록시가 게이트웨이에 확인 결과를 반환합니다. Apigee는 에이전트의 트래픽을 전달하지 않습니다. 프록시에 타겟이 없기 때문입니다.
8. 판정에서 요청을 허용하는 경우 게이트웨이는 원래 요청을 대상에 전송합니다.

그림 1의 AuthzPolicy 및 AuthzExtension은 트래픽이 아닌 구성입니다. 정책은 확장 프로그램을 게이트웨이에 연결하고 확장 프로그램은 실행되는 확장 프로그램 프로세서 프록시의 이름을 지정합니다. 이러한 인증 키와 프로필은 승인 확장 프로그램 구성에서 만들 수 있습니다.

확장 프로그램 프로세서를 부하 분산기에 연결하려면 Apigee 확장 프로그램 프로세서 시작하기를 참고하세요.

다음 섹션에서는 단계를 안내합니다.

• Apigee 확장 프로그램 프로세서를 구성합니다.
• Agent Gateway를 Apigee에 연결
• 승인 확장 프로그램을 구성합니다.
• 연결을 확인합니다.

시작하기 전에

시작하기 전에 다음 작업을 완료하세요.

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. Verify that billing is enabled for your Google Cloud project.

3. Enable the Apigee, Compute Engine, Network Services, Network Security, and Cloud DNS APIs.

   Roles required to enable APIs

   To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

   Enable the APIs

4. Google Cloud CLI 설치

   Google Cloud CLI를 설치한 후 gcloud components update 명령어를 실행하여 최신 gcloud 구성요소를 가져옵니다.

5. 아직 수행하지 않은 경우 Apigee 인스턴스를 프로비저닝합니다.

   Google Cloud 콘솔에서 Apigee 인스턴스 페이지로 이동합니다.

   Apigee 인스턴스로 이동

6. 게이트웨이가 에이전트의 아웃바운드 트래픽을 관리하도록 governedAccessPath이 AGENT_TO_ANYWHERE로 설정된 상태로 Apigee 인스턴스와 동일한 리전에 Agent Gateway를 배포합니다. 자세한 내용은 Agent Gateway 구성을 참고하세요.

   DNS 영역이 생성된 후 Agent Gateway 업데이트에서 이 게이트웨이의 네트워크 구성을 업데이트합니다.

7. 에이전트 게이트웨이와 Private Service Connect 엔드포인트가 모두 사용할 수 있는 VPC와 서브넷이 있는지 확인합니다.

   VPC 네트워크로 이동

필요한 역할

Apigee 확장 프로그램 프로세서를 에이전트 게이트웨이에 연결하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

• Apigee 리소스 생성 및 관리: 조직의 Apigee 조직 관리자 (roles/apigee.admin)
• 서비스 확장 프로그램 생성 및 관리: 서비스 확장 프로그램 관리자 (roles/networkservices.serviceExtensionsAdmin) 조직
• 승인 정책 만들기 및 관리: 조직의 네트워크 보안 관리자 (roles/networksecurity.admin)
• Private Service Connect 엔드포인트 및 DNS를 비롯한 네트워킹 리소스 만들기 및 관리: 조직의 Compute 네트워크 관리자 (roles/compute.networkAdmin)

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

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

환경 변수 설정하기

시작하기 전에 만든 리소스를 식별하도록 다음 환경 변수를 설정합니다. 이 페이지의 각 후속 섹션에서는 명명된 리소스를 만드는 시점에 필요한 추가 변수를 정의합니다.

export PROJECT_ID=PROJECT_ID
export ORG_NAME=$PROJECT_ID
export REGION=REGION
export INSTANCE=INSTANCE
export VPC_NETWORK_NAME=VPC_NETWORK_NAME
export SUBNET=SUBNET
export GATEWAY=GATEWAY

각 항목의 의미는 다음과 같습니다.

• PROJECT_ID는 Apigee 인스턴스가 포함된 프로젝트의 ID입니다.
• REGION은 Apigee 인스턴스의 Google Cloud 리전입니다.
• INSTANCE은 Apigee 인스턴스의 이름입니다.
• VPC_NETWORK_NAME 및 SUBNET은 Agent Gateway와 Private Service Connect 엔드포인트가 사용하는 VPC 네트워크 및 서브넷입니다.
• GATEWAY은 배포한 Agent Gateway의 이름입니다.

환경 변수가 올바르게 설정되었는지 확인하려면 다음 명령어를 실행하고 출력을 검토합니다.

echo $PROJECT_ID $ORG_NAME $REGION $INSTANCE $VPC_NETWORK_NAME $SUBNET $GATEWAY

콜아웃 호스트 이름 선택

게이트웨이는 사용자가 선택한 비공개 호스트 이름으로 Apigee에 연결됩니다. 첫 번째 리소스인 Apigee 환경 그룹이 이를 호스트 이름으로 사용하지만 이를 확인하는 DNS 영역은 비공개 DNS 영역 만들기 전까지는 생성되지 않으므로 지금 아무것도 만들기 전에 선택합니다.

export DNS_DOMAIN=DNS_DOMAIN
export EXTPROC_HOST=apigee-extproc.$DNS_DOMAIN

여기서 DNS_DOMAIN은 공개 인터넷에서 확인할 필요가 없는 비공개 DNS 도메인이며, 예를 들어 internal.example.com와 같이 후행 점 없이 작성됩니다. 그러면 apigee-extproc.internal.example.com의 EXTPROC_HOST가 제공됩니다. 호스트 이름이 DNS_DOMAIN 내에 유지되는 한 apigee-extproc 이외의 라벨을 사용할 수 있습니다.

중요: EXTPROC_HOST는 Apigee 환경 그룹 호스트 이름, 비공개 DNS 레코드, 승인 확장 프로그램의 authority 및 service 필드 등 세 곳에서 사용됩니다. 세 가지가 모두 동일해야 합니다. 그렇지 않으면 콜아웃이 Apigee에 도달하지 않습니다. 호스트 이름도 DNS_DOMAIN 내에 있어야 하므로 위의 명령어는 해당 변수에서 호스트 이름을 파생시킵니다.

인증 토큰 구성

export TOKEN=$(gcloud auth print-access-token)
echo $TOKEN

참고: 조직에서 데이터 상주를 사용하는 경우 이 페이지의 명령어에서 apigee.googleapis.com을 조직의 리전 엔드포인트로 바꾸세요. 자세한 내용은 데이터 레지던시를 위해 리전 엔드포인트 사용을 참고하세요.

Apigee 확장 프로그램 프로세서 구성

이 섹션에서 만드는 Apigee 리소스의 이름을 지정합니다.

export EXTPROC_ENV=EXTPROC_ENV
export EXTPROC_ENVGROUP=EXTPROC_ENVGROUP
export PROXY_NAME=PROXY_NAME

각 항목의 의미는 다음과 같습니다.

• EXTPROC_ENV 및 EXTPROC_ENVGROUP은 확장 프로그램 프로세서 전용 Apigee 환경 및 환경 그룹에 대해 선택하는 이름입니다(예: extproc-env 및 extproc-envgroup). 각 이름은 소문자, 숫자 또는 하이픈으로 구성된 2~32자여야 하며, 문자로 시작해야 하고 하이픈으로 끝나면 안 됩니다. 환경 이름은 조직의 다른 모든 환경 이름과 달라야 합니다.
• PROXY_NAME은 확장 프로그램 프로세서 프록시에 대해 선택한 이름입니다(예: extproc-authz).

구성의 Apigee 측면은 부하 분산기와 동일합니다. 빠른 시작의 Apigee 확장 프로그램 프로세서 구성에 따라 다음 작업을 실행합니다.

1. apigee-service-extension-enabled 속성이 true로 설정된 Apigee 환경을 만들고 인스턴스에 연결한 다음 호스트 이름이 $EXTPROC_HOST인 환경 그룹을 만듭니다.
2. 해당 환경에 타겟 없음 확장 프로그램 프로세서 프록시를 만들고 배포합니다.

참고: 빠른 시작에서는 이러한 리소스의 이름을 ENV_NAME, ENV_GROUP_NAME, ENV_GROUP_HOSTNAME로 지정합니다. 각각 $EXTPROC_ENV, $EXTPROC_ENVGROUP, $EXTPROC_HOST를 사용합니다.

참고: 프록시의 정책이 Google Cloud API를 호출하는 경우 배포 요청에 ?serviceAccount=SERVICE_ACCOUNT_EMAIL를 추가하여 서비스 계정으로 프록시를 배포하세요. 그렇지 않으면 MISSING_SERVICE_ACCOUNT와 함께 배포가 실패합니다.

그런 다음 환경의 배포를 나열합니다.

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments/$EXTPROC_ENV/deployments"

환경에 배포된 프록시가 두 개 이상 있을 수 있으므로 응답에서 apiProxy이 $PROXY_NAME인 항목을 찾아 revision을 기록합니다.

Google Cloud 콘솔에서 프록시를 검토할 수 있습니다.

API 프록시로 이동

연결 확인에 필요한 해당 버전으로 다음 변수를 설정합니다.

export REVISION=REVISION

Agent Gateway를 Apigee에 연결

게이트웨이는 비공개 DNS 영역에서 $EXTPROC_HOST를 확인하여 찾은 VPC의 Private Service Connect 엔드포인트를 통해 Apigee에 연결됩니다.

서비스 연결 찾기

Apigee 인스턴스의 서비스 연결을 찾습니다.

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances"

다음 변수를 해당 지역의 인스턴스 serviceAttachment 값으로 설정합니다.

export SERVICE_ATTACHMENT=SERVICE_ATTACHMENT

네트워크 연결 만들기

에이전트 게이트웨이는 네트워크 연결을 통해 VPC로 이그레스됩니다. 이름(예: agent-gateway-attachment)을 선택하고 만듭니다.

export NETWORK_ATTACHMENT=NETWORK_ATTACHMENT
gcloud compute network-attachments create $NETWORK_ATTACHMENT \
    --region=$REGION --subnets=$SUBNET --connection-preference=ACCEPT_AUTOMATIC

Private Service Connect 엔드포인트 만들기

내부 IP 주소를 예약하고 Private Service Connect 엔드포인트를 만듭니다.

gcloud compute addresses create apigee-extproc-psc-ip \
    --region=$REGION --subnet=$SUBNET --purpose=GCE_ENDPOINT
gcloud compute forwarding-rules create apigee-extproc-psc-endpoint \
    --region=$REGION --network=$VPC_NETWORK_NAME \
    --address=apigee-extproc-psc-ip \
    --target-service-attachment=$SERVICE_ATTACHMENT

Google Cloud 콘솔에서 Private Service Connect 페이지로 이동합니다.

Private Service Connect로 이동

엔드포인트가 pscConnectionStatus: ACCEPTED를 보고하는지 확인하고 다음 변수를 IP 주소로 설정합니다.

gcloud compute forwarding-rules describe apigee-extproc-psc-endpoint \
    --region=$REGION --format="value(pscConnectionStatus,IPAddress)"
export PSC_IP=PSC_IP

상태가 PENDING이면 프로젝트가 Apigee 인스턴스의 consumerAcceptList에 없으므로 연결을 수락할 수 없습니다.

비공개 DNS 영역 만들기

$DNS_DOMAIN의 비공개 DNS 영역과 $EXTPROC_HOST를 엔드포인트의 IP 주소로 확인하는 A 레코드를 만듭니다.

gcloud dns managed-zones create extproc-zone \
    --dns-name=$DNS_DOMAIN. --visibility=private --networks=$VPC_NETWORK_NAME \
    --description="Apigee extension processor callout host"
gcloud dns record-sets create $EXTPROC_HOST. --type=A --ttl=300 \
    --rrdatas=$PSC_IP --zone=extproc-zone

에이전트 게이트웨이 업데이트

시작하기 전에서 에이전트 게이트웨이를 업데이트하여 네트워크 연결을 통해 이그레스하고 생성한 영역을 확인할 수 있도록 합니다.

주의: Agent Gateway를 가져오면 전체 리소스가 대체됩니다. 항상 내보낸 구성에서 시작하여 수정하세요. 새 파일을 작성하면 protocols 및 registries와 같이 생략한 필드가 게이트웨이에서 삭제됩니다.

1. 현재 구성을 내보냅니다.

   gcloud network-services agent-gateways export $GATEWAY \
       --location=$REGION --destination=agent-gateway.yaml

2. agent-gateway.yaml에서 다음 networkConfig 블록을 추가하고 각 자리표시자를 해당 환경 변수의 값으로 바꿉니다. 파일이 직접 수정되므로 여기서는 셸 변수가 대체되지 않습니다.

   networkConfig:
     egress:
       networkAttachment: projects/PROJECT_ID/regions/REGION/networkAttachments/NETWORK_ATTACHMENT
     dnsPeeringConfig:
       domains: [ DNS_DOMAIN. ]
       targetProject: PROJECT_ID
       targetNetwork: projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME

   googleManaged.governedAccessPath, protocols, registries를 포함한 나머지 파일은 내보낸 대로 둡니다.

3. 수정된 구성을 가져옵니다.

   gcloud network-services agent-gateways import $GATEWAY \
       --location=$REGION --source=agent-gateway.yaml

전체 에이전트 게이트웨이 필드는 에이전트 게이트웨이 구성을 참고하세요.

승인 확장 프로그램 구성

게이트웨이를 확장 프로그램 프로세서 프록시에 연결하는 두 가지 리소스가 있습니다. 하나는 Apigee를 가리키는 승인 확장 프로그램이고 다른 하나는 확장 프로그램을 게이트웨이에 연결하는 승인 정책입니다.

승인 확장 프로그램 만들기

승인 확장 프로그램의 이름을 선택합니다(예: apigee-authz-extension). metadata 필드는 실행할 Apigee 프록시와 메시지 본문을 프록시에 전송할지 여부를 선택합니다.

export AUTHZ_EXT=AUTHZ_EXT
cat > authz-extension.yaml <<EOF
name: projects/$PROJECT_ID/locations/$REGION/authzExtensions/$AUTHZ_EXT
authority: $EXTPROC_HOST
service: $EXTPROC_HOST
timeout: 5s
metadata:
  apigee-extension-processor: $PROXY_NAME
  apigee-request-body: 'true'
  apigee-response-body: 'true'
EOF
gcloud service-extensions authz-extensions import $AUTHZ_EXT \
    --source=authz-extension.yaml --location=$REGION

각 항목의 의미는 다음과 같습니다.

• apigee-extension-processor는 트래픽을 처리하는 확장 프로그램 프로세서 프록시를 선택합니다.
• apigee-request-body 및 apigee-response-body는 요청 및 응답 본문을 프록시에서 request.content 및 response.content로 사용할 수 있도록 합니다. 이러한 필드가 없으면 페이로드를 검사하는 정책에서 아무것도 찾지 못합니다.

승인 정책 만들기

승인 정책의 이름을 선택합니다(예: apigee-content-authz-policy). 이 정책은 확장 프로그램을 게이트웨이에 연결하고 Apigee로 전송되는 트래픽을 결정합니다.

export AUTHZ_POLICY=AUTHZ_POLICY
cat > authz-policy.yaml <<EOF
name: projects/$PROJECT_ID/locations/$REGION/authzPolicies/$AUTHZ_POLICY
action: CUSTOM
policyProfile: CONTENT_AUTHZ
customProvider:
  authzExtension:
    resources:
    - projects/$PROJECT_ID/locations/$REGION/authzExtensions/$AUTHZ_EXT
httpRules:
- to:
    operations:
    - paths:
      - prefix: "/"
target:
  resources:
  - projects/$PROJECT_ID/locations/$REGION/agentGateways/$GATEWAY
EOF
gcloud beta network-security authz-policies import $AUTHZ_POLICY \
    --source=authz-policy.yaml --location=$REGION

메시지 본문을 검사할 수 있도록 policyProfile: CONTENT_AUTHZ를 사용합니다. REQUEST_AUTHZ 정책은 요청 헤더만 평가합니다.

중요: 위의 예에서는 모든 요청을 prefix: "/"와 일치시켜 세션, 원격 분석, 도구 호출을 비롯한 모든 에이전트 트래픽을 Apigee로 전송합니다. to.operations.paths 또는 when 필드의 Common Expression Language(CEL) 표현식을 사용하여 범위를 좁혀 관리하려는 트래픽만 처리되도록 합니다.

연결 확인하기

트래픽을 생성하려면 이 게이트웨이에서 이그레스를 관리하는 에이전트가 필요합니다. 에이전트는 에이전트 게이트웨이 구성을 $GATEWAY로 설정하여 에이전트가 생성될 때 게이트웨이에 바인딩됩니다. 게이트웨이에 대한 직접 HTTP 요청으로 연결을 실행할 수 없습니다. 자세한 내용은 Agent Gateway 구성을 참고하세요.

확장 프로그램 프로세서 프록시에서 Apigee 디버그 세션을 시작한 다음 에이전트를 통해 요청 하나를 보냅니다.

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments/$EXTPROC_ENV/apis/$PROXY_NAME/revisions/$REVISION/debugsessions?timeout=600" \
  -d '{"count":15,"tracesize":5120,"filter":"(request.uri Like \"*generateContent*\")"}'

참고: 에이전트의 세션과 원격 분석 호출도 게이트웨이를 통과하므로 단일 에이전트 턴에서 여러 트랜잭션이 생성됩니다. filter 필드를 사용하여 검사하려는 트래픽만 캡처하세요. 그렇지 않으면 원하는 요청이 도착하기 전에 버퍼가 채워질 수 있습니다.

캡처된 거래에서 다음을 확인합니다.

• 요청 URL은 Apigee 기본 경로가 아닌 모델 엔드포인트나 도구 호스트와 같이 에이전트가 호출한 주소입니다.
• request.content 및 response.content이 채워지며, 이는 승인 확장 프로그램의 본문 메타데이터가 작동함을 확인해 줍니다.

거래가 표시되지 않으면 환경 그룹 호스트 이름, DNS 레코드, 확장 프로그램의 authority 및 service 필드가 모두 $EXTPROC_HOST이고 Private Service Connect 엔드포인트가 ACCEPTED를 보고하며 게이트웨이의 governedAccessPath이 AGENT_TO_ANYWHERE인지 확인합니다.

다음 단계

• Apigee 확장 프로그램 프로세서 개요를 읽어보세요.
• 부하 분산기에서 Apigee 확장 프로그램 프로세서를 시작합니다.