signalwire-sdk 3.7.1.dev128__tar.gz → 3.7.1.dev129__tar.gz

{signalwire_sdk-3.7.1.dev128 → signalwire_sdk-3.7.1.dev129}/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+- `AgentBase.on_call_start()` registers handlers that run when the call
+  starts, before the AI's first turn: the counterpart of `on_call_end()`. It
+  wraps the platform's reserved `startup_hook` function. A handler receives
+  the SWAIG request and may return a `FunctionResult`: its actions run at
+  once, and its response text is added to the conversation as a system
+  message the model reads before it speaks. Handlers run in registration
+  order, and an exception is logged, not raised.
+
+### Documentation
+- How to reject a call from the per-call configuration callback
+  (`add_per_call_config()`): build the agent with `play` and `hangup`
+  post-answer verbs and no tools, and have the callback add the tools and
+  call `clear_post_answer_verbs()` only for a call it accepts. A callback
+  that fails leaves the call rejected. See "Rejecting a Call" in
+  `docs/agent_guide.md`.
+- The SWAIG function webhook timeout: the platform waits up to 30 seconds to
+  connect and 120 seconds for a tool's reply, and sends the request again, up
+  to 3 times, after a failed or timed-out request or a 5xx. The caller hears
+  nothing meanwhile, so tools should answer quickly and send late results into the call with
+  `rest.calling.ai_message()`. See "Slow tools and the webhook timeout" in
+  `docs/agent_guide.md`.
 ## [3.7.1] - 2026-10-13
 
 ### Added

{signalwire_sdk-3.7.1.dev128/signalwire/signalwire_sdk.egg-info → signalwire_sdk-3.7.1.dev129}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire-sdk
-Version: 3.7.1.dev128
+Version: 3.7.1.dev129
 Summary: SignalWire SDK for AI voice agents, live call control (RELAY) and REST. Run sw-pydocs for its documentation.
 Author-email: SignalWire Team <info@signalwire.com>
 License: MIT

{signalwire_sdk-3.7.1.dev128 → signalwire_sdk-3.7.1.dev129}/docs/agent_guide.md

@@ -346,6 +346,47 @@ An `on_swml_request` override still runs on the event loop, because it can chang
 
 Set `SWML_SYNC_HANDLERS_INLINE=true` to run synchronous handlers and callbacks on the event loop instead, one at a time, as earlier releases did. The serverless entry points call handlers directly, as before.
 
