Package org.springframework.ai.model.tool

Record Class ToolCallDecisions

java.lang.Object
java.lang.Record
org.springframework.ai.model.tool.ToolCallDecisions
Record Components:
decisions - one decision per tool call of the reply, with distinct keys
public record ToolCallDecisions(List<ToolCallDecision> decisions) extends Record
The decisions a person made on the tool calls of an AssistantMessage, for a ToolCallingManager to carry them out.

A manager pauses a batch when one of its calls needs confirmation (see ToolCallConfirmationPolicy), by throwing ToolCallConfirmationRequiredException before any call runs. A tool-calling loop then returns the reply to the caller, listing the keys of the calls that wait for a decision under AWAITING_DECISION_METADATA_KEY in the response metadata (awaitingDecision(ChatResponse)). The caller shows them to a person and runs the reply's calls with the decisions through ToolCallingManager.executeToolCalls(org.springframework.ai.chat.prompt.Prompt, ChatResponse, ToolCallDecisions): the allowed calls run, a denied call answers the model with its message. The tool results then go to the model as part of the next request.

Every tool call of the reply needs a decision, and an allowed call runs only with a tool the prompt carries. The reply the calls come from must be the one the model gave, read from storage the end user cannot change: whoever can edit it can run any tool with any arguments.

Decisions name the calls by their keys (toolCallKeys(AssistantMessage)): a call's id, or its position in the reply when the model gave it no id, or the same id as another call. The reply itself is never changed.

Since:
2.1.0
Author:
Christian Tzolov

  • Field Details

    • POSITION_KEY_PREFIX

      public static final String POSITION_KEY_PREFIX
      The prefix of the key of a tool call that has no id of its own, followed by the call's position in the reply, starting at 0.
      See Also:

    • AWAITING_DECISION_METADATA_KEY

      public static final String AWAITING_DECISION_METADATA_KEY
      The response metadata key under which a paused loop lists the keys of the tool calls that wait for a decision, as a List<String>. When streaming, the key is on the last chunk only; the aggregated response does not carry it.
      See Also:

  • Constructor Details

    • ToolCallDecisions

      public ToolCallDecisions(List<ToolCallDecision> decisions)
      Creates an instance of a ToolCallDecisions record class.
      Parameters:
      decisions - the value for the decisions record component

  • Method Details

    • of

      public static ToolCallDecisions of(ToolCallDecision... decisions)
      The decisions, one per tool call.

    • decisionOn

      public @Nullable ToolCallDecision decisionOn(String toolCallId)
      The decision on the tool call with the key, or null when there is none.

    • toolCallKeys

      public static List<String> toolCallKeys(AssistantMessage message)
      The keys of the tool calls of the message, in the order the model asked for them: a call's id when it has one that no other call of the message shares, otherwise POSITION_KEY_PREFIX followed by the call's position, such as #1. Decisions name the calls by these keys. Some model providers return tool calls without ids; their calls are named by position, and the message keeps its calls as the model gave them.
      Parameters:
      message - the reply with the tool calls
      Returns:
      one key per tool call, all distinct

    • awaitingDecision

      public static List<String> awaitingDecision(@Nullable ChatResponse chatResponse)
      The keys of the tool calls a paused loop waits on (see toolCallKeys(AssistantMessage)), or an empty list when the response is not a paused one. When streaming, ask the last chunk; the aggregated response does not carry the keys.

      Only a response tells a paused reply apart: read it with chatResponse() or chatClientResponse(). The text that content() returns is the paused reply's text, often empty, and a streamed content() simply ends.

    • isAwaitingDecision

      public static boolean isAwaitingDecision(@Nullable ChatResponse chatResponse)
      Whether the response is a paused one, with tool calls waiting for a decision.

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with Objects::equals(Object,Object).
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • decisions

      public List<ToolCallDecision> decisions()
      Returns the value of the decisions record component.
      Returns:
      the value of the decisions record component