Skip to content

Turns in the ChatClient

spring-ai-session-turn-advisor runs every ChatClient call as a turn, with the turn service. It starts the turn before the call and ends it after. When the tool loop pauses on a tool call that needs a confirmation, it parks the turn instead of ending it. A later call with the person's decisions resumes it, on any instance.

Using it

Add the dependency, with its version from the BOM:

<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>spring-ai-session-turn-advisor</artifactId>
</dependency>

It brings the turn service and the Spring AI session advisors.

TurnAdvisors builds the advisor chain: the Spring AI session advisors, and the two advisors of this module around them.

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(TurnAdvisors.builder(sessionService).build())
    .defaultTools(tools)
    .build();

A call names its session, as with the Spring AI session advisors. When it pauses on a tool call, the response names the calls that await a decision, and the session is parked:

ChatResponse response = chatClient.prompt()
    .user("Book flight VX205")
    .advisors(SessionAdvisors.session(sessionId))
    .call()
    .chatResponse();

List<String> awaiting = ToolCallDecisions.awaitingDecision(response);   // ["c1"]; empty when the call did not pause

Later, on any instance, a call with the person's decisions and no user message resumes it:

ToolCallDecisions decisions = ToolCallDecisions.of(ToolCallDecision.allow("c1"));

chatClient.prompt()
    .advisors(TurnStatusAdvisor.decisions(sessionId, decisions))
    .call()
    .content();

TurnStatusAdvisor.decisions sets the session id and the decisions in the advisor context. The request must carry the tools of the allowed calls. Tools set with defaultTools are on every request. Tools passed to a single call must be passed again with the decisions.

The module uses these context keys:

Context key Value
session_tool_call_decisions (TOOL_CALL_DECISIONS_CONTEXT_KEY) The ToolCallDecisions that answer the parked tool calls.
session_run_id (RUN_ID_CONTEXT_KEY) The run id of the turn. TurnStatusAdvisor.runId(runId) sets it; the advisor sets it on the response. See the run id.
session_turn_id (TURN_ID_CONTEXT_KEY) The id of the turn. The advisor sets it on the request it forwards, for the interrupt check. You do not set it.

The run id

Each call runs as a turn under a run id. The advisor takes it from the request context under session_run_id, or generates one. It puts the run id into the context of the request it forwards and of the response.

TurnStatusAdvisor.runId(runId) sets the run id for a call that starts a turn and for one that resumes it:

chatClient.prompt()
    .user("Book flight VX205")
    .advisors(SessionAdvisors.session(sessionId))
    .advisors(TurnStatusAdvisor.runId("run-1"))
    .call()
    .content();

A resume without a run id runs under a new one. To keep the run id of the paused call, pass it with the decisions. The run id is stored in the session's log, so the status of a parked session still has it, on any instance and after a restart:

TurnService turns = new TurnService(sessionService);
String runId = turns.status(sessionId).runId();   // the run id of the parked turn

chatClient.prompt()
    .advisors(TurnStatusAdvisor.decisions(sessionId, decisions))
    .advisors(TurnStatusAdvisor.runId(runId))
    .call()
    .content();

The paused response has the same run id in its context, under TurnStatusAdvisor.RUN_ID_CONTEXT_KEY, for a caller that still holds it.

It wraps the Spring AI advisors

Spring AI 2.1 already has session advisors for the ChatClient. This module does not replace them. It adds one advisor in front of them and one behind them, and leaves them as they are.

Turns in the ChatClient The advisor chain of a ChatClient with the TurnStatusAdvisor of this project in front of the Spring AI session advisors and its TurnInterruptAdvisor behind them. TurnStatusAdvisor runs once per call: it starts, parks, resumes and ends the turn through the TurnService, which writes TURN events through the SessionService. SessionTurnAdvisor runs once per call: it creates the session and compacts it. ToolCallingAdvisor runs the loop and the tools through the ToolCallingManager, and pauses on a tool call that needs a confirmation; for each tool round the rest of the chain runs again. SessionMemoryAdvisor stores the messages and builds the prompt on every round. TurnInterruptAdvisor of this project checks on every round that the turn still runs, and stops the loop after an interrupt. ChatModelCallAdvisor, the last advisor, calls the chat model. The Spring AI advisors are unchanged. Turns in the ChatClient The advisor chain of a ChatClient advisors, by order (HIGHEST_PRECEDENCE + n) TurnStatusAdvisoronce per call: starts, parks, resumes, ends the turn+100 SessionTurnAdvisoronce per call: creates the session, compacts+200 ToolCallingAdvisorthe loop: runs tools, pauses on a confirmation+300 SessionMemoryAdvisorevery round: stores the messages, builds the prompt+1000 TurnInterruptAdvisorevery round: stops the loop after an interrupt+1100 ChatModelCallAdvisorcalls the modellast for each tool round what the chain calls TurnServiceTURN.STATUS, QUESTION, ANSWER events SessionServicethe event log, kept in a session store ToolCallingManager & Toolssome need a person's confirmation Spring AI Session Extensions Spring AI 2.1, unchanged ChatModel

