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