> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jay.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Handlers

Event handlers are asynchronous functions that are called when events occur throughout the lifecycle
of a session. Event handlers are particularly useful for sending data to external systems, like your
database or a third-party analytics service. Event handlers don't return data; they just respond to events.

Sessions are never blocked by the logic in your event handlers, so it's fine to put slow
asynchronous operations in your event handlers.

Event handlers are defined as fields on the [`Agent`](https://docs.jay.so/references/agent), as shown in the "Usage" sections below.

An agent emits the following events:

| Event                                                             | Description                                                        |
| ----------------------------------------------------------------- | ------------------------------------------------------------------ |
| **[`on_agent_started_speaking`](#on-agent-started-speaking)**     | Agent started speaking                                             |
| **[`on_user_started_speaking`](#on-user-started-speaking)**       | User started speaking                                              |
| **[`on_agent_stopped_speaking`](#on-agent-stopped-speaking)**     | Agent stopped speaking                                             |
| **[`on_user_stopped_speaking`](#on-user-stopped-speaking)**       | User stopped speaking                                              |
| **[`on_agent_message_added`](#on-agent-speech-committed)**        | Agent message added to the chat history during the session         |
| **[`on_user_message_added`](#on-user-speech-committed)**          | User message added to the chat history during the session          |
| **[`on_agent_interrupted`](#on-agent-speech-interrupted)**        | Agent was interrupted by the user while speaking                   |
| **[`on_function_calls_collected`](#on-function-calls-collected)** | Jay received the complete set of functions to execute from the LLM |
| **[`on_function_calls_executed`](#on-function-calls-finished)**   | Jay executed all of the functions that were collected              |

***

***

# `on_agent_started_speaking`

Called when the agent begins speaking.

### Usage

```py theme={null}
from jay_ai import OnAgentStartedSpeakingInput

async def on_agent_started_speaking(
  input: OnAgentStartedSpeakingInput
) -> None:
  ...

agent = Agent(
  on_agent_started_speaking=on_agent_started_speaking,
  ...
)
```

### Parameters

<ResponseField name="input" type="Object" required>
  <Expandable title="properties" defaultOpen="true">
    <ResponseField name="session_data" type="Object" required>
      Custom data that you specified in the [`SessionConfig`](https://docs.jay.so/references/configure-session#param-session-config) object
    </ResponseField>
  </Expandable>
</ResponseField>

Example `input` parameter:

```json theme={null}
{
  "session_data": {
    "my_user_id": "abc123",
  }
}
```

***

# `on_user_started_speaking`

Called when the user starts speaking.

### Usage

```py theme={null}
from jay_ai import OnUserStartedSpeakingInput

async def on_user_started_speaking(
  input: OnUserStartedSpeakingInput
) -> None:
  ...

agent = Agent(
  on_user_started_speaking=on_user_started_speaking,
  ...
)
```

### Parameters

<ResponseField name="input" type="Object" required>
  <Expandable title="properties" defaultOpen="true">
    <ResponseField name="session_data" type="Object" required>
      Custom data that you specified in the [`SessionConfig`](https://docs.jay.so/references/configure-session#param-session-config) object
    </ResponseField>
  </Expandable>
</ResponseField>

Example `input` parameter:

```json theme={null}
{
  "session_data": {
    "my_user_id": "abc123"
  }
}
```

***

# `on_user_stopped_speaking`

Called when the user stops speaking.

### Usage

```py theme={null}
from jay_ai import OnUserStoppedSpeakingInput

async def on_user_stopped_speaking(
  input: OnUserStoppedSpeakingInput
) -> None:
  ...

agent = Agent(
  on_user_stopped_speaking=on_user_stopped_speaking,
  ...
)
```

### Parameters

<ResponseField name="input" type="Object" required>
  <Expandable title="properties" defaultOpen="true">
    <ResponseField name="session_data" type="Object" required>
      Custom data that you specified in the [`SessionConfig`](https://docs.jay.so/references/configure-session#param-session-config) object
    </ResponseField>
  </Expandable>
</ResponseField>

Example `input` parameter:

```json theme={null}
{
  "session_data": {
    "my_user_id": "abc123"
  }
}
```

***

# `on_agent_stopped_speaking`

Called when the agent finishes speaking.

### Usage

```py theme={null}
from jay_ai import OnAgentStoppedSpeakingInput

async def on_agent_stopped_speaking(
  input: OnAgentStoppedSpeakingInput
) -> None:
  ...

agent = Agent(
  on_agent_stopped_speaking=on_agent_stopped_speaking,
  ...
)
```

### Parameters

<ResponseField name="input" type="Object" required>
  <Expandable title="properties" defaultOpen="true">
    <ResponseField name="session_data" type="Object" required>
      Custom data that you specified in the [`SessionConfig`](https://docs.jay.so/references/configure-session#param-session-config) object
    </ResponseField>
  </Expandable>
</ResponseField>

Example `input` parameter:

```json theme={null}
{
  "session_data": {
    "my_user_id": "abc123"
  }
}
```

***

# `on_user_message_added`

Called when the user’s message is added to the chat history during the session.

### Usage

```py theme={null}
from jay_ai import OnUserMessageAddedInput

async def on_user_message_added(
  input: OnUserMessageAddedInput
) -> None:
  ...

agent = Agent(
  on_user_message_added=on_user_message_added,
  ...
)
```

### Parameters

<ResponseField name="input" type="Object" required>
  <Expandable title="properties" defaultOpen="true">
    <ResponseField name="message" type="Object" required>
      The user's message that was added to the chat history most recently.

      <Expandable title="properties" defaultOpen="false">
        <ResponseField name="content" type="string" required>
          The text of the user’s message
        </ResponseField>

        <ResponseField name="role" type="string" required>
          The role of the speaker (always "user")
        </ResponseField>

        <ResponseField name="name" type="string | None">
          An optional speaker name. Defaults to `None`.
        </ResponseField>

        <ResponseField name="tool_call_id" type="string | None">
          If the `role` is `"tool"`, this is the tool call ID that this message is responding to. Otherwise, it's `None`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="input" type="Object" required>
      Custom data that you specified in the [`SessionConfig`](https://docs.jay.so/references/configure-session#param-session-config) object
    </ResponseField>
  </Expandable>
</ResponseField>

Example `input` parameter:

```json theme={null}
{
  "message": {
    "content": "Hello, agent!",
    "role": "user",
    "name": "Bob",
    "tool_call_id": None
  },
  "session_data": {
    "my_user_id": "abc123"
  }
}
```

***

# `on_agent_message_added`

Called when the agent’s message is added to the chat history during the session.

### Usage

```py theme={null}
from jay_ai import OnAgentMessageAddedInput

async def on_agent_message_added(
  input: OnAgentMessageAddedInput
) -> None:
  ...

agent = Agent(
  on_agent_message_added=on_agent_message_added,
  ...
)
```

### Parameters

<ResponseField name="input" type="Object" required>
  <Expandable title="properties" defaultOpen="true">
    <ResponseField name="message" type="Object" required>
      The message produced by the agent.

      <Expandable title="properties" defaultOpen="false">
        <ResponseField name="content" type="string" required>
          The text the agent is responding with
        </ResponseField>

        <ResponseField name="role" type="string" required>
          The role of the speaker (in this case, "assistant")
        </ResponseField>

        <ResponseField name="name" type="string | None">
          An optional speaker name. Defaults to `None`.
        </ResponseField>

        <ResponseField name="tool_call_id" type="string | None">
          Internal ID if this message is responding to a tool call. Defaults to `None`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="session_data" type="Object" required>
      Custom data that you specified in the [`SessionConfig`](https://docs.jay.so/references/configure-session#param-session-config) object
    </ResponseField>
  </Expandable>
</ResponseField>

Example `input` parameter:

```json theme={null}
{
  "message": {
    "content": "Hello there, how can I help you?",
    "role": "assistant",
    "name": None,
    "tool_call_id": None
  },
  "session_data": {
    "my_user_id": "abc123"
  }
}
```

***

# `on_agent_interrupted`

Called if the agent is interrupted by the user while speaking.

### Usage

```py theme={null}
from jay_ai import OnAgentInterruptedInput

async def on_agent_interrupted(
  input: OnAgentInterruptedInput
) -> None:
  ...

agent = Agent(
  on_agent_interrupted=on_agent_interrupted,
  ...
)
```

### Parameters

<ResponseField name="input" type="Object" required>
  <Expandable title="properties" defaultOpen="true">
    <ResponseField name="message" type="Object" required>
      Agent message up until it was interrupted.

      <Expandable title="properties" defaultOpen="false">
        <ResponseField name="content" type="string" required>
          The text the agent was speaking
        </ResponseField>

        <ResponseField name="role" type="string" required>
          The role of the speaker (in this case, "assistant")
        </ResponseField>

        <ResponseField name="name" type="string | None">
          An optional speaker name. Defaults to `None`.
        </ResponseField>

        <ResponseField name="tool_call_id" type="string | None">
          Internal ID if this message is part of a tool call. Defaults to `None`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="session_data" type="Object" required>
      Custom data that you specified in the [`SessionConfig`](https://docs.jay.so/references/configure-session#param-session-config) object
    </ResponseField>
  </Expandable>
</ResponseField>

Example `input` parameter:

```json theme={null}
{
  "message": {
    "content": "Hello the-",
    "role": "assistant",
    "name": None,
    "tool_call_id": None
  },
  "session_data": {
    "my_user_id": "abc123"
  }
}
```

***

# `on_function_calls_collected`

Called when Jay receives the complete set of functions to execute from the LLM.

### Usage

```py theme={null}
from jay_ai import OnFunctionCallsCollectedInput

async def on_function_calls_collected(
  input: OnFunctionCallsCollectedInput
) -> None:
  ...

agent = Agent(
  on_function_calls_collected=on_function_calls_collected,
  ...
)
```

### Parameters

<ResponseField name="input" type="Object" required>
  <Expandable title="properties" defaultOpen="true">
    <ResponseField name="function_calls" type="List[Object]" required>
      List of function calls the model requested.

      <Expandable title="properties" defaultOpen="false">
        <ResponseField name="id" type="string" required>
          The ID of the tool call
        </ResponseField>

        <ResponseField name="type" type="string" required>
          The type of call; always the string "function"
        </ResponseField>

        <ResponseField name="function" type="Object" required>
          <Expandable title="properties" defaultOpen="false">
            <ResponseField name="name" type="string" required>
              The name of the function to call
            </ResponseField>

            <ResponseField name="arguments" type="string" required>
              JSON string containing the arguments
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="session_data" type="Object" required>
      Custom data that you specified in the [`SessionConfig`](https://docs.jay.so/references/configure-session#param-session-config) object
    </ResponseField>
  </Expandable>
</ResponseField>

Example `input` parameter:

```json theme={null}
{
  "function_calls": [
    {
      "id": "tool_call_001",
      "type": "function",
      "function": {
        "name": "get_weather",
        "arguments": "{"location": "New York"}"
      }
    }
  ],
  "session_data": {
    "my_user_id": "abc123"
  }
}
```

***

# `on_function_calls_executed`

Called after Jay has executed all the functions the model requested.

### Usage

```py theme={null}
from jay_ai import OnFunctionCallsExecutedInput

async def on_function_calls_executed(
  input: OnFunctionCallsExecutedInput
) -> None:
  ...

agent = Agent(
  on_function_calls_executed=on_function_calls_executed,
  ...
)
```

### Parameters

<ResponseField name="input" type="Object" required>
  <Expandable title="properties" defaultOpen="true">
    <ResponseField name="results" type="List[Object]" required>
      A list of results returned by each executed function.

      <Expandable title="properties" defaultOpen="false">
        <ResponseField name="tool_call_id" type="string" required>
          The ID that corresponds to the function call
        </ResponseField>

        <ResponseField name="role" type="string" required>
          Always "tool" for these messages
        </ResponseField>

        <ResponseField name="content" type="string" required>
          The output from the function
        </ResponseField>

        <ResponseField name="function" type="Object" required>
          The same function definition that was called

          <Expandable title="properties" defaultOpen="false">
            <ResponseField name="name" type="string" required>
              The name of the function
            </ResponseField>

            <ResponseField name="arguments" type="string" required>
              JSON string containing arguments the function was called with
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="session_data" type="Object" required>
      Custom data that you specified in the [`SessionConfig`](https://docs.jay.so/references/configure-session#param-session-config) object
    </ResponseField>
  </Expandable>
</ResponseField>

Example `input` parameter:

```json theme={null}
{
  "results": [
    {
      "tool_call_id": "tool_call_001",
      "role": "tool",
      "content": "{"temperature": "30F", "condition": "snow"}",
      "function": {
        "name": "get_weather",
        "arguments": "{"location": "New York"}"
      }
    }
  ],
  "session_data": {
    "my_user_id": "abc123"
  }
}
```