Class SessionTurnAdvisor

java.lang.Object
org.springframework.ai.session.advisor.SessionTurnAdvisor
All Implemented Interfaces:
Advisor, CallAdvisor, StreamAdvisor, org.springframework.core.Ordered

public final class SessionTurnAdvisor extends Object implements CallAdvisor, StreamAdvisor
Runs each ChatClient call as one turn of the session. A turn is one user message and everything up to the next: the tool rounds and the reply, the unit the chat memory's turn-boundary eviction works with too. The advisor sits outside the tool-calling loop (order DEFAULT_ORDER), so it sees the request before the first round and the turn's final response after the last one, however the loop ended; what happens once per turn is its, what happens once per model round is the SessionMemoryAdvisor's, inside the loop.
  1. Finds the session or creates it on first use, with the metadata from SessionMemoryAdvisor.SESSION_METADATA_CONTEXT_KEY, such as the agent attributes.
  2. With SessionTurnAdvisor.Builder.sessionIdInToolContext(boolean), puts the session id into the tool context of the call, so that a tool that reads the session, the session recall tools for example, finds it without the caller passing it a second time. Off by default, because the tool context goes to every tool of the call.
  3. Before a new turn, answers the tool calls the conversation ends with when they have no results, with UNANSWERED_TOOL_RESULT: a tool call that waited for a person's confirmation and never got one, or a loop that failed after the reply was stored. The log then keeps the call with a result, so the model sees what it asked for and the memory advisor has nothing to drop from the prompt. A request that brings results for those calls, as the resume of a confirmation does, is left alone. The advisor cannot tell an abandoned call from one whose tool still runs in another call on the same session, so a session takes one call at a time.
  4. After a loop that ended on a returnDirect tool or a breached tool call limit, stores the reply's tool results, which no model round stored.
  5. Compacts the session once the call has returned, if a trigger fires: before the reply is returned, or after it on the scheduler with SessionTurnAdvisor.Builder.asyncCompaction(boolean). Compaction is best-effort: a failure is logged and the reply returned, and it is retried after the next turn. It appends a boundary with an optimistic compare-and-swap, so of two concurrent compactions only the first lands; a compaction that a new turn's writes overtake keeps them in the view and lands with the same summary.
On its own the advisor stores no conversation: it needs the memory advisor, and SessionAdvisors builds the two together at their orders. The memory advisor alone keeps the history, without compaction.
Since:
2.1.0
Author:
Christian Tzolov
  • Field Details

    • DEFAULT_ORDER

      public static final int DEFAULT_ORDER
      Outside the tool-calling advisor (HIGHEST_PRECEDENCE + 300), so the loop runs inside the turn.
      See Also:
    • NOT_RUN_TOOL_RESULT

      public static final String NOT_RUN_TOOL_RESULT
      The result a tool call gets in the log when the loop ended before it ran.
      See Also:
    • UNANSWERED_TOOL_RESULT

      public static final String UNANSWERED_TOOL_RESULT
      The result a tool call gets in the log when a new turn starts and the call still has none: the turn that made it paused for a confirmation that never came, or failed before its results were stored. It says what the log knows and no more: the tool may have run.
      See Also:
  • Method Details