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:

EventDescription
on_agent_started_speakingAgent started speaking
on_user_started_speakingUser started speaking
on_agent_stopped_speakingAgent stopped speaking
on_user_stopped_speakingUser stopped speaking
on_agent_message_addedAgent message added to the chat history during the session
on_user_message_addedUser message added to the chat history during the session
on_agent_interruptedAgent was interrupted by the user while speaking
on_function_calls_collectedJay received the complete set of functions to execute from the LLM
on_function_calls_executedJay 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
​
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
​
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
​
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
​
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
​
message
Object
required

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

​
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
​
message
Object
required

The message produced by the agent.

​
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
​
message
Object
required

Agent message up until it was interrupted.

​
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
​
function_calls
List[Object]
required

List of function calls the model requested.

​
id
string
required

The ID of the tool call

​
type
string
required

The type of call; always the string “function”

​
function
Object
required
​
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
​
results
List[Object]
required

A list of results returned by each executed function.

​
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

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