***

title: handle_serverless_request
slug: /reference/python/agents/agent-base/serverless
description: Handle requests in serverless environments like AWS Lambda, Google Cloud Functions, and Azure Functions.
max-toc-depth: 3
---------------------

For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

[run]: /docs/server-sdks/reference/python/agents/agent-base/run

Handle incoming requests in serverless environments. This method dispatches to the
appropriate handler based on the detected (or forced) execution mode: CGI, Lambda,
Google Cloud Functions, or Azure Functions.

In most cases, use [`run()`][run] instead,
which auto-detects the environment and calls this method when appropriate. Call
`handle_serverless_request()` directly only when you need explicit control over the
serverless dispatch.

The method automatically:

* Parses the request body for SWAIG function calls
* Routes to the correct SWAIG function handler
* Returns the SWML document for root path requests
* Validates authentication credentials

<Note>
  Supported platforms: AWS Lambda (HTTP API v1 and v2), Google Cloud Functions (Flask),
  Azure Functions (HttpRequest/HttpResponse), and CGI.
</Note>

## **Parameters**

<ParamField path="event" type="Optional[Any]" toc={true}>
  Platform-specific event or request object:

  * **Lambda**: The event dictionary from the Lambda handler
  * **Google Cloud Functions**: The Flask `request` object
  * **Azure Functions**: The `HttpRequest` object
  * **CGI**: Not used (reads from `stdin` and environment variables)
</ParamField>

<ParamField path="context" type="Optional[Any]" toc={true}>
  Platform-specific context object (Lambda context, etc.).
</ParamField>

<ParamField path="mode" type="Optional[str]" toc={true}>
  Override the auto-detected execution mode.

  * `"cgi"` -- CGI gateway interface
  * `"lambda"` -- AWS Lambda
  * `"google_cloud_function"` -- Google Cloud Functions
  * `"azure_function"` -- Azure Functions
</ParamField>

## **Returns**

Platform-specific response:

* **Lambda**: `dict` with `statusCode`, `headers`, and `body`
* **Google Cloud Functions**: Flask `Response` object
* **Azure Functions**: `HttpResponse` object
* **CGI**: Response string printed to stdout

## **Examples**

### AWS Lambda

```python {11-12}
from signalwire import AgentBase
from signalwire.core.function_result import FunctionResult

agent = AgentBase(name="lambda-agent")
agent.set_prompt_text("You are a helpful assistant.")

@agent.tool(description="Say hello")
def say_hello(args, raw_data=None):
    return FunctionResult("Hello!")

def handler(event, context):
    return agent.handle_serverless_request(event, context, mode="lambda")
```

### Google Cloud Function

```python {7}
from signalwire import AgentBase

agent = AgentBase(name="gcf-agent")
agent.set_prompt_text("You are a helpful assistant.")

def main(request):
    return agent.handle_serverless_request(request, mode="google_cloud_function")
```

### Azure Function

```python {8}
import azure.functions as func
from signalwire import AgentBase

agent = AgentBase(name="azure-agent")
agent.set_prompt_text("You are a helpful assistant.")

def main(req: func.HttpRequest) -> func.HttpResponse:
    return agent.handle_serverless_request(req, mode="azure_function")
```