Objetivos del modelo Smithy
Smithy es un lenguaje para definir servicios y kits de desarrollo de software (SDK). Los modelos Smithy proporcionan un enfoque más estructurado para definir las API en comparación con OpenAPI, y son particularmente útiles para conectarse AWS a servicios, como AgentCore Gateway.
Los objetivos del modelo Smithy conectan su AgentCore puerta de enlace con los servicios que se definen mediante los modelos de API de Smithy. Al invocar un objetivo de puerta de enlace modelo Smithy, la puerta de enlace traduce las solicitudes MCP entrantes en llamadas a la API que se envían a estos servicios. La puerta de enlace también gestiona el formato de las respuestas.
Revisa las principales consideraciones y limitaciones, incluida la compatibilidad con las funciones, para ayudarte a decidir si un objetivo de Smithy es aplicable a tu caso de uso. Si es así, puede crear un esquema que siga las especificaciones y, a continuación, configurar los permisos para que la puerta de enlace pueda acceder al objetivo. Elija un tema para obtener más información:
Consideraciones y limitaciones clave
Cuando utilice los modelos Smithy con AgentCore Gateway, tenga en cuenta las siguientes limitaciones:
-
Tamaño máximo del modelo: 10 MB
-
Solo se admiten en su totalidad los enlaces del protocolo JSON
-
Solo se RestJson admite el protocolo
Si desea utilizar los modelos Smithy con AgentCore Gateway, consulte la siguiente tabla de compatibilidad de funciones.
Prácticas recomendadas de seguridad para la configuración de terminales
aviso
Al definir las reglas de los puntos finales y las URL de los servidores en sus modelos de Smithy, evite utilizar patrones de parámetros de URL demasiado permisivos que puedan exponer su puerta de enlace a riesgos de seguridad.
Los modelos de Smithy admiten la configuración dinámica de los puntos finales mediante reglas de puntos finales y parámetros de URL. Sin embargo, ciertos patrones pueden introducir vulnerabilidades de seguridad si no se limitan adecuadamente. En concreto, evite utilizar patrones totalmente dinámicos, como:
-
Parámetros de host o dominio sin restricciones en las URL de los puntos finales: o
https://{host}/api/v1https://{domain}.example.com -
Varios marcadores de posición sin restricciones en las URL del servidor:
https://{subdomain}.{env}.{domain}.com -
Reglas de punto final que permiten la construcción de URL arbitrarias sin validación
Estos patrones pueden explotarse potencialmente para:
-
Redirigir las solicitudes a puntos finales no deseados o maliciosos
-
Acceda a los recursos de la red interna o a los servicios de metadatos de las instancias (Server-Side solicitud de falsificación)
-
Exfiltre las credenciales de IAM o los datos confidenciales
Prácticas recomendadas:
-
Utilice URL de punto final estáticas y totalmente calificadas siempre que sea posible
-
En el AWS caso de los servicios, utilice una resolución de punto final estándar con parámetros de región validados. Gateway exige la validación AWS regional de los servicios AWS
-
Si se requieren reglas de punto final personalizadas, restrinja los parámetros a valores específicos y validados
-
Evite exponer parámetros de host o dominio sin procesar en la configuración de puntos finales de su modelo de Smithy
Para las integraciones de AWS servicios, AgentCore Gateway valida automáticamente los parámetros de la región y bloquea las solicitudes a los rangos de IP privados.
Smithy ofrece soporte para Gateway AgentCore
En la siguiente tabla se describen las funciones de Smithy compatibles y no compatibles con Gateway:
| Características admitidas | Características no admitidas |
|---|---|
|
Definiciones de servicios Definiciones de estructura de servicio basadas en las especificaciones de Smithy Definiciones de operaciones con input/output formas Definiciones de recursos Formas de rasgos RestJson Protocolo Protocolo de soporte Protocolo request/response Patrones HTTP estándar Tipos de datos Tipos primitivos (cadena, entero, booleano, flotante, doble) Tipos complejos (estructuras, listas, mapas) Manejo de marcas de tiempo Tipos de datos Blob Enlaces de datos HTTP Enlaces de métodos HTTP básicos Enlaces de parámetros de ruta simples Enlaces de parámetros de consulta Enlaces de encabezados para casos simples Reglas de punto final La regla de punto final establece la determinación del punto final |
Protocolo Support RestXml protocolo JsonRpc AwsQuery protocolo Ec2Query Protocolos personalizados Autenticación Varios tipos de autenticación de salida para API específicas Esquemas de autenticación complejos que requieren decisiones en tiempo de ejecución Operaciones de streaming Operaciones que requieren implementaciones de protocolos personalizados |
Especificación del modelo Smithy
AgentCore Gateway proporciona modelos Smithy integrados para servicios comunes AWS . Para ver los modelos de AWS servicios de Smithy, consulte el repositorio de modelos de AWS API
nota
AgentCore Gateway no admite modelos Smithy personalizados para empresas que no sean de servicios.AWS
Tras definir el modelo de Smithy, puede realizar una de las siguientes acciones:
-
Cárguelo en un bucket de Amazon S3 y consulte la ubicación de S3 cuando añada el objetivo a su puerta de enlace.
-
Pegue la definición en línea cuando añada el objetivo a su puerta de enlace.
Amplíe una sección para ver ejemplos de especificaciones de modelos Smithy compatibles y no compatibles:
El siguiente ejemplo muestra una especificación de modelo Smithy válida para un servicio meteorológico:
{ "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" } } } } } }
El siguiente ejemplo muestra una configuración de reglas de punto final no válida con 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"} } ] })
