View a markdown version of this page

Smithy 모델 대상 - Amazon Bedrock AgentCore
주요 고려 사항 및 제한 사항Smithy 모델 사양

Smithy 모델 대상

Smithy는 서비스 및 소프트웨어 개발 키트(SDKs. Smithy 모델은 OpenAPI에 비해 APIs 정의에 대한 보다 구조화된 접근 방식을 제공하며 AgentCore Gateway와 같은 AWS 서비스에 연결하는 데 특히 유용합니다.

Smithy 모델 대상은 AgentCore 게이트웨이를 Smithy API 모델을 사용하여 정의된 서비스에 연결합니다. Smithy 모델 게이트웨이 대상을 호출하면 게이트웨이는 수신 MCP 요청을 이러한 서비스로 전송되는 API 호출로 변환합니다. 게이트웨이는 응답 형식도 처리합니다.

기능 지원을 포함한 주요 고려 사항 및 제한 사항을 검토하여 사용 사례에 Smithy 대상을 적용할 수 있는지 결정하는 데 도움이 됩니다. 이 경우 사양을 따르는 스키마를 생성한 다음 게이트웨이가 대상에 액세스할 수 있도록 권한을 설정할 수 있습니다. 주제 영역을 선택하여 자세히 알아보세요.

주요 고려 사항 및 제한 사항

AgentCore Gateway에서 Smithy 모델을 사용하는 경우 다음 제한 사항에 유의하세요.

  • 최대 모델 크기: 10MB

  • JSON 프로토콜 바인딩만 완전히 지원됩니다.

  • RestJson 프로토콜만 지원됩니다.

AgentCore Gateway에서 Smithy 모델을 사용하는 방법을 고려할 때 다음 기능 지원 표를 검토하세요.

엔드포인트 구성에 대한 보안 모범 사례

주의

Smithy 모델에서 엔드포인트 규칙과 서버 URLs을 정의할 때는 게이트웨이를 보안 위험에 노출시킬 수 있는 지나치게 허용적인 URL 파라미터 패턴을 사용하지 마세요.

Smithy 모델은 엔드포인트 규칙 및 URL 파라미터를 통해 동적 엔드포인트 구성을 지원합니다. 그러나 특정 패턴이 제대로 제한되지 않으면 보안 취약성이 발생할 수 있습니다. 특히 다음과 같은 완전 동적 패턴을 사용하지 마세요.

  • 엔드포인트 URLs의 무제한 호스트 또는 도메인 파라미터: https://{host}/api/v1 또는 https://{domain}.example.com

  • 서버 URLs: https://{subdomain}.{env}.{domain}.com

  • 검증 없이 임의 URL 구성을 허용하는 엔드포인트 규칙

이러한 패턴은 잠재적으로 다음을 위해 악용될 수 있습니다.

  • 의도하지 않거나 악의적인 엔드포인트로 요청 리디렉션

  • 내부 네트워크 리소스 또는 인스턴스 메타데이터 서비스에 액세스(서버 측 요청 위조)

  • IAM 자격 증명 또는 민감한 데이터 유출

권장 사례:

  • 가능하면 정규화된 정적 엔드포인트 URLs 사용

  • AWS 서비스의 경우 검증된 리전 파라미터와 함께 표준 엔드포인트 해상도를 사용합니다. Gateway는 AWS 서비스에 대한 AWS 리전 검증을 적용합니다.

  • 사용자 지정 엔드포인트 규칙이 필요한 경우 파라미터를 구체적이고 검증된 값으로 제한합니다.

  • Smithy 모델의 엔드포인트 구성에서 원시 호스트 또는 도메인 파라미터 노출 방지

AWS 서비스 통합의 경우 AgentCore Gateway는 리전 파라미터를 자동으로 검증하고 프라이빗 IP 범위에 대한 요청을 차단합니다.

AgentCore Gateway에 대한 Smithy 기능 지원

다음 표에는 Gateway에서 지원 및 지원하지 않는 Smithy 기능이 요약되어 있습니다.

지원 기능 지원되지 않는 기능

서비스 정의 Smithy 사양 기반 서비스 구조 정의 입력/출력 셰이프가 있는 작업 정의 리소스 정의 속성 셰이프 프로토콜 지원 RestJson 프로토콜 표준 HTTP 요청/응답 패턴 데이터 유형 기본 유형(문자열, 정수, 부울, 부동 소수점, 이중) 복합 유형(구조, 목록, 맵) 타임스탬프 처리 Blob 데이터 유형 HTTP 바인딩 기본 HTTP 메서드 바인딩 단순 경로 파라미터 바인딩 쿼리 파라미터 바인딩 간단한 경우에 대한 헤더 바인딩 엔드포인트 규칙 엔드포인트 규칙 세트 조건을 기반으로 런타임 엔드포인트 결정

프로토콜 지원 RestXml 프로토콜 JsonRpc 프로토콜 AwsQuery 프로토콜 Ec2Query 프로토콜 사용자 지정 프로토콜 인증 특정 APIs에 대한 여러 송신 인증 유형 런타임 결정이 필요한 복잡한 인증 체계 작업 스트리밍 작업 사용자 지정 프로토콜 구현이 필요한 작업

Smithy 모델 사양

AgentCore Gateway는 일반적인 AWS 서비스를 위한 내장 Smithy 모델을 제공합니다. AWS 서비스에 대한 Smithy 모델을 보려면 AWS API 모델 리포지토리를 참조하세요.

참고

AgentCore Gateway는 비AWS 서비스에 대한 사용자 지정 Smithy 모델을 지원하지 않습니다.

Smithy 모델을 정의한 후 다음 중 하나를 수행할 수 있습니다.

  • Amazon S3 버킷에 업로드하고 게이트웨이에 대상을 추가할 때 S3 위치를 참조합니다.

  • 게이트웨이에 대상을 추가할 때 정의를 인라인으로 붙여 넣습니다.

섹션을 확장하여 지원되는 Smithy 모델 사양과 지원되지 않는 Smithy 모델 사양의 예를 확인합니다.

다음 예제는 날씨 서비스에 유효한 Smithy 모델 사양을 보여줍니다.

{
  "smithy": "2.0",
  "metadata": {
    "suppressions": []
  },
  "shapes": {
    "example.weather#WeatherService": {
      "type": "service",
      "version": "1.0.0",
      "operations": [
        {
          "target": "example.weather#GetCurrentWeather"
        }
      ],
      "traits": {
        "aws.protocols#restJson1": {},
        "smithy.api#documentation": "Weather service for retrieving weather information"
      }
    },
    "example.weather#GetCurrentWeather": {
      "type": "operation",
      "input": {
        "target": "example.weather#GetCurrentWeatherInput"
      },
      "output": {
        "target": "example.weather#GetCurrentWeatherOutput"
      },
      "errors": [
        {
          "target": "smithy.framework#ValidationException"
        }
      ],
      "traits": {
        "smithy.api#http": {
          "method": "GET",
          "uri": "/weather"
        },
        "smithy.api#documentation": "Get current weather for a location"
      }
    },
    "example.weather#GetCurrentWeatherInput": {
      "type": "structure",
      "members": {
        "location": {
          "target": "smithy.api#String",
          "traits": {
            "smithy.api#required": {},
            "smithy.api#httpQuery": "location",
            "smithy.api#documentation": "City name or coordinates"
          }
        },
        "units": {
          "target": "example.weather#Units",
          "traits": {
            "smithy.api#httpQuery": "units",
            "smithy.api#default": "metric",
            "smithy.api#documentation": "Units of measurement (metric or imperial)"
          }
        }
      }
    },
    "example.weather#GetCurrentWeatherOutput": {
      "type": "structure",
      "members": {
        "location": {
          "target": "smithy.api#String",
          "traits": {
            "smithy.api#documentation": "Location name"
          }
        },
        "temperature": {
          "target": "smithy.api#Float",
          "traits": {
            "smithy.api#documentation": "Current temperature"
          }
        },
        "conditions": {
          "target": "smithy.api#String",
          "traits": {
            "smithy.api#documentation": "Weather conditions description"
          }
        },
        "humidity": {
          "target": "smithy.api#Float",
          "traits": {
            "smithy.api#documentation": "Humidity percentage"
          }
        }
      }
    },
    "example.weather#Units": {
      "type": "enum",
      "members": {
        "metric": {
          "target": "smithy.api#Unit",
          "traits": {
            "smithy.api#enumValue": "metric"
          }
        },
        "imperial": {
          "target": "smithy.api#Unit",
          "traits": {
            "smithy.api#enumValue": "imperial"
          }
        }
      }
    }
  }
}

다음 예제에서는 Smithy를 사용한 잘못된 엔드포인트 규칙 구성을 보여줍니다.

@endpointRuleSet({
  "rules": [
    {
      "conditions": [{"fn": "booleanEquals", "argv": [{"ref": "UseFIPS"}, true]}],
      "endpoint": {"url": "https://weather-fips.{Region}.example.com"}
    },
    {
      "endpoint": {"url": "https://weather.{Region}.example.com"}
    }
  ]
})