yaalalabs/agent-kernel/ak-cloud-deploy

Deploy to Cloud

Use this skill to deploy your Agent Kernel project to AWS, Azure, or GCP.

Instructions for the Agent

When the user wants cloud deployment, follow this workflow.

Step 1: Identify the Project

Check for:

• pyproject.toml with agentkernel dependency
• agent entry file (app.py, lambda.py, or similar)
• config.yaml

If missing, suggest ak-init first.

Step 2: Ask Deployment Questions

1. Target platform: AWS, Azure, GCP, or Kubernetes (on-prem / baremetal / EKS via the Helm chart; see the On-Prem / Kubernetes section)?
2. Runtime mode:

• Serverless
• Containerized

1. Execution pattern (AWS only):

• Synchronous HTTP (rest_sync, supports standard or queue/scalable mode; AWS serverless or containerized)
• Asynchronous REST (rest_async, queue/scalable mode; AWS serverless or containerized)
• WebSocket full-response (async with message_type unset or complete, works with or without queue mode — queue_mode = false runs the agent inline, queue_mode = true enqueues to a separately-scalable Agent Runner) — AWS serverless or AWS containerized/ECS
• WebSocket token streaming (async with message_type = "delta", works with or without queue mode, same as async above) — AWS serverless or AWS containerized/ECS; also available via SSE (POST /api/v1/chat with execution.mode: rest_sync and execution.message_type: delta, no Terraform changes required) wherever the built-in FastAPI REST server runs: local/self-hosted, AWS ECS single-container (non-queue) REST, Azure Container Apps, GCP Cloud Run — not on AWS Lambda or ECS queue mode (both refuse rest_sync + delta at startup; use async + delta there) or Azure Functions. The old stream mode was removed: execution_mode = "stream" fails at terraform plan and execution.mode: stream fails at config load

1. Scalability (AWS serverless only): standard or queue/scalable mode?
2. Session store: Redis, Valkey (AWS only), DynamoDB (AWS), Cosmos DB (Azure), Firestore (GCP)?
3. Security: custom authorizer required (AWS serverless only)?
4. Resource naming: a single prefix applied to every resource name (e.g. myapp-dev-chat).

Step 3: Choose the Correct Terraform Module

Use official modules:

• AWS serverless: yaalalabs/ak-serverless/aws
• AWS containerized: yaalalabs/ak-containerized/aws
• Azure serverless: yaalalabs/ak-serverless/azurerm
• Azure containerized: yaalalabs/ak-containerized/azurerm
• GCP serverless: yaalalabs/ak-serverless/google
• GCP containerized: yaalalabs/ak-containerized/google

Use current module version (0.9.5) unless user requests another.

