***

title: RunContext
slug: /reference/python/agents/livewire/run-context
description: Context object available inside tool handler functions.
max-toc-depth: 3
---------------------

For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

[agentsession]: /docs/server-sdks/reference/python/agents/livewire/agent-session

[functiontool]: /docs/server-sdks/reference/python/agents/livewire/function-tool

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

```python
from signalwire.livewire import function_tool, RunContext

@function_tool
def save_preference(ctx: RunContext, color: str) -> str:
    """Save the user's favorite color."""
    ctx.userdata["favorite_color"] = color
    return f"Got it, your favorite color is {color}."
```

<Note>
  The `RunContext` parameter is automatically detected by
  [`@function_tool`][functiontool] 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.
</Note>

## **Properties**

<ParamField path="session" type="Optional[AgentSession]" toc={true}>
  The [`AgentSession`][agentsession]
  that owns this context. May be `None` if the tool is invoked outside a session.
</ParamField>

<ParamField path="userdata" type="Any" toc={true}>
  Shortcut for `session.userdata`. Returns an empty dict if no session is bound.
</ParamField>

<ParamField path="speech_handle" type="Any" toc={true}>
  Handle to the current speech output. Accepted for API compatibility.
</ParamField>

<ParamField path="function_call" type="Any" toc={true}>
  Metadata about the function call that triggered this context. Accepted for API
  compatibility.
</ParamField>

## **Example**

```python
from signalwire.livewire import Agent, AgentSession, RunContext, function_tool

@function_tool
def add_note(ctx: RunContext, note: str) -> str:
    """Add a note to the session."""
    notes = ctx.userdata.setdefault("notes", [])
    notes.append(note)
    return f"Note saved. You have {len(notes)} note(s)."

agent = Agent(
    instructions="You are a note-taking assistant.",
    tools=[add_note],
)
session = AgentSession(userdata={"notes": []})
await session.start(agent)
```