> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Deploy a serverless endpoint to AWS Lambda
description: Package a Python AGNT5 endpoint with Lambda Web Adapter, publish an immutable version, and sync its Function URL.
last_verified: 2026-07-31
---

AWS Lambda Web Adapter runs a normal HTTP application inside Lambda. The AGNT5 scaffold packages FastAPI and the Web Adapter in a container image, so the Python serverless protocol does not need a Lambda-specific handler.

This integration is preview. The generated image passes a local container smoke, but you must validate the deployed function, URL policy, timeout, and secret configuration in your AWS account.

## 1. Generate the application

```bash
agnt5 serverless init \
  --provider aws-lambda \
  --runtime python \
  --name orders-api

uv add agnt5 fastapi uvicorn
```

The command creates:

- `agnt5_serverless.py`: the FastAPI protocol application.
- `Dockerfile.agnt5-lambda`: a Python 3.13 image with Lambda Web Adapter `1.0.0`.

The application reads `AWS_LAMBDA_FUNCTION_VERSION` as its service version.

## 2. Build the image

```bash
docker build \
  --file Dockerfile.agnt5-lambda \
  --tag orders-api:local \
  .
```

The Dockerfile configures the Web Adapter readiness path as `/.well-known/agnt5` and starts Uvicorn on port `8080`.

Push the image to an Amazon ECR repository in the same Region as the Lambda function. Create or update a Lambda function with package type `Image` and the pushed image URI.

## 3. Configure signing and timeout

1. Set `AGNT5_SERVERLESS_SIGNING_SECRET` in the Lambda function configuration from your protected deployment pipeline.
2. Set the Lambda timeout above the AGNT5 request timeout.
3. Publish a numbered Lambda version after the image and environment configuration are final.
4. Point a Lambda alias, such as `production`, at that published version.

Use the numbered version or image digest as the immutable reference in AGNT5.

## 4. Create the Function URL

Create the Function URL on the published alias with `AuthType NONE`. When you use the AWS CLI, add both resource-policy permissions required by [AWS Function URL access control](https://docs.aws.amazon.com/lambda/latest/dg/urls-auth.html).


> AGNT5 does not sign outbound endpoint requests with AWS SigV4. `AWS_IAM` Function URLs are not supported yet. With `AuthType NONE`, the manifest route is public and the invoke route relies on the AGNT5 HMAC secret.


Do not route the URL to `$LATEST`. A URL attached to an alias preserves the published code version used by an in-flight AGNT5 run.

## 5. Validate and sync

```bash
export ENDPOINT="https://<function-url-id>.lambda-url.<region>.on.aws"
export LAMBDA_VERSION="<published-version>"
export AGNT5_SERVERLESS_SIGNING_SECRET="<same-secret-configured-in-lambda>"

agnt5 serverless validate "$ENDPOINT"

agnt5 serverless sync "$ENDPOINT" \
  --provider aws-lambda \
  --immutable-ref "$LAMBDA_VERSION" \
  --signing-secret-env AGNT5_SERVERLESS_SIGNING_SECRET \
  --activate=false
```

Run **`agnt5 serverless status --deployment-id <deployment-id> --verify`** before activation.

## Next steps

- [Serverless support matrix](/docs/run/serverless-support-matrix.md): review the Lambda evidence level and authentication gap.
- [Integrate Python web frameworks](/docs/integrations/python-web-frameworks.md): reuse the protocol adapter in an existing Python service.
- [Operate serverless endpoints](/docs/run/operate-serverless-endpoints.md): promote and recover immutable releases.
- [Serverless protocol reference](/docs/run/serverless-protocol.md): inspect HMAC headers and response envelopes.