이 페이지의 일부 또는 모든 정보는 S3NS의 Cloud de Confiance에 적용되지 않을 수 있습니다. 자세한 내용은 Google Cloud와의 차이점을 참조하세요.

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

Agent Gateway 연결 문제 해결

이 가이드에서는 특히 Gemini Enterprise Agent Platform과 함께 Agent Gateway, 에이전트 ID, ID 및 액세스 관리 (IAM) 정책, 서비스 확장 프로그램의 위임된 승인을 사용할 때 Gemini Enterprise Agent Platform의 연결 문제를 디버그하고 해결하는 방법을 설명합니다.

Agent Platform 문제 해결 스킬을 사용하여 문제 해결

AI 코딩 어시스턴트와 대화식으로 연결, 승인, 시작 문제를 진단하려면 Cloud de Confiance by S3NS 에이전트 기술 저장소에서 agent-platform-troubleshooting 기술을 설치하면 됩니다.

이 스킬은 AI 에이전트가 다음과 같은 에이전트 플랫폼 스택 전반에서 도메인별 진단 플레이북, 로그 필터, 해결 단계를 갖추도록 지원합니다.

에이전트 게이트웨이 이그레스 거부: 게이트웨이에서 차단된 403 Forbidden 오류를 진단하고 IAP 승인 결정을 확인합니다.
에이전트 런타임 시작 실패: 누락된 역할 (예: roles/browser 또는 resourcemanager.projects.get) 및 부트스트랩 예외를 식별합니다.
에이전트 레지스트리 대상 문제: 서비스 항목, 엔드포인트 인터페이스, 통합 Google API 구성을 확인합니다.
IAM 액세스 정책: 통합 액세스 정책(UAP) 바인딩, 조건 표현식, 보안 주체 액세스 경계 (PAB) 범위를 검증합니다.
컨테이너 신뢰: 맞춤 컨테이너 (BYOC) 또는 비공개 인증 기관 (CA)의 TLS 인증서 및 핸드셰이크 오류를 진단합니다.

에이전트 환경에 기술을 설치하려면 다음 명령어를 실행합니다.

npx skills add https://github.com/google/skills --skill agent-platform-troubleshooting

이그레스 요청 흐름

Agent Platform은 모든 발신 트래픽에 default-deny 정책을 채택합니다. 에이전트가 외부 리소스에 연결하려면 모든 네트워크 및 ID 레이어에서 액세스를 명시적으로 허용해야 합니다. Agent Gateway가 사용 설정되면 게이트웨이가 에이전트의 모든 요청을 가로채고 구성된 정책을 적용합니다.

요청이 성공하려면 다음 조건을 모두 충족해야 합니다.

IAM 액세스 정책: 에이전트에 할당된 에이전트 ID에 대상 리소스에 대한 iap.resources.egressViaIAP 권한이 직접 또는 주 구성원 집합을 통해 부여되어야 합니다. 자세한 내용은 IAM 에이전트 정책 만들기를 참조하세요. IAP 정책 문제 해결 방법을 알아보세요.
Agent Registry: 세분화된 리소스별 액세스 정책과 도구 수준 제어를 적용하려면 Agent Registry에 대상을 등록하는 것이 좋습니다. 에이전트가 등록되지 않은 대상에 도달하려고 하는 경우 등록되지 않은 엔드포인트의 정책을 구성하여 에이전트 ID에 iap.resources.egressViaIAP 권한을 부여해야 합니다.
Agent Gateway: 게이트웨이는 명시적으로 게이트웨이를 타겟팅하는 승인 정책과 연결되어야 합니다. 기본적으로 게이트웨이는 IAP와 Model Armor를 사용하여 요청을 보호합니다.
서비스 확장 프로그램을 사용한 위임된 승인: 서비스 확장 프로그램을 사용하여 승인 결정을 커스텀 승인 엔진에 위임할 수 있습니다. 구성된 승인 정책에 따라 이러한 승인 엔진 중 하나 이상이 요청을 허용하거나 거부합니다.

일반적인 문제

Agent Gateway 문제를 해결할 때 다음 일반적인 문제와 해결 방법을 검토하세요.

Agent Runtime 시작 중 오류

