AWS Lambda Adapter

API reference for the AWS Lambda handle_lambda adapter

The AWS Lambda adapter enables deploying agents as Lambda functions behind API Gateway.

Import

from ai_query.adapters.aws import handle_lambda

---

handle_lambda

The handle_lambda function bridges AWS Lambda events to the agent system, supporting API Gateway v1 and v2.

Function Signature

def handle_lambda(
    agent: Agent,
    event: dict[str, Any],
    context: Any
) -> dict[str, Any]

Parameters

agent · Agent · required

The agent instance to handle requests.

event · dict[str, Any] · required

AWS Lambda event object from API Gateway.

context · Any · required

AWS Lambda context object.

Returns

Usage Examples

Basic Lambda Function

# lambda_function.py
from ai_query.agents import Agent
from ai_query.adapters.aws import handle_lambda
from ai_query.providers import openai

# Create agent
agent = Agent(
    "lambda-agent",
    model=openai("gpt-4o"),
    system="You are an AWS Lambda-powered assistant."
)

def lambda_handler(event, context):
    return handle_lambda(agent, event, context)

Multi-Agent Lambda Router

# lambda_function.py
import json
from ai_query.agents import AgentRegistry, Agent
from ai_query.adapters.aws import handle_lambda
from ai_query.providers import openai

# Create agent registry
registry = AgentRegistry()
registry.register("chatbot", lambda id: Agent(id, model=openai("gpt-4o")))
registry.register("assistant", lambda id: Agent(id, model=openai("gpt-4o"), system="You are an assistant."))

# Router function
def lambda_handler(event, context):
    # Extract agent type from path or headers
    agent_type = event.get("pathParameters", {}).get("type", "chatbot")

    # Create appropriate agent
    target_class = registry.resolve(agent_type)
    agent = target_class(f"lambda-{agent_type}")

    return handle_lambda(agent, event, context)

With Environment Configuration

import os
from ai_query.agents import Agent
from ai_query.adapters.aws import handle_lambda
from ai_query.providers import openai, anthropic

# Configure agent based on environment
model_provider = os.getenv("MODEL_PROVIDER", "openai")
model_name = os.getenv("MODEL_NAME", "gpt-4o")

if model_provider == "openai":
    model = openai(model_name)
elif model_provider == "anthropic":
    model = anthropic(model_name)
else:
    raise ValueError(f"Unsupported provider: {model_provider}")

agent = Agent(
    "lambda-agent",
    model=model,
    system=os.getenv("SYSTEM_PROMPT", "You are helpful."),
    max_tokens=int(os.getenv("MAX_TOKENS", "1000"))
)

def lambda_handler(event, context):
    return handle_lambda(agent, event, context)

---

Using Lambda Layers

# lambda_function.py
import os
import sys

# Add ai-query from Lambda layer
sys.path.insert(0, os.path.join(os.getcwd(), "opt", "python"))

from ai_query.agents import Agent
from ai_query.adapters.aws import handle_lambda
from ai_query.providers import openai

# Initialize agent outside handler for reuse
agent = Agent(
    "production-agent",
    model=openai(os.getenv("OPENAI_API_KEY")),
    system="You are a production assistant."
)

def lambda_handler(event, context):
    """Handle Lambda requests with agent."""
    return handle_lambda(agent, event, context)

---

Error Handling

The AWS Lambda adapter returns a JSON error response:

{
    "statusCode": 400,
    "headers": {"Content-Type": "application/json"},
    "body": "{\"error\": \"Invalid JSON body\"}"
}

For custom error handling, wrap the agent in your handler function.