As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
Metas 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 que são definidos usando modelos de API da Smithy. Quando você invoca um destino de gateway do modelo Smithy, o gateway traduz as solicitações de MCP recebidas em chamadas de API que são enviadas para esses serviços. O gateway também lida com 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 as 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 modelos Smithy com o AgentCore Gateway, esteja ciente das seguintes limitações:
-
Tamanho máximo do modelo: 10MB
-
Somente associações de protocolo JSON são totalmente suportadas
-
Somente o RestJson protocolo é suportado
Ao considerar o uso de modelos Smithy com o AgentCore Gateway, revise a tabela de suporte de recursos a seguir.
Práticas recomendadas de segurança para configuração de terminais
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 restringidos adequadamente. 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 nos URLs do servidor:
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 internos da rede ou serviços de metadados da 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 terminais com parâmetros de região validados. O Gateway impõe a validação AWS regional dos serviços AWS
-
Se forem necessárias regras personalizadas de endpoint, 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 com base 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 RestJson Protocolo de suporte request/response Padrões HTTP padrão Tipos de dados (string, inteiro, booleano, flutuante, duplo) Tipos complexos (estruturas, listas, mapas) Manipulação de data e hora Tipos de dados Blob Vinculações básicas de métodos HTTP Vinculações de parâmetros de caminho simples Vinculações de parâmetros de consulta Cabeçalho vinculações para casos simples Endpoint Rules Conjuntos de regras de endpoint Determinação de endpoints em tempo de execução com base nas condições |
Protocolo de suporte RestXml protocolo 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 protocolo personalizadas |
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 do modelo Smithy suportadas 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"} } ] })
