Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
Objetivos del modelo Smithy
Smithy es un lenguaje para definir servicios y kits de desarrollo de software (SDK). Los modelos de Smithy proporcionan un enfoque más estructurado para definir las API en comparación con OpenAPI y son particularmente útiles para conectarse a AWS servicios, como Gateway. AgentCore
Los objetivos del modelo de Smithy conectan su AgentCore puerta de enlace a los servicios que se definen mediante los modelos de API de Smithy. Al invocar un objetivo de puerta de enlace modelo de 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 de funciones, para ayudarte a decidir si un objetivo de Smithy es aplicable a tu caso de uso. Si lo es, puede crear un esquema que siga las especificaciones y, a continuación, configurar los permisos para que la puerta de enlace pueda acceder al destino. Elija un tema para obtener más información:
Consideraciones y limitaciones clave
Cuando utilice los modelos de Smithy con AgentCore Gateway, tenga en cuenta las siguientes limitaciones:
-
Tamaño máximo del modelo: 10 MB
-
Solo se admiten totalmente los enlaces del protocolo JSON
-
Solo se RestJson admite el protocolo
Al considerar la posibilidad de usar los modelos de Smithy con AgentCore Gateway, consulte la siguiente tabla de compatibilidad de funciones.
Mejores prácticas de seguridad para la configuración de terminales
aviso
Al definir las reglas de punto final y las URL de los servidores en sus modelos de Smithy, evite utilizar patrones de parámetros de URL demasiado permisivos, ya que podrían exponer su puerta de enlace a riesgos de seguridad.
Los modelos de Smithy admiten la configuración dinámica de puntos finales mediante reglas de punto final y parámetros de URL. Sin embargo, ciertos patrones pueden introducir vulnerabilidades de seguridad si no se restringen 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 de los servidores:
https://{subdomain}.{env}.{domain}.com -
Reglas de punto final que permiten la construcción arbitraria de URL sin validación
Estos patrones pueden aprovecharse potencialmente para:
-
Redirigir las solicitudes a puntos finales no deseados o malintencionados
-
Acceda a los recursos de la red interna o a los servicios de metadatos de la instancia (falsificación de Server-Side solicitudes)
-
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
-
Para AWS los servicios, confíe en la resolución de puntos finales estándar con parámetros de región validados. Gateway aplica AWS la validación 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
En el caso de las integraciones de AWS servicios, AgentCore Gateway valida automáticamente los parámetros de la región y bloquea las solicitudes a 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 servicio 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 de soporte de protocolos Protocolo de soporte request/response Patrones HTTP estándar Tipos de datos Primitivos (cadena, entero, booleano, flotante, doble) Tipos complejos (estructuras, listas, mapas) Gestión de marcas de tiempo Tipos de datos de blob Enlaces de métodos HTTP básicos Enlaces de parámetros de ruta simples Enlaces de parámetros de consulta Encabezado Enlaces para casos simples Reglas de punto final La regla de punto final establece la determinación del punto final en tiempo de ejecución |
Protocolo de soporte de RestXml protocolo JsonRpc AwsQuery Protocolo Ec2Query Protocolos personalizados Autenticación Múltiples tipos de autenticación de salida para API específicas Esquemas de autenticación complejos que requieren decisiones de tiempo de ejecución Operaciones Operaciones de streaming Operaciones que requieren implementaciones de protocolos personalizadas |
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 de Smithy personalizados para productos que no sean de servicios.AWS
Tras definir su 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 destino a su puerta de enlace.
-
Pegue la definición en línea cuando añada el destino a su puerta de enlace.
Amplíe una sección para ver ejemplos de especificaciones de modelos de Smithy compatibles y no compatibles:
El siguiente ejemplo muestra una especificación de modelo de 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"} } ] })