Kubernetes does not use Terraform: the Helm chart lives at ak-deployment/ak-k8s/chart in the Agent Kernel repository and is published as an OCI artifact (oci://ghcr.io/yaalalabs/charts/agent-kernel, versioned with each release). Install the published chart, as in the Kubernetes section below, not a repository checkout.

All modules are provider-agnostic: they declare required_providers but do not configure them internally. Configure each provider (aws/docker, azurerm, or google/google-beta/docker) in the root module and pass it explicitly via the module's providers = { ... } argument, as shown in the examples below. Azure's containerized module builds and pushes its image via a nested submodule with its own internal docker provider, so no docker provider needs to be configured or passed by the caller there.

AWS-only features in this skill:

• execution_mode / message_type (Terraform inputs; execution.message_type itself is plain Agent Kernel config)
• queue_mode
• authorizer

Azure examples use the provider module's standard top-level inputs (function_name, package_path, container_port, publisher_email) rather than AWS serverless execution modes.

GCP modules use Cloud Run for both serverless (scale-to-zero, min_instance_count=0) and containerized (always-on, min_instance_count≥1) modes. Both use agentkernel.gcp.CloudRun as the entry point.

Step 4: Align App Dependencies and Session Config

When the user selects a session store, always update both app dependencies and config.yaml.

Redis sessions

• Dependency extras: include redis
• Typical dependency example:

dependencies = [
  "agentkernel[openai,api,redis]>=0.9.5"
]

• config.yaml session block:

session:
  type: redis
  namespace: chat
  redis:
    host: ${REDIS_HOST}
    port: 6379
    db: 0

Valkey sessions (AWS)

Valkey is the open-source, Linux Foundation-governed fork of Redis. It is wire-compatible with Redis and available on AWS ElastiCache at a lower price point than the Redis OSS engine. Agent Kernel treats it as a first-class session and response store backend on AWS.

• Dependency extras: include valkey
• Typical dependency example:

dependencies = [
  "agentkernel[openai,api,aws,valkey]>=0.9.5"
]

• config.yaml session block:

session:
  type: valkey
  valkey:
    url: ${AK_SESSION__VALKEY__URL}  # valkeys:// for SSL
    ttl: 604800
    prefix: "ak:sessions:"

• Terraform provisions the cluster with create_valkey_cluster = true (serverless and

containerized) and injects AK_SESSION__VALKEY__URL — session.type: valkey must still be set in config.yaml since the type itself is never injected.

• For queue-mode response storage, set create_valkey_response_store = true (serverless only) and

execution.response_store.type: valkey in config.yaml.

DynamoDB sessions (AWS)

• Dependency extras: include aws
• Typical dependency example:

dependencies = [
  "agentkernel[openai,api,aws]>=0.9.5"
]

• config.yaml session block:

session:
  type: dynamodb
  dynamodb:
    table_name: ${DYNAMODB_MEMORY_TABLE}
    region: ${AWS_REGION}

Cosmos DB sessions (Azure)

• Dependency extras: include azure
• Typical dependency example:

dependencies = [
  "agentkernel[openai,api,azure]>=0.9.5"
]

• config.yaml session block:

session:
  type: cosmosdb
  cosmosdb:
    endpoint: ${AZURE_COSMOS_ENDPOINT}
    database_name: ${AZURE_COSMOS_DATABASE}
    container_name: ${AZURE_COSMOS_CONTAINER}

Firestore sessions (GCP)

• Dependency extras: include gcp
• Typical dependency example:

dependencies = [
  "agentkernel[openai,api,gcp]>=0.9.5"
]

• config.yaml session block:

session:
  type: firestore
  firestore:
    collection_name: ${AK_SESSION__FIRESTORE__COLLECTION_NAME}
    project_id: ${PROJECT_ID}
    ttl: 604800

• The Terraform module injects AK_SESSION__TYPE=firestore and AK_SESSION__FIRESTORE__COLLECTION_NAME automatically when Firestore is enabled.
• A TTL policy must be set on the Firestore collection pointing to the expiry_time field for automatic document expiry.

If the Terraform module creates the backing store (for example create_redis_cluster = true, create_valkey_cluster = true, or create_dynamodb_memory_table = true), make sure output values are wired to the app environment variables used by config.yaml.

Deploying Conversation Thread Storage

Conversation threads (ak-add-capabilities) deploy the same way sessions do: the app mounts AgentThreadRequestHandler (which is what enables the feature; the self-hosted REST API is the only surface that records threads — queue-mode runners and the other deployment adapters do not) and declares thread.type in config.yaml, and Terraform provisions the backend, injecting only the connection detail. Terraform never sets AK_THREAD__TYPE itself.

• AWS (serverless + containerized): create_dynamodb_thread_table = true provisions a DynamoDB

table (partition session_id, sort sk, TTL on expiry_time) and injects AK_THREAD__DYNAMODB__TABLE_NAME.

• GCP (serverless + containerized): create_firestore_thread_collection = true requires

create_firestore_database = true, reuses that database, and injects AK_THREAD__FIRESTORE__COLLECTION_NAME, __PROJECT_ID, and __DATABASE_ID. No new resource is provisioned — the collection is created on first write.

• Redis / Valkey: no dedicated Terraform flag — reuse whatever create_redis_cluster /

create_valkey_cluster already provisions and declare thread: {type: redis} (or valkey) with the cluster URL in config.yaml.

Setting the Terraform flag without declaring thread.type in config.yaml silently leaves threads on the non-durable in-memory backend (any AK_THREAD__* var materialises AKConfig.thread, but type still defaults to in_memory) — always pair the flag with the matching thread.type.

Deploying Scheduled Tasks

Scheduled tasks (ak-add-capabilities) deploy on the same two-step split: the app declares schedule.provider.type and schedule.store.type in config.yaml, and Terraform provisions the backends, injecting only the coordinates. Terraform never sets AK_SCHEDULE__PROVIDER__TYPE or AK_SCHEDULE__STORE__TYPE.

Scheduling requires queue mode — occurrences are delivered into the input queue, so queue_mode = true is mandatory on AWS. enable_scheduling without it is rejected.

• AWS (serverless + containerized): enable_scheduling = true provisions an EventBridge Scheduler

schedule group and the execution role Scheduler assumes to deliver triggers to the input queue, grants both the request/REST role and the agent-runner role scheduler:CreateSchedule|UpdateSchedule|DeleteSchedule|GetSchedule plus iam:PassRole on that role, and injects AK_SCHEDULE__PROVIDER__EVENTBRIDGE__GROUP_NAME, __ROLE_ARN and __QUEUE_ARN. It also flips the input queue to content-based deduplication, because Scheduler cannot set a MessageDeduplicationId (application senders are unaffected — their explicit id takes precedence).

• AWS (serverless + containerized): create_dynamodb_schedule_table = true provisions a DynamoDB

table (partition task_id, no sort key, no GSI, TTL on expiry_time) and injects AK_SCHEDULE__STORE__DYNAMODB__TABLE_NAME.

• Redis / Valkey task store: no dedicated Terraform flag — reuse whatever create_redis_cluster /

create_valkey_cluster already provisions and declare schedule: {store: {type: redis}} (or valkey) with the cluster URL in config.yaml.

• Azure / GCP: no scheduling provider ships for these clouds yet. The local provider only works

in a single always-on process with the in_memory transport and store, which no cloud deployment mode gives you.

queue_mode                     = true
enable_scheduling              = true
create_dynamodb_schedule_table = true

schedule:
  provider:
    type: eventbridge
  store:
    type: dynamodb

Setting the Terraform flags without declaring both types in config.yaml silently leaves scheduling on the in-process local provider and in_memory store (any AK_SCHEDULE__* var materialises AKConfig.schedule, but the types still default), while the provisioned group and table sit unused — always pair the flags with the matching types. The reverse is safe: declaring the types without the flags fails at startup with an AKConfigError on the missing group_name / role_arn / queue_arn.

The blocks above enable deferring and the agent tools. The /api/v1/schedules management routes are not mounted from config — on ECS queue mode, pass the handler to the IO container's entrypoint, where it is served alongside the queue-producing chat route:

# app_rest_service.py
from agentkernel.aws import ECSIOHandler
from agentkernel.schedule import ScheduleRESTRequestHandler
if __name__ == "__main__":
    # add authoriser=... to scope listings to the caller; without one the routes are open
    ECSIOHandler.run(handlers=[ScheduleRESTRequestHandler()])

Remember to list the schedule paths in gateway_endpoints — the gateway only proxies paths it is told about.