# HTTP 패스스루 대상 HTTP 패스스루 대상을 추가하여 게이트웨이를 통해 HTTP 엔드포인트로 트래픽을 라우팅할 수 있습니다. 게이트웨이는 보안 프록시 계층 역할을 하는 프로토콜 변환 없이 대상 엔드포인트에 요청을 전달합니다. 따라서 패스스루 대상은 게이트웨이의 중앙 집중식 인증, 정책 적용 및 관찰성을 통해 액세스하려는 에이전트 URLs, 외부 APIs 또는 HTTP 서비스에 이상적입니다. 게이트웨이에 HTTP 패스스루 대상을 추가하는 것은 다음과 같은 경우에 유용합니다. + 통합 액세스 제어를 통해 단일 게이트웨이 엔드포인트 뒤에 있는 프런트 에이전트 서비스(예: A2A 에이전트, 외부 MCP 서버 또는 사용자 지정 추론 엔드포인트). + 게이트웨이가 인바운드 인증 및 아웃바운드 자격 증명 주입을 관리하는 동안 트래픽을 외부 서비스로 라우팅합니다. + 가드레일 및 액세스 제어와 같은 게이트웨이 정책을 외부 엔드포인트로 향하는 요청에 적용합니다. + 경로 기반 라우팅(`/{targetName}/{path}`)을 사용하여 단일 게이트웨이를 통해 여러 외부 서비스에 연결할 수 있습니다. **Topics** + [대상 구성](#gateway-target-http-passthrough-config) + [HTTP 패스스루 대상 생성](#gateway-target-http-passthrough-create) + [HTTP 패스스루 대상 호출](#gateway-target-http-passthrough-invoke) + [아웃바운드 권한 부여](#gateway-target-http-passthrough-auth) ## 대상 구성 HTTP 패스스루 대상을 생성할 때 대상 엔드포인트 URL과 대상이 구현하는 애플리케이션 프로토콜을 나타내는 프로토콜 유형을 제공합니다. 게이트웨이는 관찰성 및 정책 평가에 프로토콜 유형을 사용하지만 프로토콜 변환은 수행하지 않습니다. HTTP 패스스루 대상의 대상 구성은 다음 구조를 사용합니다. ``` { "http": { "passthrough": { "endpoint": "https://partner-agent.example.com", "protocolType": "A2A" } } } ``` 다음 예제에서는 사용자 지정 프로토콜과 명시적 API 스키마가 있는 패스스루 대상을 보여줍니다. ``` { "http": { "passthrough": { "endpoint": "https://my-service.example.com", "protocolType": "CUSTOM", "schema": { "source": { "s3": { "uri": "s3://DOC-EXAMPLE-BUCKET/service-schema.yaml" } } } } } } ``` + **엔드포인트**(필수) - 대상 서비스의 HTTPS URL입니다. 게이트웨이는 요청을이 엔드포인트로 전달합니다. + **protocolType**(필수) - 대상이 구현하는 애플리케이션 프로토콜입니다. 유효한 값: + `MCP` - 대상은 MCP 서버입니다. 직접 액세스하려는 단일 MCP 서버로 라우팅할 때 사용합니다(다른 MCP 대상과 집계되지 않음). + `A2A` - 대상은 Agent-to-Agent(A2A) 프로토콜을 구현합니다. + `INFERENCE` - 대상은 추론 엔드포인트입니다. + `CUSTOM` - 대상이 사용자 지정 또는 독점 프로토콜을 구현합니다. + **스키마**(선택 사항) - 패스스루 대상의 요청 및 응답 구조를 설명하는 API 스키마입니다. 게이트웨이는이 스키마를 사용하여 가드레일과 같은 정책 엔진 기능을 활성화합니다. 스키마 형식은 OpenAPI 또는 Smithy로 자동 감지됩니다. 스키마 요구 사항은 프로토콜 유형에 따라 다릅니다. + `MCP` 및 `A2A` 프로토콜 유형의 경우 기본 스키마가 자동으로 적용됩니다. 기본값을 재정의하지 않는 한 스키마를 제공할 필요가 없습니다. + 잘 알려진 공급자(OpenAI, Anthropic 또는 Amazon Bedrock)가 있는 `INFERENCE` 프로토콜 유형의 경우 엔드포인트 도메인을 기반으로 기본 스키마가 적용됩니다. + `CUSTOM` 프로토콜 유형의 경우 가드레일을 사용하려면 스키마를 제공해야 합니다. `schema` 객체에는 스키마 콘텐츠의 위치를 `source` 지정하는이 포함되어 있습니다. + **s3** - 스키마 파일을 가리키는 S3 URI(예: `s3://DOC-EXAMPLE-BUCKET/service-schema.yaml`). + **inlinePayload** - 문자열로 직접 제공되는 스키마 콘텐츠입니다. ## HTTP 패스스루 대상 생성 다음 예제에서는 A2A 에이전트, 외부 MCP 서버, IAM 인증 내부 서비스, API 키로 인증된 외부 API 등 다양한 유형의 엔드포인트로 라우팅하는 패스스루 대상을 생성합니다. **Example** 1. OAuth 자격 증명을 사용하여 A2A 에이전트로 라우팅합니다. ``` agentcore add gateway-target \ --name partner-agent \ --type passthrough \ --passthrough-endpoint https://partner-agent.example.com \ --passthrough-protocol A2A \ --outbound-auth oauth \ --credential-name partner-oauth \ --gateway MyGateway agentcore deploy ``` OAuth 자격 증명을 사용하여 외부 MCP 서버로 라우팅합니다. ``` agentcore add gateway-target \ --name slack-mcp \ --type passthrough \ --passthrough-endpoint https://mcp-slack.example.com \ --passthrough-protocol MCP \ --outbound-auth oauth \ --credential-name slack-oauth \ --gateway MyGateway agentcore deploy ``` `CUSTOM` 프로토콜 및 S3 스키마와 함께 IAM(SigV4) 역할 기반 인증을 사용하여 내부 서비스로 라우팅합니다. ``` agentcore add gateway-target \ --name internal-service \ --type passthrough \ --passthrough-endpoint https://internal-service.example.com \ --passthrough-protocol CUSTOM \ --schema s3://amzn-s3-demo-bucket/internal-service-schema.yaml \ --signing-service execute-api \ --signing-region us-west-2 \ --gateway MyGateway agentcore deploy ``` API 키 자격 증명을 사용하여 외부 API로 라우팅합니다. ``` agentcore add gateway-target \ --name external-api \ --type passthrough \ --passthrough-endpoint https://api.example.com \ --passthrough-protocol CUSTOM \ --outbound-auth api-key \ --credential-name my-api-key \ --credential-parameter-name x-api-key \ --gateway MyGateway agentcore deploy ``` 1. OAuth 자격 증명을 사용하여 A2A 에이전트로 라우팅합니다. ``` aws bedrock-agentcore-control create-gateway-target --cli-input-json '{ "gatewayIdentifier": "GATEWAY_ID", "name": "partner-agent", "targetConfiguration": { "http": { "passthrough": { "endpoint": "https://partner-agent.example.com", "protocolType": "A2A" } } }, "credentialProviderConfigurations": [ { "credentialProviderType": "OAUTH", "credentialProvider": { "oauthCredentialProvider": { "providerArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:token-vault/default/oauthcredentialprovider/partner-oauth" } } } ] }' ``` OAuth 자격 증명을 사용하여 외부 MCP 서버로 라우팅합니다. ``` aws bedrock-agentcore-control create-gateway-target --cli-input-json '{ "gatewayIdentifier": "GATEWAY_ID", "name": "slack-mcp", "targetConfiguration": { "http": { "passthrough": { "endpoint": "https://mcp-slack.example.com", "protocolType": "MCP" } } }, "credentialProviderConfigurations": [ { "credentialProviderType": "OAUTH", "credentialProvider": { "oauthCredentialProvider": { "providerArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:token-vault/default/oauthcredentialprovider/slack-oauth" } } } ] }' ``` `CUSTOM` 프로토콜 및 S3 스키마와 함께 IAM 역할 기반 인증을 사용하여 내부 서비스로 라우팅합니다. ``` aws bedrock-agentcore-control create-gateway-target --cli-input-json '{ "gatewayIdentifier": "GATEWAY_ID", "name": "internal-service", "targetConfiguration": { "http": { "passthrough": { "endpoint": "https://internal-service.example.com", "protocolType": "CUSTOM", "schema": { "source": { "s3": { "uri": "s3://DOC-EXAMPLE-BUCKET/internal-service-schema.yaml" } } } } } }, "credentialProviderConfigurations": [ {"credentialProviderType": "GATEWAY_IAM_ROLE"} ] }' ``` API 키 자격 증명을 사용하여 외부 API로 라우팅합니다. ``` aws bedrock-agentcore-control create-gateway-target --cli-input-json '{ "gatewayIdentifier": "GATEWAY_ID", "name": "external-api", "targetConfiguration": { "http": { "passthrough": { "endpoint": "https://api.example.com", "protocolType": "CUSTOM" } } }, "credentialProviderConfigurations": [ { "credentialProviderType": "API_KEY", "credentialProvider": { "apiKeyCredentialProvider": { "providerArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:token-vault/default/apikeycredentialprovider/my-api-key", "credentialParameterName": "x-api-key" } } } ] }' ``` ## HTTP 패스스루 대상 호출 게이트웨이를 통해 HTTP 패스스루 대상을 호출하려면 경로 기반 라우팅을 사용하여 대상에 요청을 보냅니다. URL 형식은 다음과 같습니다. ``` https://{gatewayId}.gateway.bedrock-agentcore.{region}.amazonaws.com/{targetName}/{path} ``` 게이트웨이는 대상의 `{endpoint}/{path}`에 요청을 전달합니다. `{gatewayId}`를 게이트웨이 ID로,를 AWS 리전`{region}`으로, `{targetName}`를 대상 이름으로,를 전달할 경로`{path}`로 바꿉니다. 다음 예시에서는 게이트웨이를 통해 파트너 에이전트에게 A2A 메시지를 보냅니다. ``` curl -X POST https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/partner-agent/invocations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{ "jsonrpc": "2.0", "id": "req-001", "method": "message/send", "params": { "message": { "role": "user", "parts": [{"kind": "text", "text": "What is the stock price of AMZN?"}], "messageId": "msg-001" } } }' ``` 다음 예제에서는 게이트웨이를 통해 MCP 서버를 호출합니다. ``` curl -X POST https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/slack-mcp/mcp \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' ``` ## 아웃바운드 권한 부여 HTTP 패스스루 대상은 다음과 같은 아웃바운드 권한 부여 유형을 지원합니다. + **IAM(SigV4)**(`GATEWAY_IAM_ROLE`) - 게이트웨이는 게이트웨이 서비스 역할을 수임하여 대상에 대한 요청에 서명합니다. + **OAuth**(`OAUTH`) - 게이트웨이는 Amazon Bedrock AgentCore 자격 증명 서비스를 통해 대상에 구성된 자격 증명 공급자로부터 OAuth 토큰을 검색합니다. + **호출자 IAM 자격 증명**(`CALLER_IAM_CREDENTIALS`) - 게이트웨이는 호출자의 IAM 자격 증명 및 권한을 사용하여 SigV4를 사용하여 대상에 대한 요청에 서명합니다. `AWS_IAM` 또는 `AUTHENTICATE_ONLY` 권한 부여자 유형이 있는 게이트웨이에만 사용할 수 있습니다. + **토큰 패스스루**(`JWT_PASSTHROUGH`) - 게이트웨이는 인바운드 토큰을 검증하고 수정 없이 대상에 전달합니다. + **API 키**(`API_KEY`) - 게이트웨이는 토큰 볼트에 구성된 자격 증명 공급자로부터 API 키를 검색하여 지정된 요청 헤더로 아웃바운드 요청에 주입합니다.