에이전트 런타임 인스턴스가 시작되거나 배포되지 않으면 IAP가 내부 트래픽을 차단하거나 에이전트에 초기화에 필요한 기본 역할이 없다는 의미일 수 있습니다.

IAP가 내부 서비스 호출을 차단하지 않는지 확인

증상: 시작 중 403 Forbidden 오류

원인: Agent Gateway는 모든 트래픽에 기본 거부 정책을 사용합니다. 따라서 IAP가 시행 모드에 있으면 등록되지 않고 에이전트에 필요한 IAM 권한이 없는 한 내부 서비스 (예: aiplatform 또는 logging)에 대한 호출도 차단합니다.

해결 방법: IAP를 테스트 실행 모드로 일시적으로 전환하여 시작을 차단하지 않고 실패하는 연결을 확인하거나 Cloud Logging을 쿼리하여 정확한 차단된 호스트 이름을 식별합니다. 타겟 서비스 호스트 이름을 식별한 후 에이전트 레지스트리에 등록하고 에이전트에 iap.resources.egressViaIAP 권한을 부여합니다.

Cloud Logging을 사용하여 차단된 특정 호스트 이름을 찾으려면 로그 탐색기에서 다음 쿼리를 실행하세요.
```
resource.type="networkservices.googleapis.com/Gateway"
resource.labels.gateway_type="SECURE_WEB_GATEWAY"
httpRequest.status=403
```
결과의 httpRequest.requestUrl 또는 jsonPayload.authzPolicyInfo 필드를 검사하여 대상 호스트 이름을 찾습니다.

시작 중에 등록이 필요할 수 있는 일반적인 내부 서비스는 다음과 같습니다.
- Agent Platform (추론 엔진 및 세션): https://REGION-aiplatform.mtls.googleapis.com
- Resource Manager: https://cloudresourcemanager.mtls.googleapis.com 및 https://cloudresourcemanager.mtls.googleapis.com/
- Google Cloud Observability (사용 설정된 경우): https://telemetry.mtls.googleapis.com/
- Cloud Logging (사용 설정된 경우): https://logging.googleapis.com/
- Cloud Monitoring: https://monitoring.googleapis.com/ 및 https://monitoring.mtls.googleapis.com/
- Cloud Trace: https://cloudtrace.googleapis.com/ 및 https://cloudtrace.mtls.googleapis.com/
- Secret Manager: https://secretmanager.googleapis.com/ 및 https://secretmanager.mtls.googleapis.com/
에이전트 ID에 필요한 기본 역할이 있는지 확인

증상: aiplatform.googleapis.com/reasoning_engine_stderr 로그에 google.api_core.exceptions.Unknown: None 또는 Failed to convert project number to project ID와 같은 오류가 표시됩니다. Reasoning Engine 시작 중에 오류가 표시됩니다.

원인 에이전트 ID에 초기화 중에 프로젝트 이름을 확인하는 데 필요한 resourcemanager.projects.get 권한이 없습니다.

수정 에이전트 ID (또는 해당 주 구성원 집합)에 자체 런타임 구성을 읽는 데 필요한 권한이 있는지 확인합니다. 다음 역할이 필요합니다.
- roles/aiplatform.agentDefaultAccess: 기본 에이전트 역할입니다.
- roles/aiplatform.user: 에이전트를 실행하는 데 필요합니다.
- roles/agentregistry.viewer: 등록된 리소스를 보는 데 필요합니다.
- roles/logging.logWriter 및 roles/monitoring.metricWriter: 관측 가능성에 필요합니다.
- roles/browser: SDK 초기화 중에 resourcemanager.projects.get을 실행해야 합니다.
에이전트 ID에 할당된 역할을 확인하려면 다음 명령어를 실행합니다.
```
gcloud projects get-iam-policy PROJECT_ID \
--flatten="bindings[].members" \
--filter="bindings.members:AGENT_IDENTITY_PRINCIPAL"
```
다음을 바꿉니다.
- PROJECT_ID: Cloud de Confiance 프로젝트 ID입니다.
- AGENT_IDENTITY_PRINCIPAL: 에이전트 ID 주 구성원입니다. principal://TRUST_DOMAIN/resources/SERVICE/RESOURCE_PATH 형식을 사용합니다.
역할을 부여하는 방법은 Agent Runtime에서 에이전트 아이덴티티 사용을 참조하세요.

