Obiettivi del modello Smithy
Smithy è un linguaggio per definire servizi e kit di sviluppo software (SDK). I modelli Smithy forniscono un approccio più strutturato alla definizione delle API rispetto a OpenAPI e sono particolarmente utili per la connessione a AWS servizi come Gateway. AgentCore
Gli obiettivi del modello Smithy collegano il AgentCore gateway ai servizi definiti utilizzando i modelli API Smithy. Quando richiamate un target di gateway modello Smithy, il gateway traduce le richieste MCP in entrata in chiamate API che vengono inviate a questi servizi. Il gateway gestisce anche la formattazione della risposta.
Esamina le considerazioni e le limitazioni principali, incluso il supporto delle funzionalità, per aiutarti a decidere se un obiettivo Smithy è applicabile al tuo caso d'uso. In tal caso, puoi creare uno schema che segua le specifiche e quindi impostare le autorizzazioni affinché il gateway possa accedere alla destinazione. Per ulteriori informazioni, scegli un argomento:
Considerazioni e limitazioni principali
Quando utilizzi i modelli Smithy con AgentCore Gateway, tieni presente le seguenti limitazioni:
-
Dimensione massima del modello: 10 MB
-
Solo i collegamenti al protocollo JSON sono completamente supportati
-
È supportato solo il protocollo RestJson
Per prendere in considerazione l'utilizzo dei modelli Smithy con AgentCore Gateway, consulta la seguente tabella di supporto delle funzionalità.
Le migliori pratiche di sicurezza per la configurazione degli endpoint
avvertimento
Quando definisci le regole degli endpoint e gli URL dei server nei tuoi modelli Smithy, evita di utilizzare modelli di parametri URL eccessivamente permissivi che potrebbero esporre il gateway a rischi per la sicurezza.
I modelli Smithy supportano la configurazione dinamica degli endpoint tramite regole degli endpoint e parametri URL. Tuttavia, alcuni modelli possono introdurre vulnerabilità di sicurezza se non adeguatamente vincolati. In particolare, evita di utilizzare modelli completamente dinamici come:
-
Parametri di host o dominio senza restrizioni negli URL degli endpoint: o
https://{host}/api/v1https://{domain}.example.com -
Più segnaposti non vincolati negli URL dei server:
https://{subdomain}.{env}.{domain}.com -
Regole degli endpoint che consentono la costruzione arbitraria di URL senza convalida
Questi modelli possono essere potenzialmente sfruttati per:
-
Reindirizzare le richieste verso endpoint non intenzionali o dannosi
-
Accedi alle risorse di rete interne o ai servizi di metadati delle istanze (Request Forgery) Server-Side
-
Efiltra le credenziali IAM o i dati sensibili
Pratiche consigliate:
-
Usa URL di endpoint statici e completamente qualificati quando possibile
-
Per quanto riguarda AWS i servizi, affidatevi alla risoluzione standard degli endpoint con parametri regionali convalidati. Gateway applica la convalida AWS regionale per i servizi AWS
-
Se sono necessarie regole personalizzate per gli endpoint, vincola i parametri a valori specifici e convalidati
-
Evita di esporre i parametri grezzi dell'host o del dominio nella configurazione degli endpoint del tuo modello Smithy
Per le integrazioni AWS di servizi, AgentCore Gateway convalida automaticamente i parametri regionali e blocca le richieste verso intervalli IP privati.
Supporto delle funzionalità Smithy per Gateway AgentCore
La tabella seguente descrive le funzionalità di Smithy supportate e non supportate da Gateway:
| Caratteristiche supportate | Caratteristiche non supportate |
|---|---|
|
Definizioni dei servizi Definizioni della struttura dei servizi basate sulle specifiche di Smithy Definizioni delle operazioni con input/output forme Definizioni delle risorse Forme dei tratti Protocollo di supporto RestJson request/response Schemi HTTP Standard Tipi di dati Tipi di dati Tipi primitivi (string, integer, booleano, float, double) Tipi complessi (strutture, elenchi, mappe) Gestione del timestamp Tipi di dati Blob Associazioni ai metodi HTTP di base Associazioni dei parametri del percorso semplice Associazioni dei parametri di query Associazioni di intestazione per casi semplici Endpoint Rules La regola Endpoint imposta la determinazione dell'endpoint Runtime in base a condizioni |
Protocollo Protocollo di supporto RestXml JsonRpc AwsQuery protocollo Protocollo Ec2Query Protocolli personalizzati Autenticazione Tipi di autenticazione in uscita multipli per API specifiche Schemi di autenticazione complessi che richiedono decisioni di runtime Operazioni Operazioni di streaming Operazioni che richiedono implementazioni di protocolli personalizzate |
Specifiche del modello Smithy
AgentCore Gateway fornisce modelli Smithy integrati per servizi comuni. AWS Per vedere i modelli Smithy per i AWS servizi, consulta l'archivio API Models.AWS
Nota
AgentCore Gateway non supporta modelli Smithy personalizzati per prodotti diversi dai servizi.AWS
Dopo aver definito il modello Smithy, puoi eseguire una delle seguenti operazioni:
-
Caricalo in un bucket Amazon S3 e fai riferimento alla posizione S3 quando aggiungi la destinazione al gateway.
-
Incolla la definizione in linea quando aggiungi il target al gateway.
Espandi una sezione per vedere esempi di specifiche del modello Smithy supportate e non supportate:
L'esempio seguente mostra una specifica valida del modello Smithy per un servizio meteorologico:
{ "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" } } } } } }
L'esempio seguente mostra una configurazione delle regole degli endpoint non valida utilizzando 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"} } ] })
