Smithy model targets - Amazon Bedrock AgentCore
Key considerations and limitationsSmithy model specification

Smithy model targets

Smithy is a language for defining services and software development kits (SDKs). Smithy models provide a more structured approach to defining APIs compared to OpenAPI, and are particularly useful for connecting to AWS services, such as AgentCore Gateway.

Smithy model targets connect your AgentCore gateway to services that are defined using Smithy API models. When you invoke a Smithy model gateway target, the gateway translates incoming MCP requests into API calls that are sent to these services. The gateway also handles the response formatting.

Review the key considerations and limitations, including feature support, to help you decide whether a Smithy target is applicable to your use case. If it is, you can create a schema that follows the specifications and then set up permissions for the gateway to be able to access the target. Select a topic to learn more:

Key considerations and limitations

When using Smithy models with AgentCore Gateway, be aware of the following limitations:

  • Maximum model size: 10MB

  • Only JSON protocol bindings are fully supported

  • Only RestJson protocol is supported

In considering using Smithy models with AgentCore Gateway, review the following feature support table.

Smithy feature support for AgentCore Gateway

The following table outlines the Smithy features that are supported and unsupported by Gateway:

Smithy feature support
Supported Features Unsupported Features

Service Definitions

  • Service structure definitions based on Smithy specifications

  • Operation definitions with input/output shapes

  • Resource definitions

  • Trait shapes

Protocol Support

  • RestJson protocol

  • Standard HTTP request/response patterns

Data Types

  • Primitive types (string, integer, boolean, float, double)

  • Complex types (structures, lists, maps)

  • Timestamp handling

  • Blob data types

HTTP Bindings

  • Basic HTTP method bindings

  • Simple path parameter bindings

  • Query parameter bindings

  • Header bindings for simple cases

Endpoint Rules

  • Endpoint rule sets

  • Runtime endpoint determination based on conditions

Protocol Support

  • RestXml protocol

  • JsonRpc protocol

  • AwsQuery protocol

  • Ec2Query protocol

  • Custom protocols

Authentication

  • Multiple egress authentication types for specific APIs

  • Complex authentication schemes requiring runtime decisions

Operations

  • Streaming operations

  • Operations requiring custom protocol implementations

Smithy model specification

AgentCore Gateway provides built-in Smithy models for common AWS services. To see Smithy models for AWS services, see the AWS API Models repository.

Note

AgentCore Gateway doesn't support custom Smithy models for non-AWS services.

After you define your Smithy model, you can do one of the following:

  • Upload it to an Amazon S3 bucket and refer to the S3 location when you add the target to your gateway.

  • Paste the definition inline when you add the target to your gateway.

Expand a section to see examples of supported and unsupported Smithy model specifications:

The following example shows a valid Smithy model specification for a weather service:

namespace example.weather

use aws.protocols#restJson1
use smithy.framework#ValidationException

/// Weather service for retrieving weather information
@restJson1
service WeatherService {
    version: "1.0.0",
    operations: [GetCurrentWeather]
}

/// Get current weather for a location
@http(method: "GET", uri: "/weather")
operation GetCurrentWeather {
    input: GetCurrentWeatherInput,
    output: GetCurrentWeatherOutput,
    errors: [ValidationException]
}

structure GetCurrentWeatherInput {
    /// City name or coordinates
    @required
    @httpQuery("location")
    location: String,

    /// Units of measurement (metric or imperial)
    @httpQuery("units")
    units: Units = metric
}

structure GetCurrentWeatherOutput {
    /// Location name
    location: String,

    /// Current temperature
    temperature: Float,

    /// Weather conditions description
    conditions: String,

    /// Humidity percentage
    humidity: Float
}

enum Units {
    metric
    imperial
}

The following example shows an invalid endpoint rules configuration using 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"}
    }
  ]
})