오류 `403 Forbidden`개

403 Forbidden 오류가 발생하면 Agent Gateway 이그레스와 관련이 있는지 확인합니다. 다음은 샘플 이그레스 오류 메시지입니다.

{"code": 403, "message": "403 Forbidden. {'message': 'Egress request is not authorized.', 'status': 'Forbidden'}"}

Logging에서 에이전트 로그를 쿼리하여 실패한 특정 호출을 찾습니다.

resource.type="aiplatform.googleapis.com/ReasoningEngine"
resource.labels.location="LOCATION"
resource.labels.reasoning_engine_id="AGENT_ID"
textPayload:"403"

다음을 바꿉니다.

LOCATION: 에이전트가 배포된 리전입니다(예: us-central1).
AGENT_ID: 에이전트 (추론 엔진)의 ID입니다.

로그 항목의 textPayload에서 Egress request is not authorized 메시지를 찾습니다. 403 오류에 다른 텍스트가 포함된 경우 Agent Gateway가 아닌 대상 서비스에서 호출을 직접 거부하는 것일 수 있습니다.

기본 제공 관측 가능성 대시보드를 사용하여 403 거부를 비롯한 이그레스 트래픽 로그를 볼 수도 있습니다.

자체 서명 또는 비공개 CA 대상에 연결할 수 없음

증상: 에이전트가 자체 서명 또는 비공개 CA 발급 인증서를 제공하는 대상에 연결할 수 없습니다.
원인: 기본적으로 Agent Gateway는 공개적으로 신뢰할 수 있는 CA에서 발급한 인증서만 신뢰합니다. 비공개 CA 또는 자체 서명 인증서를 사용하는 대상에 연결하려면 추가 구성이 필요합니다.
완화: 비공개 CA 또는 자체 서명 인증서를 사용하여 대상에 연결하려면 에이전트 연결 템플릿에서 tlsConfig 설정을 사용하여 맞춤 TLS 신뢰 앵커를 구성해야 합니다.

맞춤 컨테이너 (BYOC)로 배포된 에이전트가 Agent Gateway에 연결되지 않음

증상: BYOC 에이전트가 Agent Gateway를 통해 라우팅될 때 연결을 설정하지 못합니다. 로그에 TLS 핸드셰이크 또는 인증서 확인 오류가 표시될 수 있습니다.
원인: 에이전트의 커스텀 컨테이너가 Agent Gateway의 인증 기관을 신뢰하지 않습니다.
해결: Agent Gateway의 루트 인증서를 컨테이너의 CA 저장소에 추가했는지 확인합니다. Agent Gateway용 커스텀 컨테이너(BYOC) 에이전트 구성을 참조하세요.

정책 바인딩이 실패하거나 거버넌스 거부를 모방함

증상: 정책 바인딩 구성이 실패하거나, 정책을 바인딩할 때 etag를 입력하라는 메시지가 대화형으로 표시되거나, 잘못된 거버넌스 거부 오류 (예: '등록되지 않은 대상이 올바르게 거부됨')와 함께 요청이 실패합니다.
원인: 프로젝트에서 Identity-Aware Proxy API (iap.googleapis.com)가 사용 중지되어 있습니다.
해결: Identity-Aware Proxy API를 사용 설정합니다.

직원 ID 제휴로 Agent Gateway를 관리할 때 발생하는 오류

Cloud de Confiance 콘솔에서 Agent Gateway를 관리하거나 직원 ID 제휴 (WIF)로 인증할 때 gcloud CLI를 사용하는 경우 이 문제가 발생할 수 있습니다.

콘솔에 다음과 같은 일반적인 로드 또는 생성 오류가 표시됩니다.

'로드하는 중에 오류가 발생했습니다…'
'서버에서 요청을 처리할 수 없습니다.'
'에이전트 게이트웨이를 만들 수 없음'
'로드할 수 없음'

또한 gcloud 명령어 (예: gcloud network-services agent-gateways import)는 error 13: an internal error has occurred와 같은 내부 오류를 반환할 수 있습니다.

