Signals

LiveWire provides exception and signal classes that tool handlers can raise or return to control agent behavior. These mirror their LiveKit equivalents.

StopResponse

An exception that, when raised inside a tool handler, signals that the tool should not trigger another LLM reply. Use this when the tool’s side effect is the final action and no further conversation is needed.

1
from signalwire.livewire import function_tool, StopResponse
2
3
@function_tool
4
def end_call(reason: str) -> str:
5
    """End the call immediately."""
6
    # Perform cleanup...
7
    raise StopResponse()

ToolError

An exception that signals a tool execution error. Raise this when a tool encounters a problem that should be reported back to the LLM so it can communicate the issue to the user or retry.

1
from signalwire.livewire import function_tool, ToolError
2
3
@function_tool
4
def transfer_funds(amount: float, to_account: str) -> str:
5
    """Transfer funds to another account."""
6
    if amount <= 0:
7
        raise ToolError("Amount must be positive.")
8
    return f"Transferred ${amount} to {to_account}."

AgentHandoff

A signal object for handing off a conversation to a different agent in multi-agent scenarios. Return an AgentHandoff from a tool handler to indicate that a different agent should take over.

1
from signalwire.livewire import Agent, AgentHandoff, function_tool
2
3
billing_agent = Agent(instructions="You handle billing questions.")
4
5
@function_tool
6
def transfer_to_billing() -> AgentHandoff:
7
    """Transfer the caller to the billing department."""
8
    return AgentHandoff(billing_agent)

Properties

ChatContext

A minimal stub mirroring the LiveKit ChatContext. Holds a list of chat messages that can be used to seed conversation history.

1
from signalwire.livewire import ChatContext
2
3
chat = ChatContext()
4
chat.append(role="user", text="What is the weather?")
5
chat.append(role="assistant", text="It is sunny today.")

Properties

Methods

append

append(role="user", text="") -> ChatContext

Add a message to the context. Returns self for chaining.

Returns

ChatContext — The same instance, for method chaining.