Proxy¶

AWS Lambda proxy handlers for Twilio webhooks. Requires the agentcore extra.

AgentCore Lambda Proxy¶

tac_aws.proxy.agentcore_lambda ¶

AgentCore Lambda Proxy - Reusable Lambda handler wrapper for TAC integration.

This module provides a proxy class that wraps Lambda handler logic for Twilio webhook routing to AWS Bedrock AgentCore. Users provide the Twilio auth token, and the proxy handles signature validation and webhook routing internally.

Example usage

from tac_aws.proxy import AgentCoreLambdaProxy

Fetch Twilio auth token from Secrets Manager¶

twilio_auth_token = fetch_twilio_auth_token( secret_arn=os.environ["TWILIO_SECRET_ARN"] )

Create proxy¶

proxy = AgentCoreLambdaProxy( agentcore_runtime_arn=os.environ["AGENTCORE_RUNTIME_ARN"], conversation_configuration_id=os.environ["TWILIO_CONVERSATION_CONFIGURATION_ID"], twilio_auth_token=twilio_auth_token, )

Expose handler¶

lambda_handler = proxy.lambda_handler

AgentCoreLambdaProxy ¶

AgentCoreLambdaProxy(
    agentcore_runtime_arn: str,
    conversation_configuration_id: str,
    twilio_auth_token: str,
    aws_region: str | None = None,
)

Lambda proxy for routing Twilio webhooks to AWS Bedrock AgentCore.

This proxy handles:

Signature validation for Twilio webhooks
Voice call routing (generates TwiML with presigned WebSocket URL)
Conversation webhook routing (forwards to AgentCore via HTTP)

Attributes:

Name	Type	Description
`agentcore_runtime_arn`		ARN of the AgentCore runtime
`conversation_configuration_id`		Twilio Conversation Configuration ID
`signature_validator`		TwilioSignatureValidator instance
`aws_region`		AWS region for clients

Initialize AgentCore Lambda proxy.

Parameters:

Name	Type	Description	Default
`agentcore_runtime_arn`	`str`	ARN of the AgentCore runtime	required
`conversation_configuration_id`	`str`	Twilio Conversation Configuration ID	required
`twilio_auth_token`	`str`	Twilio auth token for webhook signature validation	required
`aws_region`	`str \| None`	AWS region for boto3 clients (optional, auto-detected from AWS_REGION env var, boto3 session, or AWS config)	`None`

Raises:

Type	Description
`ValueError`	If AWS region cannot be determined

lambda_handler ¶

lambda_handler(
    event: dict[str, Any], context: Any
) -> dict[str, Any]

Route requests to appropriate handler.

Parameters:

Name	Type	Description	Default
`event`	`dict[str, Any]`	Lambda event containing HTTP request data	required
`context`	`Any`	Lambda context object	required

Returns:

Type	Description
`dict[str, Any]`	Dict containing statusCode, headers, and body

Signature Validation¶

tac_aws.proxy.validation ¶

Twilio webhook signature validation for AWS Lambda.

Handles signature validation for both form-encoded and JSON webhooks.

TwilioSignatureValidator ¶

TwilioSignatureValidator(auth_token: str)

Validates Twilio webhook signatures for AWS Lambda events.

Initialize validator with Twilio auth token.

Raises:

Type	Description
`ImportError`	If twilio package is not installed

validate ¶

validate(event: dict[str, Any]) -> bool

Validate Twilio webhook signature from Lambda event.

Handles different content types:

Form-encoded: Parses body with blank values preserved
JSON with bodySHA256: Validates using body string
Other: Validates using body string

Parameters:

Name	Type	Description	Default
`event`	`dict[str, Any]`	AWS Lambda event dict	required

Returns:

Type	Description
`bool`	True if signature is valid, False otherwise