이 문제를 해결하려면 roles/networkservices.admin와 같은 필수 권한이 있는 Cloud ID 또는 Google Workspace를 통해 관리되는 표준 Google 계정으로 인증하세요.

제휴 ID는 미리보기의 Agent Platform 거버넌스 및 게이트웨이 서비스에서 제한적으로 지원됩니다. 연결된 주 구성원에게 더 광범위한 IAM 역할을 부여해도 문제가 해결되지 않습니다.

디버깅 워크플로

이그레스 요청 흐름 섹션에 설명된 조건 중 하나라도 누락되면 요청이 차단될 수 있습니다.

IAP 결정 검토

로그 검색 범위를 IAP 이그레스 결정으로 좁히려면 Logging에서 다음 쿼리를 실행하세요.

protoPayload.serviceName="iap.googleapis.com"
protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP"
protoPayload.metadata.mcp_attributes.base_protocol_method="true"

일치하는 IAP 로그 항목이 전혀 표시되지 않으면 IAP에서 평가하기 전에 게이트웨이가 요청을 거부했을 수 있습니다. 다음 단계로 이동합니다.

일치하는 로그 항목이 표시되면 다음 필드를 검토합니다.

protoPayload.authorizationInfo[].granted: 요청이 허용 (true)되었는지 거부 (false)되었는지를 나타냅니다.
protoPayload.authenticationInfo.principalSubject: 호출자의 SPIFFE ID 또는 principal://... ID입니다. 이 정보가 상담사의 신원과 일치하는지 확인합니다.
protoPayload.authorizationInfo[].resource: 호출이 확인된 등록된 대상 리소스입니다.
labels."iap.googleapis.com/audited_resource_name": 이 값이 unregisteredResource이면 대상 호스트 이름이 등록되지 않습니다. Agent Registry에 대상 호스트 이름을 등록하고 에이전트에 이 대상에 대한 iap.resources.egressViaIAP 권한이 있는지 확인합니다.
시행 모드: 요청의 시행 모드를 검토합니다. 드라이 런 요청을 필터링하려면 쿼리에 protoPayload.metadata.iamEnforcementMode="DRY_RUN"을 추가하면 됩니다. DRY_RUN 모드에서 IAP는 거부를 로깅하지만 시행하지는 않습니다. 따라서 에이전트가 드라이 실행 모드에서 403 오류로 실패하면 거부는 게이트웨이의 이그레스 프록시 또는 대상 리소스에서 발생한 것일 수 있습니다.

Agent Gateway 결정 검토

에이전트 게이트웨이에서 요청을 평가한 방법을 검토하려면 로깅에서 게이트웨이 로그를 쿼리하세요. 이 예시에서는 403 오류에 대해서만 로그를 필터링합니다.

resource.type="networkservices.googleapis.com/Gateway"
resource.labels.gateway_type="SECURE_WEB_GATEWAY"
resource.labels.location="REGION"
resource.labels.gateway_name="AGENT_GATEWAY_NAME"
httpRequest.status=403
-httpRequest.requestMethod="CONNECT"

일치하는 로그 항목에서 다음 필드를 검토합니다.

jsonPayload.authzPolicyInfo.policies.result: 전체 승인 결과(ALLOWED 또는 DENIED)입니다.
httpRequest.requestUrl: 상담사가 도달하려고 시도한 정확한 도착 URL을 기록합니다. 다음 단계에서는 대상 리소스에서 사용하는 호스트 이름이 Agent Registry에 등록되어 있는지 확인합니다.

대상 등록 및 IAM 액세스 정책 적용 범위 확인

대상에 액세스하려면 항상 에이전트 아이덴티티에 iap.resources.egressViaIAP 권한을 부여하는 IAM 허용 정책이 필요합니다. 세분화된 리소스별 액세스 정책을 시행하고 정확한 호스트 이름 일치를 보장하려면 Agent Registry에 대상을 등록하는 것이 좋습니다. 등록되지 않은 대상의 경우 등록되지 않은 엔드포인트에 대한 정책이 에이전트 ID에 필요한 권한을 부여하는지 확인합니다.

