Alvos do modelo Smithy
Smithy é uma linguagem para definir serviços e kits de desenvolvimento de software (SDKs). Os modelos Smithy fornecem uma abordagem mais estruturada para definir APIs em comparação com o OpenAPI e são particularmente úteis para se conectar a AWS serviços, como o Gateway. AgentCore
Os alvos do modelo Smithy conectam seu AgentCore gateway a serviços definidos usando modelos de API do Smithy. Quando você invoca um destino de gateway do modelo Smithy, o gateway converte as solicitações MCP recebidas em chamadas de API que são enviadas para esses serviços. O gateway também gerencia a formatação da resposta.
Analise as principais considerações e limitações, incluindo o suporte a recursos, para ajudá-lo a decidir se uma meta da Smithy é aplicável ao seu caso de uso. Se estiver, você pode criar um esquema que siga as especificações e, em seguida, configurar permissões para que o gateway possa acessar o destino. Escolha um tópico para saber mais:
Principais considerações e limitações
Ao usar os modelos Smithy com o AgentCore Gateway, esteja ciente das seguintes limitações:
-
Tamanho máximo do modelo: 10MB
-
Somente as vinculações de protocolo JSON são totalmente suportadas
-
Somente o RestJson protocolo é suportado
Ao considerar o uso de modelos Smithy com o AgentCore Gateway, consulte a tabela de suporte de recursos a seguir.
Práticas recomendadas de segurança para configuração de endpoints
Atenção
Ao definir regras de endpoint e URLs de servidor em seus modelos Smithy, evite usar padrões de parâmetros de URL excessivamente permissivos que possam expor seu gateway a riscos de segurança.
Os modelos Smithy oferecem suporte à configuração dinâmica de endpoints por meio de regras de endpoint e parâmetros de URL. No entanto, certos padrões podem introduzir vulnerabilidades de segurança se não forem adequadamente restringidos. Especificamente, evite usar padrões totalmente dinâmicos, como:
-
Parâmetros irrestritos de host ou domínio em URLs de endpoints: ou
https://{host}/api/v1https://{domain}.example.com -
Vários espaços reservados irrestritos em URLs de servidores:
https://{subdomain}.{env}.{domain}.com -
Regras de endpoint que permitem a construção arbitrária de URL sem validação
Esses padrões podem ser potencialmente explorados para:
-
Redirecione solicitações para endpoints não intencionais ou maliciosos
-
Acesse recursos de rede internos ou serviços de metadados de instância (falsificação de Server-Side solicitações)
-
Exfiltre credenciais do IAM ou dados confidenciais
Práticas recomendadas:
-
Use URLs de endpoint estáticos e totalmente qualificados sempre que possível
-
Para AWS serviços, confie na resolução padrão de endpoints com parâmetros de região validados. O gateway impõe a validação AWS da região para serviços AWS
-
Se forem necessárias regras de endpoint personalizadas, restrinja os parâmetros a valores específicos e validados
-
Evite expor parâmetros brutos de host ou domínio na configuração de endpoint do seu modelo Smithy
Para integrações AWS de serviços, o AgentCore Gateway valida automaticamente os parâmetros da região e bloqueia solicitações para intervalos de IP privados.
Suporte de recursos Smithy para Gateway AgentCore
A tabela a seguir descreve os recursos do Smithy que são suportados e não suportados pelo Gateway:
| Recursos compatíveis | Recursos sem suporte |
|---|---|
|
Definições de serviço Definições de estrutura de serviço baseadas nas especificações da Smithy Definições de operação com input/output formas Definições de recursos Formas de características Protocolo de suporte de RestJson protocolo request/response Padrões HTTP padrão Tipos primitivos (string, inteiro, booleano, flutuante, duplo) Tipos complexos (estruturas, listas, mapas) Manipulação de carimbo de data/hora Tipos de dados de blob Associações básicas de métodos HTTP Associações de parâmetros de caminho simples Associações de parâmetros de consulta Associações de parâmetros de consulta Ligações de cabeçalho para casos simples Regras de endpoint A regra de endpoint define a determinação do endpoint em tempo de execução com base nas condições |
Protocolo Support RestXml Protocolo de JsonRpc AwsQuery protocolo Protocolo Ec2Query Protocolos personalizados Autenticação Vários tipos de autenticação de saída para APIs específicas Esquemas de autenticação complexos que exigem decisões em tempo de execução Operações Operações de streaming Operações que exigem implementações de protocolos personalizados |
Especificação do modelo Smithy
AgentCore O Gateway fornece modelos Smithy integrados para serviços comuns AWS . Para ver os modelos de AWS serviços da Smithy, consulte o repositório de modelos de AWS API
nota
AgentCore O Gateway não oferece suporte a modelos Smithy personalizados para não serviços.AWS
Depois de definir seu modelo Smithy, você pode fazer o seguinte:
-
Faça o upload para um bucket do Amazon S3 e consulte a localização do S3 ao adicionar o destino ao seu gateway.
-
Cole a definição em linha ao adicionar o destino ao seu gateway.
Expanda uma seção para ver exemplos de especificações de modelos Smithy compatíveis e não suportadas:
O exemplo a seguir mostra uma especificação de modelo Smithy válida para um serviço 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" } } } } } }
O exemplo a seguir mostra uma configuração inválida de regras de endpoint usando o 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"} } ] })
