on_swml_request | SignalWire

Customization point called during SWML rendering, before the document is returned to the caller. Override this method in a subclass to inspect request data and return modifications to apply to the SWML document.

The default implementation checks for a set_dynamic_config_callback() and, if one is registered, returns an internal marker that triggers ephemeral agent cloning. For most per-request customization, set_dynamic_config_callback() is the simpler approach.

This method is called during SWML rendering by the internal request handler. It is not an override of SWMLService.on_request() — it is a separate hook that adds support for dynamic configuration and ephemeral agent copies.

Parameters

request_data

Optional[dict[str, Any]]Defaults to None

Parsed POST body from the incoming request, if available.

callback_path

Optional[str]Defaults to None

The path segment that triggered this request.

request

Optional[Request]Defaults to None

The FastAPI Request object, providing access to query parameters, headers, and other HTTP metadata.

Returns

Optional[dict] — A dictionary of modifications to apply to the SWML document, or None for no modifications. The keys and structure depend on the rendering pipeline.

Example

1 from signalwire import AgentBase
2 
3 class MultiTenantAgent(AgentBase):
4     def __init__(self):
5         super().__init__(name="multi-tenant", route="/agent")
6         self.set_prompt_text("You are a helpful assistant.")
7 
8     def on_swml_request(self, request_data=None, callback_path=None, request=None):
9         """Inject tenant context into global_data based on a request header."""
10         tenant = None
11         if request:
12             tenant = request.headers.get("X-Tenant-ID")
13         if tenant:
14             # Return modifications — "global_data" keys are merged into ai.params.global_data
15             return {"global_data": {"tenant_id": tenant, "tier": "premium" if tenant == "acme" else "standard"}}
16         return super().on_swml_request(request_data, callback_path, request)
17 
18 agent = MultiTenantAgent()
19 agent.run()

For most per-request customization scenarios, prefer set_dynamic_config_callback() which provides a higher-level interface with access to query params, body, headers, and the agent instance.