리소스별 정책을 사용하는 경우 에이전트가 연결하려고 하는 모든 대상 호스트 이름과 호스트 이름의 변형이 에이전트 레지스트리에 등록되어야 합니다. 이는 aiplatform.googleapis.com와 같은 Google API가 SDK 버전, 리전 클라이언트 구성 또는 mTLS 사용량 (예: us-central1-aiplatform.googleapis.com 또는 us-central1-aiplatform.mtls.googleapis.com)에 따라 여러 호스트 이름을 통해 확인할 수 있기 때문입니다.

게이트웨이는 호스트 이름을 정확히 일치시키므로 aiplatform.googleapis.com를 등록했지만 에이전트가 us-central1-aiplatform.googleapis.com를 호출하면 게이트웨이는 이를 등록되지 않은 리소스로 간주하고 요청을 거부합니다.

다음 샘플 스크립트를 실행하여 리소스 유형을 기반으로 레지스트리 항목을 나열하고 에이전트 호출에서 사용되는 특정 호스트 이름의 항목을 확인합니다.

HOSTNAME="HOSTNAME"
PROJECT_ID="PROJECT_ID"
LOCATION="REGION"

echo "Checking Endpoints..."
gcloud agent-registry endpoints list \
  --project="$PROJECT_ID" \
  --location="$LOCATION" | grep "$HOSTNAME"

echo "Checking MCP Servers..."
gcloud agent-registry mcp-servers list \
  --project="$PROJECT_ID" \
  --location="$LOCATION" | grep "$HOSTNAME"

echo "Checking Agents..."
gcloud agent-registry agents list \
  --project="$PROJECT_ID" \
  --location="$LOCATION" | grep "$HOSTNAME"

다음을 바꿉니다.

HOSTNAME: 에이전트가 연결하려고 시도하는 대상 호스트 이름입니다(예: us-central1-aiplatform.mtls.googleapis.com).
PROJECT_ID: Cloud de Confiance 프로젝트 ID입니다.
REGION: Agent Registry 및 Agent Gateway 리소스의 위치입니다(예: us-central1).

출력 1: 호스트 이름이 이미 등록됨

호스트 이름이 Agent Registry 항목에 있으면 다음 예시와 비슷한 출력이 표시됩니다.

Checking Endpoints...
  url: https://us-central1-aiplatform.mtls.googleapis.com
Checking MCP Servers...
Checking Agents...

대상 리소스의 IAM 바인딩 확인으로 이동하여 리소스별 또는 레지스트리 전체 정책이 에이전트 ID에 대한 액세스 권한을 부여하는지 확인합니다.

출력 2: 레지스트리에 호스트 이름이 없음

호스트 이름이 레지스트리에 없으면 다음 예와 비슷한 출력이 표시됩니다.

Checking Endpoints...
Checking MCP Servers...
Checking Agents...

리소스별 또는 레지스트리 전체 정책을 사용하려면 먼저 Agent Registry에 대상을 등록하세요. 등록되지 않은 엔드포인트에 정책을 사용하는 경우 대상 리소스의 IAM 바인딩 확인으로 진행합니다.

대상 리소스의 IAM 바인딩 확인

에이전트 ID 또는 해당 보안 주체 집합에 대상에 대한 iap.resources.egressViaIAP 권한이 있는지 확인합니다.

세 가지 범위에서 정책 바인딩을 구성할 수 있습니다.

레지스트리 전체: 레지스트리에 등록된 모든 에이전트, MCP 서버, 엔드포인트에 대한 액세스 권한입니다.
리소스별: 좁은 액세스 범위입니다. 리소스별 바인딩은 병합되는 대신 해당 특정 리소스의 레지스트리 전체 바인딩을 대체합니다.
등록되지 않은 엔드포인트 정책: Agent Registry에 등록되지 않은 대상에 대한 액세스

다음 예 중 하나를 사용하여 바인딩을 확인합니다.

레지스트리 수준 IAM 정책 바인딩을 확인하려면 다음 명령어를 실행하세요.

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-d '{}' \
-X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry:getIamPolicy" \
-H "Content-Type: application/json"

엔드포인트별 IAM 정책 바인딩을 확인하려면 다음 명령어를 실행합니다.

export HOSTNAME=HOSTNAME