A lower order runs further out. The ToolCallingAdvisor runs the advisors after it again for each tool round, so the SessionMemoryAdvisor stores every round. The TurnInterruptAdvisor runs on every round too, before the model is called. The TurnStatusAdvisor and the SessionTurnAdvisor run once per call. So the TurnStatusAdvisor sees the whole call, and it sees the response after the Spring AI advisors stored it.

The TurnStatusAdvisor does three things the Spring AI advisors do not:

  • It records the turn. start before the call, end after, park when the response is a paused reply.
  • It resumes a parked turn from decisions. The request carries the person's decisions and no user message.
  • It closes a pause when new text arrives. See new text on a parked session.

A paused tool call and its resume

Two calls. The first one pauses on a tool that needs a confirmation. The second one carries the decisions and finishes the turn.

sequenceDiagram
    participant A as Application
    participant T as TurnStatusAdvisor
    participant TS as TurnService
    participant S as Spring AI advisors<br/>(turn, tool loop, memory)
    participant M as Model

    A->>T: prompt "Book flight VX205"
    T->>TS: start(sessionId, runId)
    T->>S: request
    S->>M: prompt with the stored history
    M-->>S: reply: call bookFlight
    Note over S: memory stores the reply,<br/>tool loop pauses: bookFlight needs a confirmation
    S-->>T: paused reply
    T->>TS: park(sessionId, turn, ToolConfirmationQuestion)
    T-->>A: paused reply, awaiting a decision

    Note over A: the person decides, later,<br/>maybe on another instance

    A->>T: prompt with decisions, no user message
    T->>TS: resume(sessionId, runId, decisions)
    T->>T: run the allowed calls<br/>through the ToolCallingManager
    T->>T: store the results after the reply
    T->>S: request without messages
    S->>M: prompt: the turn so far and the results
    M-->>S: "Your flight is booked."
    S-->>T: answer
    T->>TS: end(sessionId, turn, END_TURN)
    T-->>A: answer

On the resume, the TurnStatusAdvisor stores the tool results right after the paused reply, and forwards the request without messages. Spring AI's turn advisor sees that the open calls have results and leaves them alone. Spring AI's memory advisor builds the prompt from the log, so the model gets the whole turn. When an allowed call's tool returns directly, its result is the answer, and the model is not called.

Asking the person

The paused response names the calls that await a decision. An application that still holds it can ask the person at once. Another instance, or the same one after a restart, reads the question from the session's log instead:

TurnService turns = new TurnService(sessionService);

SessionEvent pending = turns.pendingQuestion(sessionId);   // null when the session waits on nothing
ToolConfirmationQuestion question = ToolConfirmationQuestion.from(pending);

for (ToolConfirmationQuestion.ToolCall call : question.toolCalls()) {
    // call.name() and call.arguments() are what to show the person
    // call.awaitingDecision() tells whether the person must decide on it
}

The answer has one decision for each call, named by call.key():

List<ToolCallDecision> decisions = question.toolCalls().stream()
    .map(call -> !call.awaitingDecision() || approved(call)
            ? ToolCallDecision.allow(call.key())
            : ToolCallDecision.deny(call.key(), "The user declined the booking."))
    .toList();

chatClient.prompt()
    .advisors(TurnStatusAdvisor.decisions(sessionId, new ToolCallDecisions(decisions)))
    .call()
    .content();

approved stands for what the person chose. A call that does not await a decision needs no confirmation, so the example allows it.

ToolConfirmationQuestion.from refuses a question of another kind. When your harness also parks on questions of its own, read the kind first, with Question.from(pending).kind().

When the tools run

A paused reply can hold several tool calls, and only some of them may need a confirmation.

  • No call of a paused reply runs before the resume. Spring AI checks the whole reply before it runs any call. When one call needs a confirmation, none runs, also not the calls that need none.
  • The decisions cover every call of the reply. A call that needs no confirmation still needs a decision, because it has not run yet.
  • A denied call does not run. Its result is the message of the denial, and the model reads it.
  • An allowed call runs once, on the resume. The advisor records the answer first, then runs the calls, then stores the results. A second call with the same decisions is refused, because the question already has its answer.
  • The tool calls of earlier rounds already ran. A turn can run several tool rounds before one of them pauses. Their results are in the log, and the resume does not touch them.

