session#

class baf.core.session.Session(session_id, agent, platform, username=None, session_name=None)[source]#

Bases: object

A user session in an agent execution.

When a user starts interacting with an agent, a session is assigned to him/her to store user related information, such as the current state of the agent, the conversation history, the detected intent with its parameters or any user’s private data. A session can be accessed from the body of the states to read/write user information.

Parameters:

  • session_id (str) – The session id, which must unique among all agent sessions

  • agent (Agent) – The agent the session belongs to

  • platform (Platform) – The platform where the session has been created

  • username (str) – the name of the session user (optional)

  • session_name (str) – the name of the session (optional)

_id#

The session id, which must unique among all agent sessions

Type:

str

_username#

the name of the session user (optional)

Type:

str

_session_name#

the name of the session (optional)

Type:

str

_agent#

The agent the session belongs to

Type:

str

_platform#

The platform where the session has been created

Type:

str

_current_state#

The current state in the agent for this session

Type:

str

_dictionary#

Storage of private data for this session

Type:

str

_event#

The last event to trigger a transition.

Type:

Any or None

_events#

The queue of received external events to process

Type:

deque[Any]

_event_loop#

The loop in charge of managing incoming events

Type:

asyncio.AbstractEventLoop

_event_thread#

The thread where the event loop is running

Type:

threading.Thread

_timer_handle#

Handler of scheduled calls on the event loop

Type:

TimerHandle

_agent_connections#

WebSocket client connections to other agent’s WebSocket platforms. These connections enable an agent to send messages to other agents.

Type:

dict[str, WebSocketApp]

_run_event_thread()[source]#

Start the thread managing external events

_stop_event_thread()[source]#

Stop the thread managing external events

call_manage_transition()[source]#

Schedule the next call to manage_transition as soon as possible (cancelling the previously scheduled call).

create_agent_connection(url)[source]#

Create a WebSocket connection to a specific WebSocket URL.

Parameters:

url (str) – the WebSocket server’s URL

property current_state#

The current agent state of the session.

Type:

State

property db_handler#

relational DB handler configured for this agent.

Type:

DBHandler

delete(key)[source]#

Delete an entry of the session private data storage.

Parameters:

key (str) – the entry key

property event#

The last event matched by the agent.

Type:

Event

property events#

The queue of pending events for this session

Type:

dequeue[Event]

get(key, default=None)[source]#

Get an entry of the session private data storage.

Parameters:

  • key (str) – the entry key

  • default (Any) – The default value to be returned, if the dictionary does not contain the key

Returns:

the entry value, default or None if the key does not exist

Return type:

Any

get_chat_history(n=None, until_timestamp=None)[source]#

Get the history of messages between this session and its agent.

Parameters:

n (int or None) – the number of messages to get (from the most recents). If none is provided, gets all the messages

Returns:

the conversation history

Return type:

list[Message]

get_dictionary()[source]#

Returns the private data dictionary for this session.

Returns:

The session’s private data storage.

Return type:

dict[str, Any]

get_reasoning_events(until_timestamp=None)[source]#

Get the reasoning-state events for this session.

Includes both step events and task-list snapshots, ordered by their emission timestamp.

Parameters:

until_timestamp (datetime) – if provided, only events at or before this timestamp are returned.

Returns:

each entry has kind, step_kind, step, summary, payload, timestamp, chat_id keys (some may be None depending on kind).

Return type:

list[dict]

property id#

The session id.

Type:

str

Link reasoning events with chat_id IS NULL to the most recent chat row for this session. Called once at the end of each reasoning loop so the events emitted during that loop are tied to the chat reply that closed it.

manage_transition()[source]#

Evaluate the session’s current state transitions, where one could be satisfied and triggered.

move(transition)[source]#

Move to another agent state.

Parameters:

transition (Transition) – the transition that points to the agent state to move

property platform#

The session platform.

Type:

Platform

reply(message)[source]#

An agent message (usually a reply to a user message) is sent to the session platform to show it to the user.

Parameters:

message (str) – the agent reply

run_rag(message, llm_prompt=None, llm_name=None, k=None, num_previous_messages=None)[source]#

Run the RAG engine.

Parameters:

  • message (str) – the input query for the RAG engine

  • llm_prompt (str) – the prompt containing the instructions for the LLM to generate an answer from the retrieved content. If none is provided, the RAG’s default value will be used

  • llm_name (str) – the name of the LLM to use. If none is provided, the RAG’s default value will be used

  • k (int) – number of chunks to retrieve from the vector store. If none is provided, the RAG’s default value will be used

  • num_previous_messages (int) – number of previous messages of the conversation to add to the prompt context. If none is provided, the RAG’s default value will be used. Necessary a connection to MonitoringDB

Returns:

the answer generated by the RAG engine

Return type:

RAGMessage

save_message(message)[source]#

Save a message in the dedicated chat DB

Parameters:

message (Message) – the message to save

save_reasoning_event(kind, payload)[source]#

Persist a reasoning-state event in the dedicated reasoning_step table.

Reasoning events (LLM tool calls, tool results, task list mutations, push-backs, max_steps, reasoning_started/finished brackets) are NOT stored in the chat table because they would mismatch the chat message-type schema. This method routes them to their own table.

Parameters:

  • kind (str) – 'reasoning_step' for a single ReasoningStep event, or 'task_list_update' for a full task list snapshot.

  • payload (Any) – the structured event payload — a step dict or a list of task dicts.

send_message_to_websocket(url, message)[source]#

Send a message to a WebSocket Server, generally used to send a message to an agent through the WebSocket platform.

Parameters:

  • url (str) – the WebSocket URL (i.e., the target agent’s WebSocket platform URL)

  • message (Any) – the message to send to the WebSocket server

set(key, value)[source]#

Set an entry to the session private data storage.

Parameters:

  • key (str) – the entry key

  • value (Any) – the entry value