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.

from signalwire.livewire import function_tool, StopResponse
@function_tool
def end_call(reason: str) -> str:
    """End the call immediately."""
    # Perform cleanup...
    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.

from signalwire.livewire import function_tool, ToolError
@function_tool
def transfer_funds(amount: float, to_account: str) -> str:
    """Transfer funds to another account."""
    if amount <= 0:
        raise ToolError("Amount must be positive.")
    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.

from signalwire.livewire import Agent, AgentHandoff, function_tool
billing_agent = Agent(instructions="You handle billing questions.")
@function_tool
def transfer_to_billing() -> AgentHandoff:
    """Transfer the caller to the billing department."""
    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.

from signalwire.livewire import ChatContext
chat = ChatContext()
chat.append(role="user", text="What is the weather?")
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.