info
The following example shows the general structure of how to build an AWS Lambda function. For concrete implementations of agents with specific abilities, see the examples section.
There are two different ways in which you can create lambda functions.
- Using a zip upload
- Using a Docker container
They have different applications and properties.
Before you dive into one of the examples, please consider the properties in the table below.
Type | File size limits | Ease of use |
---|
Zip upload | 50MB (250MB unzipped) | easier |
Docker | NA | harder |
AWS Lambda zip deployments have a 50MB (250MB uncompressed) size limit. This often forces the use of Docker for agents with larger dependencies, such as computer vision libraries (pip install encord-agents[vision]
). Additionally, dependencies relying on C/C++ code require specific CPU architecture installations, often making testing only possible after deployment.
More detailed AWS Documentation on python lambda functions can be found here.
Building a lambda function using zip upload
The full AWS lambda documentation for zip files is available here.
STEP 1: Create a local Project
To begin, set up your local project structure. This includes creating two directories, a virtual environment (for example venv
), and a package directory for CPU-architecture-specific dependencies tailored to your cloud infrastructure.
- Create your virtual environment and install
encord-agents
. Refer to the installation docs for detailed instructions.
mkdir my_project
cd my_project
python -m venv venv
source venv/bin/activate
pip install encord-agents
deactivate
- Create the “mirror” package directory for the upload.
We recommend explicitly installing boto3
, the AWS SDK, even though it’s typically present in Lambda environments. This ensures consistent dependency versions and avoids unexpected changes when AWS updates its infrastructure.
mkdir package
pip install \
--platform manylinux2014_x86_64 \
--target=package \
--implementation cp \
--python-version 3.12 \
--only-binary=:all: --upgrade \
encord-agents boto3
STEP 2: Define the agent
- Create a
lambda_function.py
file using the following template:
from encord.objects.ontology_labels_impl import LabelRowV2
from encord_agents.core.data_model import FrameData
from encord_agents.aws import editor_agent
@editor_agent()
def lambda_handler(frame_data: FrameData, label_row: LabelRowV2) -> None:
print(frame_data.model_dump_json())
# label_row.save()
Make sure to name your file lambda_function.py
and your function lambda_handler
if you are following this example, as these names are referenced in the --handler
argument in Step 6.
- Complete the
lambda_handler
function with the logic you want to execute when the agent is triggered.
STEP 3: (Optional) Test the Agent Locally
We are testing against the venv
and not the package
that is uploaded to AWS, so we might see slight differences in the outcome.
- In order to test your agent locally, you can add an
if __name__ == "__main__"
declaration in the end of the file as follows:
# ... imports from before
@editor_agent()
def lambda_handler(frame_data: FrameData):
print(frame_data.model_dump_json())
if __name__ == '__main__':
event = {
"body": {
"projectHash": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"dataHash": "00000000-1111-2222-3333-444444444444",
"frame": 0,
"objectHashes": []
}
}
lambda_handler(event, None)
- Make sure to update the Project and data hash to correspond to one of your data units.
If you open the label editor in your browser and look at the url, it has this pattern:
https://app.encord.com/label_editor/{projectHash}/{dataHash}
- Run the file:
source venv/bin/activate
export ENCORD_SSH_KEY_FILE='/path/to/your/private-key-file'
python lambda_function.py
STEP 4: Create the ZIP file
- Create the zip file by first zipping what is in the
package
directory:
cd package
zip -r ../package.zip .
cd ..
- Add your lambda function to the zip file:
zip package.zip lambda_function.py
STEP 5: Set up an execution role
Your Lambda function requires an execution role to define the permissions it needs to run.
- Create the configuration file
trust-policy.json
to be uploaded to AWS.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
- Create a role with the trust policy:
aws iam create-role \
--role-name lambda-execute-encord-agents \
--assume-role-policy-document file://trust-policy.json
It should output a JSON similar to the following. Make sure to take a note of the Arn
.
{
"Role": {
"Path": "/",
"RoleName": "lambda-execute-encord-agents",
"RoleId": "AROAQ7BEARV2DSFT2E3PI",
"Arn": "arn:aws:iam::061234567890:role/lambda-execute-encord-agents",
"CreateDate": "2025-05-09T10:39:35+00:00",
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
}
}
- Attach the basic lambda execution role to the role.
aws iam attach-role-policy \
--role-name lambda-execute-encord-agents \
--policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
STEP 6: Upload the zip
- To upload the zip file to AWS, use the following command. Make sure to insert the
<lambda_function_name>
you want to use and the proper role Arn
from STEP 5.
aws lambda create-function --function-name <lambda_function_name> \
--runtime python3.12 \
--handler lambda_function.lambda_handler \
--role arn:aws:iam::061234567890:role/lambda-execute-encord-agents \
--zip-file fileb://package.zip
If you want to modify your lambda, follow the steps above again but call the update method rather than the create-function
from the AWS CLI.
aws lambda update-function-code \
--function-name <lambda_function_name> \
--zip-file fileb://package.zip
- Proceed to Step A below to complete the setup.
Building a Lambda Function with Docker
The full AWS documentation for building docker images for lambda functions with Python is available here.
STEP 1: Create a Local Project
Start by creating a local project directory.
mkdir my_project
cd my_project
Then add a requirements.txt
file.
(Optional) local environment
If you want, you can create a local environment for testing before building the docker image.
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
STEP 2: Define the Agent
- Create a
lambda_function.py
file using the following template:
from encord.objects.ontology_labels_impl import LabelRowV2
from encord_agents.core.data_model import FrameData
from encord_agents.aws import editor_agent
@editor_agent()
def lambda_handler(frame_data: FrameData, label_row: LabelRowV2) -> None:
print(frame_data.model_dump_json())
# label_row.save()
Make sure to name your file lambda_function.py
and your function lambda_handler
if you’re following this example, as these names are referenced in the Docker image in the next step.
Complete the lambda_handler
function with the logic you want to execute when the agent is triggered.
You can find multiple examples of what can be done with editor agents here.
STEP 3: Build the Docker Image
- Create a
Dockerfile
with the following content.
FROM public.ecr.aws/lambda/python:3.12
# Install the specified packages
COPY requirements.txt ${LAMBDA_TASK_ROOT}
RUN pip install -r requirements.txt
# Copy function code
COPY lambda_function.py ${LAMBDA_TASK_ROOT}
# Set the CMD to your handler
# (could also be done as a parameter override outside of the Dockerfile)
CMD [ "lambda_function.lambda_handler" ]
- Build the image locally.
You need to have docker
and buildx
installed.
docker buildx build \
--platform linux/amd64 \
--provenance=false \
-t encord-agents-my-agent-name:latest \
.
STEP 4: (Optional) Test the agent locally
To test the agent locally, you can spin up the container with the following command.
docker run \
-e ENCORD_SSH_KEY="$(cat /path/to/your/private-key-file)" \
-p 9000:8080 \
--platform linux/amd64 \
-t encord-agents-my-agent-name:latest
The respective lines ensures that we
- Add the
ENCORD_SSH_KEY
env variable
- Map the port 8080 to your own local port (9000 in this example)
- AWS architecture needs to be
amd64
(or arm64
see aws docs)
- Run the latest built image (
encord-agents-example:latest
in this example)
You can “hit” the function endpoint with a curl
command. The functions/function/invocation
path is required by Amazon.
curl "http://localhost:9000/2015-03-31/functions/function/invocations" \
-X "POST" \
-d '{
"body": {
"projectHash": "aaaaaaaa-ed79-4a1b-a0c1-b1b38ffb523c",
"dataHash":"659c3a38-737f-4f56-a709-26ce01f5fd0b",
"frame": 0,
"objectHashes": []
}
}'
There is a long-standing issue with Lambda Docker containers where the API differs between local and cloud execution. In this case, two relevant distinctions exist.
Content-Type
: Locally, the container expects a post request with Content-Type: application/x-www-form-urlencoded
while the public url hosted by AWS expects Content-Type: application/application-json
.
POST
data: Locally, the post data needs to be {"body": {... content dict}}
while the public url expects {... content dict}
.
As a consequence, the equivalent curl
request for a publicly hosted lambda function would be:
curl "https://<your_function_url_prefix>.lambda-url.eu-west-1.on.aws/" \
-X "POST" \
-H "Content-Type: application/json" \
-d '{
"projectHash": "aaaaaaaa-ed79-4a1b-a0c1-b1b38ffb523c",
"dataHash":"659c3a38-737f-4f56-a709-26ce01f5fd0b",
"frame": 0,
"objectHashes": []
}'
See the Function URL section for more information on how to get the public endpoint.
Step 5: Prepare ECR Container Repository
To associate a Lambda function with your container, the container must first be uploaded to the AWS Elastic Container Registry (ECR). For this, a container repository is required.
- Run the
aws get-login-password
command to authenticate the Docker CLI to your Amazon ECR registry.
- Set the
--region
value to the AWS Region where you want to create the Amazon ECR repository (we use eu-west-1
in this example).
- Replace 111122223333 with your AWS account ID.
aws ecr get-login-password --region eu-west-1 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.eu-west-1.amazonaws.com
- Create a repository in Amazon ECR using the create-repository command.
aws ecr create-repository \
--repository-name <your-lambda-function-name> \
--region us-east-1 \
--image-scanning-configuration scanOnPush=true \
--image-tag-mutability MUTABLE
If successful, you see a response with the following format:
{
"repository": {
"repositoryArn": "arn:aws:ecr:us-east-1:111122223333:repository/<your-lambda-function-name>",
"registryId": "111122223333",
"repositoryName": "<your-lambda-function-name>",
"repositoryUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/<your-lambda-function-name>",
"createdAt": "2025-05-12T10:39:01+00:00",
"imageTagMutability": "MUTABLE",
"imageScanningConfiguration": {
"scanOnPush": true
},
"encryptionConfiguration": {
"encryptionType": "AES256"
}
}
}
Copy the repositoryUri
from the output.
Step 6: Upload the Local Docker Image
- To tag your local Docker image for Amazon ECR as the latest version, use the
docker tag
command:
encord-agents-my-agent-name:latest
is the name and tag of your local Docker image. This is the image name and tag that you specified in the docker build
command above.
- Replace
<ecr-repository-uri>
with the repositoryUri
that you copied above. Make sure to include :latest
at the end of the URI.
docker tag encord-agents-my-angent-name:latest <ecr-repository-uri>:latest
- Run the
docker push
command to deploy your local image to the Amazon ECR repository. Ensure you include :latest
at the end of the repository URI.
docker push 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest
STEP 7: Set up an Execution Role
Your Lambda function requires an execution role to define the permissions it needs to run.
- Create the configuration file
trust-policy.json
to be uploaded to AWS.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
- Create a role with the trust policy.
aws iam create-role \
--role-name lambda-execute-encord-agents \
--assume-role-policy-document file://trust-policy.json
It should output a JSON similar to the following. Make sure to take a note of the Arn
.
{
"Role": {
"Path": "/",
"RoleName": "lambda-execute-encord-agents",
"RoleId": "AROAQ7BEARV2DSFT2E3PI",
"Arn": "arn:aws:iam::061234567890:role/lambda-execute-encord-agents",
"CreateDate": "2025-05-09T10:39:35+00:00",
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
}
}
- Attach the basic lambda execution role to the role.
aws iam attach-role-policy \
--role-name lambda-execute-encord-agents \
--policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
STEP 8: Creating a Lambda Function
For ImageUri
, specify the repository URI from Step 5. Ensure you include :latest
at the end of the URI.
aws lambda create-function \
--function-name <my-function-name> \
--package-type Image \
--code ImageUri=111122223333.dkr.ecr.us-east-1.amazonaws.com/<your-lambda-function-name>:latest \
--role arn:aws:iam::061234567890:role/lambda-execute-encord-agents
To update the container image, rebuild it (as in Step 3), then tag it with the repository URI and upload it again (as in Step 6).
Instead of the create-function
call in the end, you do the following.
aws lambda update-function-code \
--function-name pdf-qa \
--image-uri 111122223333.dkr.ecr.us-east-1.amazonaws.com/<your-lambda-function-name>:latest \
--publish
The URL stays the same, so there is no need to reconfigure CORS or anything else.
Now, proceed to Step A below to complete the setup.
Communication with Encord
Now the function is live but not publicly available to the internet.
To make it accessible to the Encord platform, follow these steps:
To make your live Lambda function publicly accessible to the Encord platform, follow these steps:
- Go to https://console.aws.amazon.com/lambda and navigate to your newly created function.
- Go to the Configuration tab and choose the Function URL section.
- Click the Create function URL button.
- Choose
NONE
for Auth type.
- Expand the Additional settings panel and check the Configure cross-origin resource sharing (CORS) box.
- In the Allow origin section, add
https://app.encord.com
, https://app.us.encord.com
, or your custom (VPC) domain.
- Under the Allow headers section, add both
content-type
and x-encord-editor-agent
values.
- In the Allow methods section, choose
POST
.
- Click Save.
The configuration should look similar to the following image (potentially with fewer allowed origins).
You can click the image to expand it.

STEP B: Adding Secrets
Your agent requires an SSH key secret. In the AWS console where you configured the function URL, click the Environment variables tab on the left. Add the ENCORD_SSH_KEY
variable, along with any other necessary credentials (for example, HuggingFace, OpenAI, or Gemini).
We recommend creating an Encord service account and using an associated SSH key. This ensures you provide only the necessary access permissions.
STEP C: Associating the URL with Encord
Now that your AWS setup is complete, copy the Function URL displayed at the top of your AWS Lambda function’s web page. Then, navigate to the Encord app.
- Click the Agents section on the left, and navigate to the Editor agents tab.
- Click the Register editor agent tab.
- Give the agent a name, (optionally) a description, and paste the function URL before clicking Register agent. [Image of Encord “Register editor agent” form]
You can now click the Test agent button to verify that the agent is alive and that CORS is set up correctly.