RunContext | SignalWire

RunContext is passed to tool handler functions that declare a parameter with a RunContext type annotation. It provides access to the current AgentSession and its user data, letting tools read and modify session state.

1 from signalwire.livewire import function_tool, RunContext
2 
3 @function_tool
4 def save_preference(ctx: RunContext, color: str) -> str:
5     """Save the user's favorite color."""
6     ctx.userdata["favorite_color"] = color
7     return f"Got it, your favorite color is {color}."

The RunContext parameter is automatically detected by @function_tool via its type annotation and excluded from the tool’s JSON schema. You do not need to pass it when the tool is called by the LLM.

Properties

session

Optional[AgentSession]

The AgentSession that owns this context. May be None if the tool is invoked outside a session.

userdata

Any

Shortcut for session.userdata. Returns an empty dict if no session is bound.

speech_handle

Any

Handle to the current speech output. Accepted for API compatibility.

function_call

Any

Metadata about the function call that triggered this context. Accepted for API compatibility.

Example

1 from signalwire.livewire import Agent, AgentSession, RunContext, function_tool
2 
3 @function_tool
4 def add_note(ctx: RunContext, note: str) -> str:
5     """Add a note to the session."""
6     notes = ctx.userdata.setdefault("notes", [])
7     notes.append(note)
8     return f"Note saved. You have {len(notes)} note(s)."
9 
10 agent = Agent(
11     instructions="You are a note-taking assistant.",
12     tools=[add_note],
13 )
14 session = AgentSession(userdata={"notes": []})
15 await session.start(agent)