ENDPOINT_ID=$(gcloud agent-registry endpoints list \
--project="PROJECT_ID" \
--location="REGION" \
--filter="interfaces.url:$HOSTNAME" \
--format="value(name.basename())")

echo "ENDPOINT_ID=$ENDPOINT_ID"

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-d '{}' \
-X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry/endpoints/${ENDPOINT_ID}:getIamPolicy"

HOSTNAME을 에이전트가 연결하려고 하는 대상의 호스트 이름으로 바꿉니다(예: us-central1-aiplatform.mtls.googleapis.com).

MCP 서버별 IAM 정책 바인딩을 확인하려면 다음 명령어를 실행합니다.

export MCP_SERVER=MCP_SERVER

MCP_SERVER_ID=$(gcloud agent-registry mcp-servers list \
--project="PROJECT_ID" \
--location="REGION" \
--filter="interfaces.url:$MCP_SERVER" \
--format="value(name.basename())")

echo "MCP_SERVER_ID=$MCP_SERVER_ID"

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-d '{}' \
-X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry/mcpServers/${MCP_SERVER_ID}:getIamPolicy"

MCP_SERVER을 MCP 서버의 URL (예: https://example-abc12345-uc.a.run.app/mcp)로 바꿉니다.

반환된 정책 정보에서 에이전트의 ID 또는 주 구성원 집합과 일치하는 iap.resources.egressViaIAP 권한이 있는 바인딩을 찾습니다. 반환된 출력에 "etag" 필드가 포함되어 있지만 바인딩이 없으면 IAM 정책이 존재하지 않는 것입니다.

바인딩이 있지만 condition가 포함된 경우 Common Expression Language (CEL) 표현식이 에이전트를 제외하지 않는지 확인합니다. 에이전트에 없는 속성으로 필터링하는 조건은 에이전트를 자동으로 제외할 수 있습니다.

타겟 대상에 에이전트 ID 또는 주 구성원 집합에 iap.resources.egressViaIAP 권한을 부여하는 일치하는 정책 바인딩이 없는 경우 다음 정책 옵션 중 하나를 사용하여 권한을 부여합니다.

레지스트리 수준 정책 (권장): 에이전트-레지스트리 정책을 구성하여 Agent Registry에 등록된 모든 리소스에 대한 액세스 권한을 부여합니다.
리소스별 정책 (MCP 서버 또는 엔드포인트): Agent Registry에서 MCP 서버를 등록하거나 엔드포인트를 등록하고 에이전트-MCP 서버 정책 또는 에이전트-엔드포인트 정책을 만듭니다.
등록되지 않은 엔드포인트 정책: 등록되지 않은 엔드포인트 정책을 구성하여 리소스를 등록하지 않고 액세스 권한을 부여합니다.

승인 정책 및 확장 프로그램 검사

이 섹션에서는 에이전트와 연결된 Agent Gateway를 명시적으로 타겟팅하는 승인 정책이 있는지 확인합니다.

게이트웨이와 연결된 승인 확장 프로그램의 세부정보를 가져오고 사용 중인 확장 프로그램이 예상대로 구성되었는지 확인합니다.
```
gcloud service-extensions authz-extensions describe AUTHORIZATION_EXTENSION_NAME \
  --location=LOCATION \
  --project=PROJECT_ID
```
AUTHORIZATION_EXTENSION_NAME를 게이트웨이와 연결된 확장 프로그램 이름으로 바꿉니다. 확장 프로그램 이름을 모르는 경우 Cloud de Confiance Cloud de Confiance 콘솔에서 게이트웨이의 세부정보 페이지로 이동하여 서비스 확장 프로그램 아래의 확장 프로그램 이름 필드 값을 확인하면 됩니다.
승인 정책이 게이트웨이 리소스를 명시적으로 타겟팅하고 동일한 승인 확장 프로그램에 연결되는지 확인합니다. Cloud de Confiance Cloud de Confiance 콘솔에서 게이트웨이의 세부정보 페이지로 이동하여 서비스 확장 프로그램 아래의 정책 이름 필드 값을 확인합니다.

게이트웨이를 타겟팅하는 정책이 없거나 게이트웨이-정책 매핑이 잘못된 경우 승인 확장 프로그램이 실행되지 않습니다.

주 구성원 액세스 경계 정책 확인

주 구성원 액세스 경계 정책은 IAM 허용 정책보다 우선 적용됩니다. 즉, 모든 IAM 바인딩을 올바르게 구성했더라도 에이전트의 범위에서 대상 리소스를 제외하는 활성 주 구성원 액세스 경계 정책이 있으면 요청이 실패합니다.

조직 전체 정책을 나열하려면 다음을 실행합니다.

gcloud iam principal-access-boundary-policies list \
  --organization="ORGANIZATION_ID" \
  --location=global

에이전트의 주 구성원 집합에 바인딩된 정책을 찾으려면 다음을 실행하세요.

gcloud iam policy-bindings search-target-policy-bindings \
  --project="PROJECT_ID" \
  --target="PRINCIPAL_SET"

다음을 바꿉니다.

ORGANIZATION_ID: Cloud de Confiance 조직 ID입니다.
PROJECT_ID: Cloud de Confiance 프로젝트 ID입니다.
PRINCIPAL_SET: 에이전트 ID의 주 구성원 집합입니다.

바인딩이 있는 경우 details.rules[].resources[] 필드를 검사하여 대상이 에이전트의 범위 내에 있는지 확인합니다.

보안 주체와 보안 주체 세트 바인딩 테스트

권한이 일관되지 않게 작동하거나 예기치 않게 실패하는 경우 에이전트의 그룹 ID (주 구성원 집합)가 구성된 방식과 관련이 있을 수 있습니다. 주 구성원 집합 기반 권한은 다음과 같은 이유로 실패할 수 있습니다.

동기화 지연: 집합에 ID를 추가하면 IAM이 새 구성원을 업데이트하고 인식하는 데 몇 분 정도 걸릴 수 있습니다.
속성 누락: 주 구성원 집합의 회원 자격에 특정 속성이 필요한 경우 에이전트의 ID에 해당 속성 (예: 부서 또는 팀 라벨)이 정확하게 포함되어야 합니다. ID에 이러한 속성이 누락된 경우 에이전트가 그룹에서 자동으로 제외될 수 있습니다.

그룹 멤버십이 문제인지 테스트하려면 영향을 받는 리소스에 직접 principal:// 바인딩을 추가하여 특정 에이전트에 직접 권한을 부여하세요. 에이전트가 직접 바인딩으로 연결되면 근본 원인은 속성 불일치 또는 주 구성원 집합과의 동기화 지연일 가능성이 높습니다. 이 문제를 해결하려면 에이전트의 ID 속성을 확인하고 수정하거나 직접 principal:// 바인딩을 사용하세요.

다음 단계

Codelab

Codelab: Govern agentic workloads with Agent Platform

Gemini Enterprise Agent Platform에서 Agent Gateway를 사용하여 에이전트형 워크로드를 제어하는 방법을 알아봅니다.

가이드

Monitor Agent Gateway

Agent Gateway를 모니터링하는 방법을 알아봅니다.

Agent Gateway 연결 문제 해결

Agent Platform 문제 해결 스킬을 사용하여 문제 해결

이그레스 요청 흐름

일반적인 문제

Agent Runtime 시작 중 오류

오류 403 Forbidden개

자체 서명 또는 비공개 CA 대상에 연결할 수 없음

맞춤 컨테이너 (BYOC)로 배포된 에이전트가 Agent Gateway에 연결되지 않음

정책 바인딩이 실패하거나 거버넌스 거부를 모방함

직원 ID 제휴로 Agent Gateway를 관리할 때 발생하는 오류

디버깅 워크플로

IAP 결정 검토

Agent Gateway 결정 검토

대상 등록 및 IAM 액세스 정책 적용 범위 확인

출력 1: 호스트 이름이 이미 등록됨

출력 2: 레지스트리에 호스트 이름이 없음

대상 리소스의 IAM 바인딩 확인

승인 정책 및 확장 프로그램 검사

주 구성원 액세스 경계 정책 확인

보안 주체와 보안 주체 세트 바인딩 테스트

다음 단계

Codelab: Govern agentic workloads with Agent Platform

Monitor Agent Gateway

오류 `403 Forbidden`개