Decisions name the calls by key, not the question they answer. When the turn has parked again on a new question, decisions made for the old one are refused because their keys do not match the new reply. A model that sends no tool call ids gets position keys (#0, #1), and there old decisions can match the calls of the new question.

When a resume fails

The answer is recorded before the tools run. So an allowed call runs at most once, and a failure never runs it a second time.

  • The run of the allowed calls fails. The turn ends with ERROR. Every call of the reply gets the result "No result was recorded for this tool call.", so the log keeps no call without a result.
  • The instance dies during the resume. The turn stays RUNNING, and another resume is refused. A tool may have run without its result in the log. Free the session with TurnService.interrupt. On the next call, Spring AI's turn advisor gives the calls without a result the same "No result was recorded" result.

What the TurnStatusAdvisor decides on each call

flowchart TD
    A([A call arrives]) --> R{Does another turn run?}
    R -- yes --> X([Refuse with TurnInProgressException])
    R -- no --> B{Is the session parked?}
    B -- no --> C[start the turn]
    B -- yes --> D{Does the request carry decisions?}
    D -- yes --> E[resume with the decisions,<br/>run the allowed calls,<br/>store the results]
    D -- no --> F[resume with every call denied,<br/>store the denials,<br/>send the text on]
    C --> G[Forward to the Spring AI advisors]
    E --> G
    F --> G
    G --> H{Is the response a paused reply?}
    H -- yes --> I([park the turn on the question])
    H -- no --> J{Did the call fail?}
    J -- no --> K([end with END_TURN])
    J -- yes --> L([end with ERROR])

Refused requests

These requests are refused, and nothing is written:

Request Exception
Any call while another turn runs on the session TurnInProgressException
Decisions on a session that is not parked, or that does not exist IllegalStateException
Decisions on a session parked on a question of another kind, or whose paused reply is no longer its newest message IllegalStateException
Decisions for a question another caller answered first IllegalStateException, or TurnInProgressException while that caller's turn runs
Decisions together with a user message IllegalArgumentException
Decisions that miss a call of the paused reply, or name a call it does not have IllegalArgumentException
An allowed call whose tool the request does not carry IllegalArgumentException

An IllegalArgumentException means the request is wrong. An IllegalStateException means the session is not in a state for it.

New text on a parked session

New text always moves a parked session on. The person did not decide, so the advisor closes the question before the text goes on:

  • The session waits on the tool confirmation of its newest reply. The advisor stores a denial for each open tool call, with the text of TurnStatusAdvisor.ABANDONED_DENY_MESSAGE. The log then says the calls were denied, not that they have no result.
  • The session waits on a question of another kind, or the log changed since it parked. The question gets an empty answer, and no tool runs.

Interrupting a running call

TurnService.interrupt(sessionId, reason) ends the running turn at once, from a stop button or another instance. The session is then free for the next turn.

The interrupted call must stop too. Otherwise its tool loop goes on, and its messages land in between those of the next turn. The TurnInterruptAdvisor stops it. Before each model round it checks that the call's turn still runs, and throws TurnInterruptedException when it does not. The rounds that already ran stay in the log, with their tool results.

try {
    chatClient.prompt().user("...").advisors(SessionAdvisors.session(sessionId)).call().content();
}
catch (TurnInterruptedException ex) {
    // ex.getStatus().stopReason() is INTERRUPTED
}

With stream() the exception is the error signal of the Flux. The failed call does not change the status: it stays as the interrupt left it. The check is one indexed read per model round. A tool that already runs is not stopped: the loop stops before the next model round. TurnAdvisors adds the advisor by default, and interruptible(false) leaves it out.

Configuring the advisors

TurnAdvisors builds the whole chain at the right orders. The settings the advisors share are set once, so they cannot differ.

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(TurnAdvisors.builder(sessionService)
        .sessionIdInToolContext(true)
        .sessionAdvisors(session -> session.compaction(trigger, strategy))
        .build())
    .build();
Setting What it does
sessionIdInToolContext(true) Tools get the session id in their tool context. It applies to the calls of the loop and to the allowed calls of a resume alike.
toolCallingManager(manager) The manager that runs the allowed calls of a resume. Use the one the ChatClient's tool-calling advisor uses.
scheduler(scheduler) The scheduler for the session calls of a streamed call, for every advisor.
interruptible(false) Leaves the TurnInterruptAdvisor out.
sessionAdvisors(session -> ...) The settings of the Spring AI session advisors, compaction for example.

You can also build the three parts yourself, with TurnStatusAdvisor.builder, SessionAdvisors.builder and TurnInterruptAdvisor.builder.

Streaming

A streamed call works the same way. A streamed pause ends on a last chunk that names the calls awaiting a decision, and the advisor parks the turn when the stream completes. A stream that fails ends the turn with ERROR. A stream the client cancels ends it with CANCELLED, also when the client leaves while the turn is still starting. A client that cancels after the last chunk does not change the outcome: the turn is parked or ended as the stream finished. The session calls run on a scheduler, never on the model's thread, and a cancel never interrupts them.