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
An agent emits the following events:
on_agent_started_speakingCalled 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 Example input parameter:
{ "session_data" : { "my_user_id" : "abc123" , } } on_user_started_speakingCalled 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 Example input parameter:
{ "session_data" : { "my_user_id" : "abc123" } } on_user_stopped_speakingCalled 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 Example input parameter:
{ "session_data" : { "my_user_id" : "abc123" } } on_agent_stopped_speakingCalled 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 Example input parameter:
{ "session_data" : { "my_user_id" : "abc123" } } on_user_message_addedCalled 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 The user’s message that was added to the chat history most recently.
The text of the user’s message
The role of the speaker (always “user”)
An optional speaker name. Defaults to None.
If the role is "tool", this is the tool call ID that this message is responding to. Otherwise, it’s None.
Example input parameter:
{ "message" : { "content" : "Hello, agent!" , "role" : "user" , "name" : "Bob" , "tool_call_id" : None }, "session_data" : { "my_user_id" : "abc123" } } on_agent_message_addedCalled 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 The message produced by the agent.
The text the agent is responding with
The role of the speaker (in this case, “assistant”)
An optional speaker name. Defaults to None.
Internal ID if this message is responding to a tool call. Defaults to None.
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_interruptedCalled 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 Agent message up until it was interrupted.
The text the agent was speaking
The role of the speaker (in this case, “assistant”)
An optional speaker name. Defaults to None.
Internal ID if this message is part of a tool call. Defaults to None.
Example input parameter:
{ "message" : { "content" : "Hello the-" , "role" : "assistant" , "name" : None , "tool_call_id" : None }, "session_data" : { "my_user_id" : "abc123" } } on_function_calls_collectedCalled 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 List of function calls the model requested.
The type of call; always the string “function”
The name of the function to call
JSON string containing the arguments
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_executedCalled 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 A list of results returned by each executed function.
The ID that corresponds to the function call
Always “tool” for these messages
The output from the function
The same function definition that was called
JSON string containing arguments the function was called with
Example input parameter:
{ "results" : [ { "tool_call_id" : "tool_call_001" , "role" : "tool" , "content" : "{" temperature ": " 30 F ", " condition ": " snow "}" , "function" : { "name" : "get_weather" , "arguments" : "{" location ": " New York "}" } } ], "session_data" : { "my_user_id" : "abc123" } }