대상 구성 HTTP 패스스루 대상 생성 HTTP 패스스루 대상 호출 지원되는 HTTP 메서드 아웃바운드 권한 부여

HTTP 패스스루 대상

HTTP 패스스루 대상을 추가하여 게이트웨이를 통해 HTTP 엔드포인트로 트래픽을 라우팅할 수 있습니다. 게이트웨이는 보안 프록시 계층 역할을 하는 프로토콜 변환 없이 대상 엔드포인트에 요청을 전달합니다. 따라서 패스스루 대상은 게이트웨이의 중앙 집중식 인증, 정책 적용 및 관찰성을 통해 액세스하려는 에이전트 URLs, 외부 APIs 또는 HTTP 서비스에 이상적입니다.

게이트웨이에 HTTP 패스스루 대상을 추가하는 것은 다음과 같은 경우에 유용합니다.

통합 액세스 제어를 통해 단일 게이트웨이 엔드포인트 뒤에 있는 프런트 에이전트 서비스(예: A2A 에이전트, 외부 MCP 서버 또는 사용자 지정 추론 엔드포인트).
게이트웨이가 인바운드 인증 및 아웃바운드 자격 증명 주입을 관리하는 동안 트래픽을 외부 서비스로 라우팅합니다.
가드레일 및 액세스 제어와 같은 게이트웨이 정책을 외부 엔드포인트로 향하는 요청에 적용합니다.
경로 기반 라우팅(/{targetName}/{path})을 사용하여 단일 게이트웨이를 통해 여러 외부 서비스에 연결할 수 있습니다.

대상 구성

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 등 다양한 유형의 엔드포인트로 라우팅하는 패스스루 대상을 생성합니다.

예

AgentCore CLI

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로 라우팅하고 호출자의 JWT를 전달합니다.


agentcore add gateway-target \
  --name external-api \
  --type passthrough \
  --passthrough-endpoint https://api.example.com \
  --passthrough-protocol CUSTOM \
  --outbound-auth jwt-passthrough \
  --gateway MyGateway
agentcore deploy

AWS CLI

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 <token>" \
    -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 <token>" \
    -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

지원되는 HTTP 메서드

게이트웨이는 패스스루 대상이 구현하는 프로토콜인 MCP 서버, A2A 에이전트 및 추론 엔드포인트에서 사용하는 HTTP 메서드를 지원합니다. 이러한 프로토콜은 서비스를 호출하고 트래픽을 라우팅하기 위한 특정 방법 하위 집합에 의존합니다.

게이트웨이는 다음 HTTP 메서드를 지원합니다.

POST - 모든 패스스루 대상 프로토콜에서 기본 방법으로 사용됩니다. MCP는 JSON-RPC 메시지에 POST를 사용하고, A2A는 메시지 전송 및 작업 관리에 POST를 사용하며, 추론 엔드포인트는 완료 및 채팅 요청에 POST를 사용합니다.
GET - MCP for SSE 스트림 구독, 작업 상태 검색 및 작업 나열을 위한 A2A, 모델 나열을 위한 추론 엔드포인트에 사용됩니다.
DELETE - A2A에서 푸시 알림 구성을 제거하고 추론 엔드포인트에서 리소스를 삭제하는 데 사용됩니다.

게이트웨이는 PATCH, HEAD, 또는 OPTIONS 메서드PUT를 지원하지 않습니다. 패스스루 대상은 서비스 호출 및 트래픽 라우팅을 위해 설계되었으며 이러한 방법은 해당 범위를 벗어납니다.

클라이언트가 지원되지 않는 HTTP 메서드를 사용하여 요청을 보내면 게이트웨이는 오류를 반환합니다.

아웃바운드 권한 부여

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 키를 검색하여 지정된 요청 헤더로 아웃바운드 요청에 주입합니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

AgentCore 런타임

추론 대상