Package io.jmix.aitools.tool

Class AiToolStatusPublisher

java.lang.Object

io.jmix.aitools.tool.AiToolStatusPublisher

@Component("aitls_AiToolStatusPublisher")
public class AiToolStatusPublisher
extends Object

Lets AI tools surface ephemeral status updates to a status consumer (e.g. the UI).

The callback is placed into the ToolContext by AiConversationChatService under STATUS_UPDATE_CALLBACK. If no callback was provided by the caller (typical for non-UI scenarios), all methods on this publisher are silent no-ops.

Typical tool usage — two-phase publish so the UI can render an in-flight indicator and a result snippet:

 String msg = "Searching customers by name";
 statusPublisher.update(toolContext, msg);
 String result = customerRepo.searchByName(...);   // long-running work
 statusPublisher.complete(toolContext, msg, "found " + result.size());
 

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DEFAULT_TOOL_CONTEXT_MARKER	Key of the marker entry that the add-on places into the default ToolContext of its chat clients, so it is visible to every tool invocation, including application-defined ones.
static final String	STATUS_UPDATE_CALLBACK

Constructor Summary

Constructors

Constructor	Description
AiToolStatusPublisher()

Method Summary

Modifier and Type	Method	Description
void	complete(String message, @Nullable String snippet, @Nullable org.springframework.ai.chat.model.ToolContext toolContext)	Publishes the completion of a previously-started step.
void	publish(AiToolStatusUpdate update, @Nullable org.springframework.ai.chat.model.ToolContext toolContext)	Forwards an arbitrary AiToolStatusUpdate through the status callback.
void	update(String message, @Nullable org.springframework.ai.chat.model.ToolContext toolContext)	Publishes an in-flight status update — "this step has started, no result yet".

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

STATUS_UPDATE_CALLBACK

public static final String STATUS_UPDATE_CALLBACK

See Also:

• Constant Field Values

DEFAULT_TOOL_CONTEXT_MARKER

public static final String DEFAULT_TOOL_CONTEXT_MARKER

Key of the marker entry that the add-on places into the default ToolContext of its chat clients, so it is visible to every tool invocation, including application-defined ones.

Only the presence of the key is part of the contract — its value is unspecified and may change. An application whose tool iterates, logs or forwards the tool context should reference this constant to recognise and skip the entry rather than hard-coding the string.

See Also:

• Constant Field Values

Constructor Details

AiToolStatusPublisher

public AiToolStatusPublisher()

Method Details

update

public void update(String message,
 @Nullable org.springframework.ai.chat.model.ToolContext toolContext)

Publishes an in-flight status update — "this step has started, no result yet". Sends an AiToolStatusUpdate with a blank resultSnippet.

Parameters:

message - status text describing the step that has started

toolContext - current tool context carrying the UI callback; null (no callback) makes this a no-op

complete

public void complete(String message,
 @Nullable String snippet,
 @Nullable org.springframework.ai.chat.model.ToolContext toolContext)

Publishes the completion of a previously-started step.

The message must match the one passed to update(String, ToolContext) so the UI can fold the two into a single completed entry. A blank snippet is treated as "nothing to report" and the call is a silent no-op.

Parameters:

message - same status text that was passed to update(String, ToolContext)

snippet - short result of the finished step; blank or null makes this a no-op

toolContext - current tool context carrying the UI callback; null (no callback) makes this a no-op

publish

public void publish(AiToolStatusUpdate update,
 @Nullable org.springframework.ai.chat.model.ToolContext toolContext)

Forwards an arbitrary AiToolStatusUpdate through the status callback.

Note, prefer:

• update(String, ToolContext)
• complete(String, String, ToolContext)

which encode the two-phase contract correctly.

Parameters:

update - status update to deliver; ignored if its message is blank

toolContext - current tool context carrying the UI callback; null (no callback) makes this a no-op