Gateway Configuration

A Gateway exposes tools that AI agents can discover and invoke -- Lambda functions, OpenAPI endpoints, Smithy models, or external MCP servers. This allows agents to call your custom business logic, access databases, integrate with APIs, and more.

Quick Start

Define tools in ai.tools and they become available to your agents automatically:

service: my-agent

provider:
  name: aws
  region: us-east-1

functions:
  calculatorFunction:
    handler: handlers/calculator.handler
    runtime: python3.13

ai:
  tools:
    calculator:
      function: calculatorFunction
      toolSchema:
        - name: calculate
          description: Evaluate a mathematical expression
          inputSchema:
            type: object
            properties:
              expression:
                type: string
                description: Mathematical expression to evaluate (e.g., "2 + 2 * 3")
            required:
              - expression

  agents:
    chatbot: {}

The Serverless Framework automatically:

Creates a default gateway with all tools attached
Injects BEDROCK_AGENTCORE_GATEWAY_URL into your agent's environment
Configures IAM permissions for tool invocation

How It Works

When you define tools, the framework creates an AgentCore Gateway that:

Discovers Tools: Your agent receives a BEDROCK_AGENTCORE_GATEWAY_URL environment variable
Exposes via MCP: Tools are exposed using the Model Context Protocol (MCP)
Invokes Target: When the agent calls a tool, the gateway invokes the target (Lambda function, API endpoint, or MCP server)
Returns Results: Results flow back to the agent for processing

Agent → Gateway (MCP) → Target (Lambda / API / MCP Server) → Response

Tool Types

Lambda Function Tools

The most common tool type. Wrap your Lambda functions as agent tools:

functions:
  myFunction:
    handler: handler.main
    runtime: python3.13

ai:
  tools:
    myTool:
      function: myFunction
      toolSchema:
        - name: do_something
          description: Performs a specific action
          inputSchema:
            type: object
            properties:
              input:
                type: string
            required:
              - input

Lambda Function Reference:

Format	Description
`function: myFunction`	Reference to `functions.myFunction`
`function: { name: myFunction }`	Explicit name reference
`function: { arn: arn:aws:lambda:... }`	External Lambda ARN

OpenAPI Tools

Expose HTTP APIs as tools using OpenAPI specifications:

ai:
  tools:
    weatherApi:
      openapi: ./weather-openapi.yml

Smithy Model Tools

Define tools using Smithy interface definitions:

ai:
  tools:
    myApi:
      smithy: ./my-api.smithy

MCP Server Tools

Connect to external MCP servers:

ai:
  tools:
    externalTool:
      mcp: https://my-mcp-server.example.com/mcp

Tool Schema

The toolSchema defines how the agent understands and invokes your tool:

ai:
  tools:
    search:
      function: searchFunction
      toolSchema:
        - name: search_products
          description: Search the product catalog by query
          inputSchema:
            type: object
            properties:
              query:
                type: string
                description: Search query text
              category:
                type: string
                description: Optional product category filter
              maxResults:
                type: integer
                description: Maximum number of results (default 10)
            required:
              - query

Property	Required	Description
`name`	Yes	Tool name the agent uses to invoke it
`description`	Yes	What the tool does (helps LLM decide when to use it)
`inputSchema`	Yes	JSON Schema defining input parameters
`outputSchema`	No	JSON Schema defining output parameters

Tool Credentials

By default, tools use GATEWAY_IAM_ROLE credentials -- no extra configuration needed. For tools that need authentication when calling external APIs, configure OAuth or API Key credentials:

OAuth Credentials:

ai:
  tools:
    spotify:
      openapi: ./spotify-openapi.yml
      credentials:
        type: OAUTH
        provider: arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/spotify
        grantType: AUTHORIZATION_CODE
        scopes:
          - playlist-read-private
        defaultReturnUrl: https://myapp.com/callback
        customParameters: # Optional: additional OAuth parameters
          access_type: offline

API Key Credentials:

ai:
  tools:
    weather:
      openapi: ./weather-api.yml
      credentials:
        type: API_KEY
        provider: arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/weather-key
        location: HEADER
        parameterName: X-API-Key
        prefix: Bearer # Optional: value prefix (e.g., "Bearer" for Authorization header)

Credential types:

Type	Description
`GATEWAY_IAM_ROLE`	Default -- uses the gateway's IAM role (no config)
`OAUTH`	OAuth 2.0 via AgentCore Token Vault
`API_KEY`	API key via AgentCore Token Vault

Multiple Gateways

For advanced scenarios where you need different authorization levels or tool subsets, define explicit gateways:

ai:
  tools:
    calculator:
      function: calculatorFunction
      toolSchema: [...]

    internalLookup:
      function: internalLookupFunction
      toolSchema: [...]

  gateways:
    publicGateway:
      authorizer: NONE
      tools:
        - calculator

    privateGateway:
      authorizer: AWS_IAM
      tools:
        - internalLookup

  agents:
    publicAgent:
      gateway: publicGateway

    privateAgent:
      gateway: privateGateway

Gateway Authorization Options

Type	Description
`NONE`	No authentication required
`AWS_IAM`	AWS IAM authentication (SigV4)
`CUSTOM_JWT`	JWT token validation

JWT Authorization:

ai:
  gateways:
    secureGateway:
      authorizer:
        type: CUSTOM_JWT
        jwt:
          discoveryUrl: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxx/.well-known/openid-configuration
          allowedAudience:
            - my-client-id
          allowedScopes:
            - openid
      tools:
        - protectedTool