The API template provides a serverless API service built with SST. It follows a clean architecture pattern designed for scalability and maintainability.

You can find the full source code for the API template here.

​
Project Structure

agentic-api-template/
|-- infra/                           # Infrastructure definitions
|   |-- api.ts                       # API Gateway configuration
|   |-- database.ts                  # DynamoDB tables
|   |-- queues.ts                    # SQS queues
|   |-- topics.ts                    # SNS topics
|-- packages/                        # Core packages directory
|   |-- core/                        # Core business logic
|   |   |-- src/
|   |   |   |-- agent-plane/         # Agent-related functionality
|   |   |   |-- control-plane/       # User, Billing, Settings
|   |   |   `-- orchestrator/        # Orchestration logic
|   |   `-- package.json
|   |
|   |-- functions/                   # Lambda function handlers
|   |   |-- src/
|   |   |   |-- agent-plane.api.ts   # Agent handlers
|   |   |   |-- control-plane.api.ts # User/billing handlers
|   |   |   `-- orchestrator.api.ts  # API Gateway entry points
|   |   `-- package.json
|   |
|   `-- utils/                       # Shared utilities
|       |-- src/
|       |   |-- metadata/            # Schema definitions
|       |   |-- tools/               # Core utilities
|       |   `-- vendors/             # Third-party integrations
|       `-- package.json
|
|-- sst.config.ts                    # SST configuration
|-- .env.*                           # Environment configurations

Let’s explore the key components of the API template:

  1. Core Package (/packages/core)

The core package follows a clean architecture pattern with three main modules:

/core/src/
|-- agent-plane/ 
|   |-- agent/            # Top level agent module
|   |   |-- adapters/     # Interface adapters
|   |   |-- metadata/     # Business metadata
|   |   `-- usecases/     # Business logic
|-- control-plane/        # User and billing modules
|   |-- adapters/         # Interface adapters
|   |-- metadata/         # Business metadata
|   `-- usecases/         # Business logic
|
|-- orchestrator/         # Request orchestration
|   |-- adapters/         # Interface adapters
|   |-- metadata/         # Business metadata
|   `-- usecases/         # Business logic
  1. Functions Package (/packages/functions)

Lambda functions that handle API requests:

/functions/src/
|-- agent-plane.api.ts    # Agent-related endpoints
|-- control-plane.api.ts  # User/billing endpoints
|-- orchestrator.api.ts   # API Gateway handlers
  1. Utils Package (/packages/utils)

Shared utilities and tools:

/utils/src/
|-- metadata/            # Schema definitions
|   |-- agent.cost.ts
|   |-- apikey.schema.ts
|   |-- credit.schema.ts
|
|-- tools/              # Core utilities
|   |-- ai-middleware.ts
|   |-- api-key-manager.ts
|   |-- credit-manager.ts
|   |-- custom-error.ts
|   |-- custom-handler.ts
|   |-- http-status.ts
|   |-- retry.ts
|   |-- saas-identity.ts
|-- vendors/            # Third-party integrations
|   |-- api-key-vendor.ts
|   |-- jwt-vendor.ts

​
Environment Configuration

​
Development

Create a .env.sandbox file:

# Authentication
CLERK_SECRET_KEY=<clerk_secret_key>
UNKEY_API_KEY=<unkey_api_key>
UNKEY_ROOT_KEY=<unkey_root_key>

# Infrastructure
AWS_ACCESS_KEY_ID=<aws_access_key>
AWS_SECRET_ACCESS_KEY=<aws_secret_key>
AWS_REGION=us-east-1

# Payments
STRIPE_SECRET_KEY=<stripe_secret_key>
STRIPE_WEBHOOK_SECRET=<stripe_webhook_secret>

# AI Services
OPENAI_API_KEY=<openai_api_key>

# Domain Configuration
DOMAIN_NAME=<domain_name>
CLOUDFLARE_API_TOKEN=<cloudflare_token>

​
SST Configuration

The API template uses SST for deployment and infrastructure management. The configuration is defined in sst.config.ts:

​
1. App Configuration

export default $config({
  app(input) {
    return {
      name: "agentic-api-template",
      removal: input?.stage === "prod" ? "retain" : "remove",
      home: "aws",
      providers: { 
        aws: {
          region: "us-east-1",
        }, 
        "aws-native": {
          region: "us-east-1",
        }, 
        cloudflare: {
          version: "5.42.0",
          apiToken: process.env.CLOUDFLARE_API_TOKEN,
        }
      },
    };
  }
});
  • name: Defines the app name used to prefix resources
  • removal: Retains resources in production, removes them in other stages
  • home: Uses AWS as the primary provider
  • providers: Configures AWS and Cloudflare settings

​
2. Infrastructure Configuration

The infrastructure is modularly defined in the /infra directory and imported into the SST config:

async run() {
  const infra = await import("./infra");
  return {
    api: infra.api.url,
  };
}

​
3. Auto-deployment Configuration

The autodeploy configuration manages deployment rules for different branches:

console: {
  autodeploy: {    
    target(event) {      
      if (event.type === "branch" && event.branch != "main" && event.action === "pushed") {        
        return {          
          stage: event.branch,          
          runner: { 
            engine: "codebuild", 
            compute: "large",
            architecture: "arm64" 
          }        
        };      
      }   
      if (event.type === "branch" && event.branch === "main" && event.action === "pushed") {
        return {
          stage: "prod",
          runner: {
            engine: "codebuild",
            compute: "large",
            architecture: "arm64"
          }
        };
      }
    }  
  }
}

Defines automatic deployment rules:

  • main branch → prod stage
  • Other branches → stage named after branch

Each deployment uses CodeBuild with:

  • Large compute resources
  • ARM64 architecture for better performance
  • Automatic stage naming based on branch

​
Running Tests Locally

  1. Create a .env.test file with test credentials:
TEST_AUTH_TOKEN=<test_auth_token>
OPENAI_API_KEY=<test_openai_api_key>
API_URL=https://sandbox-api.yourdomain.com/v1/
  1. Run the test suite:
yarn test

​
Deployment

The API template supports multiple deployment options:

​
SST Deployment

# Deploy to sandbox
sst deploy --stage sandbox

Deployment to production is handled by SST Autodeploy when merging to the main branch.

This set up is a modified version of the SST Monorepo setup.

For more details on SST configuration options, refer to the SST Config Documentation.

Was this page helpful?