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, as shown in the “Usage” sections below.

An agent emits the following events:

Event	Description
on_agent_started_speaking	Agent started speaking
on_user_started_speaking	User started speaking
on_agent_stopped_speaking	Agent stopped speaking
on_user_stopped_speaking	User stopped speaking
on_agent_message_added	Agent message added to the chat history during the session
on_user_message_added	User message added to the chat history during the session
on_agent_interrupted	Agent was interrupted by the user while speaking
on_function_calls_collected	Jay received the complete set of functions to execute from the LLM
on_function_calls_executed	Jay executed all of the functions that were collected

---

---

on_agent_started_speaking

Called when the agent begins speaking.

Usage

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

input · Object · required

Hide properties

session_data · Object · required

Custom data that you specified in the SessionConfig object

Example input parameter:

{
  "session_data": {
    "my_user_id": "abc123",
  }
}

---

on_user_started_speaking

Called when the user starts speaking.

Usage

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

input · Object · required

Hide properties

session_data · Object · required

Custom data that you specified in the SessionConfig object

Example input parameter:

{
  "session_data": {
    "my_user_id": "abc123"
  }
}

---

on_user_stopped_speaking

Called when the user stops speaking.

Usage

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

input · Object · required

Hide properties

session_data · Object · required

Custom data that you specified in the SessionConfig object

Example input parameter:

{
  "session_data": {
    "my_user_id": "abc123"
  }
}

---

on_agent_stopped_speaking

Called when the agent finishes speaking.

Usage

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

input · Object · required

Hide properties

session_data · Object · required

Custom data that you specified in the SessionConfig object

Example input parameter:

{
  "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

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

input · Object · required

Hide properties

message · Object · required

The user’s message that was added to the chat history most recently.

Show properties

content · string · required

The text of the user’s message

role · string · required

The role of the speaker (always “user”)

name · string | None

An optional speaker name. Defaults to None.

tool_call_id · string | None

If the role is "tool", this is the tool call ID that this message is responding to. Otherwise, it’s None.

input · Object · required

Custom data that you specified in the SessionConfig object

Example input parameter:

{
  "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

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

input · Object · required

Hide properties

message · Object · required

The message produced by the agent.

Show properties

content · string · required

The text the agent is responding with

role · string · required

The role of the speaker (in this case, “assistant”)

name · string | None

An optional speaker name. Defaults to None.

tool_call_id · string | None

Internal ID if this message is responding to a tool call. Defaults to None.

session_data · Object · required

Custom data that you specified in the SessionConfig object

Example input parameter:

{
  "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

from jay_ai import OnAgentInterruptedInput

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

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

Parameters

input · Object · required

Hide properties

message · Object · required

Agent message up until it was interrupted.

Show properties

content · string · required

The text the agent was speaking

role · string · required

The role of the speaker (in this case, “assistant”)

name · string | None

An optional speaker name. Defaults to None.

tool_call_id · string | None

Internal ID if this message is part of a tool call. Defaults to None.

session_data · Object · required

Custom data that you specified in the SessionConfig object

Example input parameter:

{
  "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

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

input · Object · required

Hide properties

function_calls · List[Object] · required

List of function calls the model requested.

Show properties

id · string · required

The ID of the tool call

type · string · required

The type of call; always the string “function”

function · Object · required

Show properties

name · string · required

The name of the function to call

arguments · string · required

JSON string containing the arguments

session_data · Object · required

Custom data that you specified in the SessionConfig object

Example input parameter:

{
  "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

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

input · Object · required

Hide properties

results · List[Object] · required

A list of results returned by each executed function.

Show properties

tool_call_id · string · required

The ID that corresponds to the function call

role · string · required

Always “tool” for these messages

content · string · required

The output from the function

function · Object · required

The same function definition that was called

Show properties

name · string · required

The name of the function

arguments · string · required

JSON string containing arguments the function was called with

session_data · Object · required

Custom data that you specified in the SessionConfig object

Example input parameter:

{
  "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"
  }
}