Class SessionRecallTools

java.lang.Object
org.springframework.ai.session.tool.SessionRecallTools

public final class SessionRecallTools extends Object
Lets a model search the conversation of its session: the conversation_search tool. A compaction keeps the prompt small by taking older messages out of it; they stay in the log, and this tool is how the model finds them again, by keyword (see EventQuery).

The tool searches one session, the one named in the ToolContext under SESSION_ID_CONTEXT_KEY. The model never names the session. The key is the one the session advisors read, but advisor parameters do not reach a tool, so the caller passes the session id to both:


 ChatClient client = ChatClient.builder(chatModel)
     .defaultAdvisors(SessionAdvisors.builder(sessionService).build())
     .defaultTools(SessionRecallTools.builder(sessionService).build())
     .build();

 client.prompt()
     .user(text)
     .advisors(SessionAdvisors.session(sessionId))
     .toolContext(Map.of(SessionRecallTools.SESSION_ID_CONTEXT_KEY, sessionId))
     .call();
 
With a tool context that holds no session id the tool searches nothing and tells the model so. With no tool context at all the tool is not called: the tool-calling machinery fails the call, because the tool takes a ToolContext. The session advisors can put the session id into the tool context themselves, with SessionAdvisors.builder(sessionService).sessionIdInToolContext(true); every tool of the call then sees it.

Read-only: the tool appends, compacts and deletes nothing.

Since:
2.1.0
Author:
Christian Tzolov
  • Field Details

    • SESSION_ID_CONTEXT_KEY

      public static final String SESSION_ID_CONTEXT_KEY
      The ToolContext key of the session to search. The same key as the session advisors' SessionMemoryAdvisor.SESSION_ID_CONTEXT_KEY.
      See Also:
    • DEFAULT_MAX_TEXT_LENGTH

      public static final int DEFAULT_MAX_TEXT_LENGTH
      The longest text a result carries by default, in characters.
      See Also:
  • Method Details

    • builder

      public static SessionRecallTools.Builder builder(SessionService sessionService)
    • conversationSearch

      @Tool(name="conversation_search", description="Search the earlier conversation of this session for messages that contain the given keywords, ignoring case. It also finds messages that are no longer in your context. Returns one page of matches, oldest first, as JSON: \'results\' with the timestamp, the type and the text of each message, and \'nextPage\' when more matches may follow. A long text is cut to an excerpt around the keyword.") public String conversationSearch(@ToolParam(description="One or more keywords, separated by commas. Each keyword is matched as literal text, so \'invoice, refund\' looks for two words and \'invoice refund\' for that exact phrase.") String query, @ToolParam(description="\'any\' (the default): a message matches when it contains one of the keywords. \'all\': it must contain every keyword.",required=false) @Nullable String match, @ToolParam(description="The page of matches, starting at 0. Omit it for the first page.",required=false) @Nullable Integer page, ToolContext toolContext)
      Searches the session's conversation for messages that contain the keywords. Returns a page of matches, oldest first, as JSON: results, each with a timestamp, a type and a text, and nextPage when the page is full and more matches may follow. A long text is cut to an excerpt around the first keyword it holds. Returns a short text when nothing matches or the search cannot run.