> ## Documentation Index
> Fetch the complete documentation index at: https://thethirdpenco-feat-tool-lifecycle-events.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```python theme={null}
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

```python theme={null}
def handle_lambda(
    agent: Agent,
    event: dict[str, Any],
    context: Any
) -> dict[str, Any]
```

#### Parameters

<ParamField path="agent" type="Agent" required>
  The agent instance to handle requests.
</ParamField>

<ParamField path="event" type="dict[str, Any]" required>
  AWS Lambda event object from API Gateway.
</ParamField>

<ParamField path="context" type="Any" required>
  AWS Lambda context object.
</ParamField>

#### Returns

<ReturnsField type="dict[str, Any]">
  API Gateway response object with statusCode, headers, and body.
</ReturnsField>

### Usage Examples

#### Basic Lambda Function

```python theme={null}
# 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

```python theme={null}
# 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

```python theme={null}
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

```python theme={null}
# 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:

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

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