+#### Slow tools and the webhook timeout
+
+SignalWire waits up to 30 seconds to connect to a SWAIG function's webhook and up to 120 seconds for its reply. When a request fails, times out or gets an error response (5xx), it sends the same request again, up to 3 more times, a second apart. So a slow or failing tool can run more than once, and the caller hears nothing from it in the meantime.
+
+Answer within a few seconds. When the work takes longer, start it in the background, return at once with a reply that tells the model the result is on its way, and send the result into the call when it's ready with the REST API's `calling.ai_message` (`rest.calling.ai_message()` on a `RestClient`):
+
+<!-- snippet: no-run illustrative fragment (`slow_order_lookup` is your own helper; sends a live REST request) -->
+```python
+import threading
+
+from signalwire import AgentBase, FunctionResult, RestClient
+
+rest = RestClient()  # SIGNALWIRE_PROJECT_ID, SIGNALWIRE_API_TOKEN, SIGNALWIRE_SPACE
+
+
+class OrderAgent(AgentBase):
+    @AgentBase.tool(
+        name="check_order",
+        description="Look up an order's shipping status",
+        parameters={"order_id": {"type": "string", "description": "The order number"}},
+    )
+    def check_order(self, args, raw_data):
+        call_id = raw_data.get("call_id")
+        order_id = args.get("order_id")
+
+        def finish():
+            status = slow_order_lookup(order_id)  # may take 30 seconds
+            rest.calling.ai_message(
+                call_id,
+                role="system",
+                message_text=f"Order {order_id} status: {status}. Tell the caller.",
+            )
+
+        threading.Thread(target=finish, daemon=True).start()
+        return FunctionResult(
+            "The lookup has started. Tell the caller you're checking and will have it shortly."
+        )
+```
+
+The message goes into the AI session as the given role (`system`, `user` or `assistant`); `system` keeps the result from reading as something the caller said. Because a request can arrive twice, make tools safe to run twice: for example, key work that's already running by `call_id` and arguments, and join it instead of starting it again. A DataMap function's webhook has its own limits; see [Network Timeout and Retry Logic](datamap_guide.md#132-network-timeout-and-retry-logic) in the DataMap guide.
+
 ### 2. External Webhook Functions
 
 External webhook functions allow you to delegate function execution to external services instead of handling them locally. This is useful when you want to:
@@ -1926,6 +1967,53 @@ class MyAgent(AgentBase):
             agent.set_global_data(config)
 ```
 
+#### Rejecting a Call
+
+The callback can't refuse the request, but it can decide what the call does. To turn away a call the agent shouldn't take, such as one whose caller can't be verified, build the agent so that by default the call hears a message and hangs up, and have the callback undo that only for a call it accepts:
+
+1. In the constructor, add `play` and `hangup` with `add_post_answer_verb()`. They run after the call is answered and before the `ai` verb, so a call that keeps them hangs up before the AI starts. Define no tools on the agent itself.
+2. In the callback, for an accepted call, add the tools and other configuration to the request's copy, then call `clear_post_answer_verbs()` last.
+
+This fails closed. The callback changes only the request's copy, so the next call starts from the goodbye again. If the callback raises, the SDK logs the error and renders the copy as it stands, and since clearing the verbs is the last step, a failure before it leaves the goodbye in place.
+
+The callback runs for every request the call makes: the SWML fetch, and again for each tool call and the post-prompt summary. Only the SWML fetch carries the caller's data, such as the `userVariables` a browser or app client sends with `dial()`; a tool call carries the `call_id` and `global_data`, and `global_data` comes from the call, so it proves nothing. Verify on the SWML fetch, remember the `call_id` (`body["call"]["call_id"]` there, `body["call_id"]` on later requests), and check that on later requests, so a tool call from a call you didn't verify finds no tool to run.
+
+<!-- snippet: no-run illustrative fragment (`signature_is_valid` is your own check) -->
+```python
+from signalwire import AgentBase, FunctionResult
+from signalwire.core.capabilities import user_variables
+
+
+class GatedAgent(AgentBase):
+    def __init__(self):
+        super().__init__(name="gated", route="/")
+        # Callbacks run in worker threads; a set's add and `in` are safe there.
+        # With more than one process, keep this in a shared store instead.
+        self._verified: set[str] = set()
+        self.prompt_add_section("Role", body="You are a helpful assistant.")
+        # Fail closed: every call gets this unless configure() accepts it.
+        self.add_post_answer_verb("play", {"url": "say:Sorry, this call can't be verified. Goodbye."})
+        self.add_post_answer_verb("hangup", {})
+        self.add_per_call_config(self.configure)
+
+    def configure(self, query_params, body_params, headers, agent):
+        call = body_params.get("call")
+        if isinstance(call, dict):  # the SWML fetch that starts the call
+            call_id = call.get("call_id")
+            if call_id and signature_is_valid(user_variables(body_params)):
+                self._verified.add(call_id)
+        else:  # a tool call or the summary
+            call_id = body_params.get("call_id")
+        if call_id not in self._verified:
+            return  # stays a goodbye with no tools
+        agent.define_tool(
+            "lookup", "Look up an account", {}, lambda args, raw: FunctionResult("...")
+        )
+        agent.clear_post_answer_verbs()  # last: a failure above leaves the goodbye
+```
+
+Since the call never reaches the `ai` verb, no tool, `on_call_start` or `on_call_end` handler runs for a rejected call. Forget a verified `call_id` when the call ends (in `on_call_end`, for example) or after a time limit.
+
 #### Error Handling
 
 1. **Graceful Degradation**: fall back to a default configuration if the custom one fails.
@@ -2044,9 +2132,39 @@ These hooks are particularly useful for:
 - Cleaning up temporary resources
 - Saving session data for analytics
 
+#### `on_call_start` and `on_call_end`
+
+`on_call_start()` and `on_call_end()` register handlers for the two hooks. Each can be used as a decorator or called directly, takes any number of handlers that run in registration order, and logs a handler's exception instead of raising it, so one failing handler doesn't stop the others.
+
+<!-- snippet: no-run illustrative fragment (`lookup_caller` and `archive` are your own helpers) -->
+```python
+from signalwire import AgentBase, FunctionResult
+
+agent = AgentBase(name="my-agent")
+
+@agent.on_call_start
+def load_caller(raw_data):
+    caller = lookup_caller(raw_data.get("caller_id_num"))
+    result = FunctionResult(f"The caller is {caller.name}, a {caller.tier} customer.")
+    return result.update_global_data({"customer_id": caller.id})
+
+@agent.on_call_end
+def save_call(call_log, raw_data):
+    archive(raw_data.get("call_id"), call_log)
+```
+
+An `on_call_start` handler receives the SWAIG request (`call_id`, `global_data`, `caller_id_num` and the rest) and may return a `FunctionResult` or `None`. The platform runs the hook once, after the call is answered and before the AI's first turn, and uses its reply:
+
+- The actions run at once, such as `update_global_data()` to give the call data before the conversation starts. Several handlers' actions run in registration order. `post_process` isn't used.
+- The response text is added to the conversation as a system message, so the model reads it before it speaks. Several handlers' texts are joined, one per line. Only a plain string response is used.
+
+The platform waits for the hook before the AI starts, so a slow handler delays the greeting; keep it short (see [Slow tools and the webhook timeout](#slow-tools-and-the-webhook-timeout)).
+
+An `on_call_end` handler receives the conversation (`call_log`) and the SWAIG request. Registering one turns on `swaig_post_conversation`, without which the hook carries no transcript. Its return value is ignored.
+
 #### Implementation
 
-To implement lifecycle hooks, define them as regular SWAIG functions with these specific names.
+To write a hook yourself instead, define a SWAIG function with the reserved name. Use one or the other for each hook: `on_call_start()` and `on_call_end()` define `startup_hook` and `hangup_hook` themselves.
 
 > **Note:** The SDK does not ship built-in session storage. The `update_state`,
 > `get_state`, and `delete_state` methods in the following example are
@@ -2165,7 +2283,7 @@ def hangup_hook(self, args, raw_data):
 2. **Error Handling**: Always implement proper error handling in hooks - failures shouldn't crash the voice session
 3. **Timing**: `startup_hook` is called before the AI starts speaking to the caller
 4. **Session Data**: Any data you need to persist across the session should be stored in external storage (Redis, database, etc.)
-5. **Return Values**: Both hooks must return a `FunctionResult` object
+5. **Return Values**: Both hooks must return a `FunctionResult` object. The `startup_hook`'s actions run and its response text is added to the conversation as a system message; the `hangup_hook`'s response is unused, since the call is over
 
 ### SIP Routing
 

{signalwire_sdk-3.7.1.dev128 → signalwire_sdk-3.7.1.dev129}/docs/api_reference.md

@@ -720,7 +720,7 @@ agent.register_swaig_function(weather_tool.to_swaig_function())
 
 ### Session Lifecycle Hooks
 
-SignalWire AI agents support special SWAIG functions that are automatically called at specific points in the conversation lifecycle:
+SignalWire AI agents support special SWAIG functions that are automatically called at specific points in the conversation lifecycle. `on_call_start()` and `on_call_end()` (see [Event Handlers](#event-handlers)) define them for you; to write one yourself, use the reserved name:
 
 ##### `startup_hook`
 Called when a new conversation/call begins.
@@ -1376,6 +1376,55 @@ class MyAgent(AgentBase):
             print(f"Raw summary: {raw_text}")
 ```
 
+##### `on_call_start`
+
+Register a handler that runs when the call starts, before the AI's first turn. Use as a decorator or call directly; handlers run in registration order. Wraps the platform's reserved `startup_hook` function.
+
+<!-- snippet: no-compile signature-illustration -->
+```python
+def on_call_start(
+    handler: Callable[[Dict[str, Any]], Optional[FunctionResult]]
+) -> Callable[[Dict[str, Any]], Optional[FunctionResult]]
+```
+
+The handler receives `raw_data`, the SWAIG request (`call_id`, `global_data`, `caller_id_num` and the rest), and may return a `FunctionResult` or `None`:
+- Its actions run at once, in registration order across handlers. `post_process` isn't used.
+- Its response text is added to the conversation as a system message the model reads before it speaks. Several handlers' texts are joined, one per line. Only a plain string response is used.
+
+An exception is logged, not raised, and that handler's result is dropped. The platform waits for the hook before the AI starts, so keep the handler short.
+
+**Usage:**
+```python
+agent = AgentBase("my_agent")
+
+@agent.on_call_start
+def greet_by_name(raw_data):
+    name = raw_data.get("caller_id_name") or "the caller"
+    return FunctionResult(f"The caller's name is {name}.")
+```
+
+##### `on_call_end`
+
+Register a handler that runs when the call ends, with the conversation. Use as a decorator or call directly; handlers run in registration order. Wraps the platform's reserved `hangup_hook` function, and turns on `swaig_post_conversation` so the hook carries the transcript.
+
+<!-- snippet: no-compile signature-illustration -->
+```python
+def on_call_end(
+    handler: Callable[[List[Dict[str, Any]], Dict[str, Any]], None]
+) -> Callable[[List[Dict[str, Any]], Dict[str, Any]], None]
+```
+
+The handler receives `call_log` (the conversation) and `raw_data` (the SWAIG request). Its return value is ignored, and an exception is logged, not raised.
+
+**Usage:**
+```python
+agent = AgentBase("my_agent")
+
+@agent.on_call_end
+def log_length(call_log, raw_data):
+    print(f"Call {raw_data.get('call_id')} ended after {len(call_log)} entries")
+```
+
 ##### `on_debug_event`
 
 Register a handler for debug webhook events. Use as a decorator. Requires `enable_debug_events()` to be called first.

{signalwire_sdk-3.7.1.dev128 → signalwire_sdk-3.7.1.dev129}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "signalwire-sdk"
-version = "3.7.1.dev128"
+version = "3.7.1.dev129"
 description = "SignalWire SDK for AI voice agents, live call control (RELAY) and REST. Run sw-pydocs for its documentation."
 authors = [
     {name = "SignalWire Team", email = "info@signalwire.com"}

{signalwire_sdk-3.7.1.dev128 → signalwire_sdk-3.7.1.dev129}/signalwire/signalwire/__init__.py

@@ -59,7 +59,7 @@ if TYPE_CHECKING:
     from signalwire.utils.schema_utils import SchemaValidationError
     from signalwire.web import WebService
 
-__version__ = "3.7.1.dev128"
+__version__ = "3.7.1.dev129"
 
 # §6.2-python (owner decision: NO packaging split — one package, all deps required;
 # IMPORT-TIME behavior only): the agent/web symbols are lazy-imported via module

{signalwire_sdk-3.7.1.dev128 → signalwire_sdk-3.7.1.dev129}/signalwire/signalwire/agent_server.py

@@ -68,7 +68,7 @@ class AgentServer:
         self.app = FastAPI(
             title="SignalWire AI Agents",
             description="Hosted SignalWire AI Agents",
-            version="3.7.1.dev128",
+            version="3.7.1.dev129",
             redirect_slashes=False,
             docs_url=None,
             redoc_url=None,

{signalwire_sdk-3.7.1.dev128 → signalwire_sdk-3.7.1.dev129}/signalwire/signalwire/cli/pydocs/_topics.py

@@ -135,7 +135,13 @@ Per-call configuration: `set_dynamic_config_callback()` configures a copy of
 the agent for each request, from its query parameters, body and headers, for
 per-tenant prompts, voices and tools. The callback runs in a worker thread,
 at the same time as other calls' callbacks. Don't keep per-caller state on the
-shared agent instance.
+shared agent instance. To turn a call away, build the agent with `play` and
+`hangup` post-answer verbs and no tools, and have the callback add the tools
+and call `clear_post_answer_verbs()` only for a call it accepts.
+
+Call start and end: `on_call_start()` runs handlers before the AI's first
+turn, and their `FunctionResult` text and actions reach the call;
+`on_call_end()` runs handlers with the transcript when the call ends.
 
 Configuration precedence: constructor arguments, then the config file, then
 environment variables, then defaults.
@@ -175,6 +181,9 @@ environment variables, then defaults.
         "signalwire.AgentBase.set_dynamic_config_callback",
         "signalwire.AgentBase.get_app",
         "signalwire.AgentBase.on_summary",
+        "signalwire.AgentBase.on_call_start",
+        "signalwire.AgentBase.on_call_end",
+        "signalwire.AgentBase.add_per_call_config",
     ),
     related=("prompts", "tools", "contexts", "skills", "pgi", "deploy"),
 )
@@ -273,6 +282,11 @@ Or give the schema yourself, with a handler that takes `(args, raw_data)`:
 - `gates=[SemanticGate(...)]` adds semantic gates: yes/no questions a
   decision model answers about the call before the platform runs the tool.
   A platform release without semantic gates runs the tool ungated.
+- Answer within a few seconds: the caller hears nothing while a tool runs.
+  SignalWire waits up to 120 seconds for a tool's webhook, and sends the
+  request again after a timeout, a failed connection or a 5xx, so a slow tool
+  can run more than once. Start long work in the background, return at once, and
+  send the result into the call with `rest.calling.ai_message()`.
 """,
     docs=(
         ("docs/swaig_reference.md", "Every FunctionResult method and action"),

{signalwire_sdk-3.7.1.dev128 → signalwire_sdk-3.7.1.dev129}/signalwire/signalwire/core/agent_base.py

@@ -749,6 +749,118 @@ class AgentBase(  # type: ignore[misc]  # intentional diamond: WebMixin's serve/
             handler=_hangup_handler,
         )
 
+    def on_call_start(
+        self, handler: Callable[[dict[str, Any]], "FunctionResult | None"]
+    ) -> Callable[[dict[str, Any]], "FunctionResult | None"]:
+        """
+        Register a handler that runs when the call starts, before the AI speaks.
+
+        Usable as a decorator or called directly. Handlers run in registration
+        order and receive:
+
+            raw_data (dict): the complete SWAIG request, including `call_id`,
+                `global_data` and the caller's details.
+
+        This wraps the platform's reserved `startup_hook` function, the
+        counterpart of the `hangup_hook` behind `on_call_end`. That name is
+        internal: the platform calls it once, after the call is answered and
+        before the AI's first turn, and never offers it to the model as
+        something it could choose.
+
+        The platform waits for the hook before the AI starts, so a slow
+        handler delays the greeting; it waits up to 120 seconds for a
+        function's reply and sends the request again after a timeout or a
+        5xx. Keep handlers short; start long work in
+        the background and send its result into the call later (see
+        `rest.calling.ai_message`).
+
+        A handler may return a `FunctionResult`, or None. What the platform
+        does with the hook's reply:
+        - its actions run at once, in registration order across handlers
+          (for example `update_global_data()` to give the call data before
+          the conversation starts);
+        - its response text is added to the conversation as a system message
+          the model reads before its first turn. The texts of several handlers
+          are joined, one per line. Only a plain string response is used.
+        `post_process` is not used: the combined result runs its actions at
+        once. The platform adds every hook reply to the conversation, so a
+        hook whose handlers return no text still adds a short placeholder
+        line, as any function with an empty reply does.
+
+        Exceptions are caught and logged rather than raised, and that
+        handler's result is dropped, so a failing handler can't stop the call
+        from starting or the other handlers from running.
+
+        Args:
+            handler: Callable taking (raw_data), returning a FunctionResult or
+                None.
+
+        Returns:
+            The handler, so this can be used as a decorator.
+
+        Example:
+            @agent.on_call_start
+            def load_caller(raw_data):
+                caller = lookup(raw_data.get("caller_id_num"))
+                result = FunctionResult(f"The caller's name is {caller.name}.")
+                return result.update_global_data({"customer_id": caller.id})
+        """
+        handlers = self.__dict__.get("_call_start_handlers")
+        if handlers is None:
+            # Rebind rather than mutate -- see the ephemeral-copy contract on
+            # _create_ephemeral_copy; this list is not in the copied set.
+            self._call_start_handlers = [handler]
+            self._ensure_call_start_hook()
+        else:
+            self._call_start_handlers = [*handlers, handler]
+        return handler
+
+    def _ensure_call_start_hook(self) -> None:
+        """Register the reserved startup_hook once."""
+
+        def _startup_handler(args: Any, raw_data: Any) -> FunctionResult:
+            raw = raw_data or {}
+            combined = FunctionResult()
+            texts: list[str] = []
+            for callback in self.__dict__.get("_call_start_handlers") or []:
+                name = getattr(callback, "__name__", repr(callback))
+                # Isolated per handler, as in _ensure_call_end_hook: one failure
+                # must not stop the others.
+                try:
+                    result = callback(raw)
+                except Exception as exc:
+                    self.log.error(
+                        "call_start_handler_failed", error=str(exc), handler=name
+                    )
+                    continue
+                if result is None:
+                    continue
+                if not isinstance(result, FunctionResult):
+                    self.log.warning(
+                        "call_start_handler_result_ignored",
+                        handler=name,
+                        result_type=type(result).__name__,
+                    )
+                    continue
+                if isinstance(result.response, str):
+                    if result.response:
+                        texts.append(result.response)
+                elif result.response:
+                    self.log.warning(
+                        "call_start_handler_structured_response_ignored",
+                        handler=name,
+                    )
+                combined.add_actions(result.action)
+            combined.set_response("\n".join(texts))
+            return combined
+
+        self.define_tool(
+            name="startup_hook",
+            description="Internal: fires when the call starts.",
+            parameters={},
+            handler=_startup_handler,
+        )
+
     def on_debug_event(self, handler: Callable[..., Any]) -> Callable[..., Any]:
         """
         Register a handler for debug webhook events.

{signalwire_sdk-3.7.1.dev128 → signalwire_sdk-3.7.1.dev129}/signalwire/signalwire/core/mixins/web_mixin.py

@@ -1696,6 +1696,20 @@ class WebMixin(_HostTyped):  # type: ignore[misc]  # _HostTyped is object at run
         `set_dynamic_config_callback` requires them to find and manually chain
         each other's callbacks, and silently drops one when they don't.
 
+        Rejecting a call: a callback can't refuse the request, but it can
+        decide what the call does. Build the agent to fail closed -- in the
+        constructor, `add_post_answer_verb("play", {"url": "say:..."})` and
+        `add_post_answer_verb("hangup", {})`, and no tools -- so the call
+        hears the message and hangs up before the `ai` verb runs. For a call
+        the callback accepts, add the tools to `agent` and call
+        `agent.clear_post_answer_verbs()` last. A callback that raises is
+        logged and the copy is rendered as it stands, so a failure before
+        that last step leaves the goodbye in place. Callbacks run for every
+        request of the call (the SWML fetch, each tool call, the summary),
+        and only the SWML fetch carries the caller's data (such as
+        `userVariables`): verify there, remember the `call_id`, and check it
+        on later requests. See "Rejecting a Call" in docs/agent_guide.md.
+
         Args:
             callback: Callable taking (query_params, body_params, headers, agent).
                       `agent` is the EPHEMERAL per-request copy; configure that,

{signalwire_sdk-3.7.1.dev128 → signalwire_sdk-3.7.1.dev129/signalwire/signalwire_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire-sdk
-Version: 3.7.1.dev128
+Version: 3.7.1.dev129
 Summary: SignalWire SDK for AI voice agents, live call control (RELAY) and REST. Run sw-pydocs for its documentation.
 Author-email: SignalWire Team <info@signalwire.com>
 License: MIT