Class SessionTurnAdvisor
java.lang.Object
org.springframework.ai.session.advisor.SessionTurnAdvisor
- All Implemented Interfaces:
Advisor,CallAdvisor,StreamAdvisor,org.springframework.core.Ordered
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.
- Finds the session or creates it on first use, with the metadata from
SessionMemoryAdvisor.SESSION_METADATA_CONTEXT_KEY, such as the agent attributes. - 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. - 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. - After a loop that ended on a
returnDirecttool or a breached tool call limit, stores the reply's tool results, which no model round stored. - Compacts the session once the call has returned, if a
triggerfires: before the reply is returned, or after it on the scheduler withSessionTurnAdvisor.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.
SessionAdvisors builds the two together at their orders. The memory advisor
alone keeps the history, without compaction.- Since:
- 2.1.0
- Author:
- Christian Tzolov
-
Nested Class Summary
Nested Classes -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intOutside the tool-calling advisor (HIGHEST_PRECEDENCE + 300), so the loop runs inside the turn.static final StringThe result a tool call gets in the log when the loop ended before it ran.static final StringThe 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.Fields inherited from interface org.springframework.ai.chat.client.advisor.api.Advisor
DEFAULT_CHAT_MEMORY_PRECEDENCE_ORDERFields inherited from interface org.springframework.core.Ordered
HIGHEST_PRECEDENCE, LOWEST_PRECEDENCE -
Method Summary
Modifier and TypeMethodDescriptionadviseCall(ChatClientRequest request, CallAdvisorChain chain) reactor.core.publisher.Flux<ChatClientResponse>adviseStream(ChatClientRequest request, StreamAdvisorChain chain) static SessionTurnAdvisor.Builderbuilder(SessionService sessionService) getName()Return the name of the advisor.intgetOrder()
-
Field Details
-
DEFAULT_ORDER
public static final int DEFAULT_ORDEROutside the tool-calling advisor (HIGHEST_PRECEDENCE + 300), so the loop runs inside the turn.- See Also:
-
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
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
-
builder
-
getName
Description copied from interface:AdvisorReturn the name of the advisor. -
getOrder
public int getOrder()- Specified by:
getOrderin interfaceorg.springframework.core.Ordered
-
adviseCall
- Specified by:
adviseCallin interfaceCallAdvisor
-
adviseStream
public reactor.core.publisher.Flux<ChatClientResponse> adviseStream(ChatClientRequest request, StreamAdvisorChain chain) - Specified by:
adviseStreamin interfaceStreamAdvisor
-