@hexos/react-coreHook that registers a frontend action the agent can trigger, with optimistic update support.
Actions are like FrontendToolDefinitions but designed for state mutations.
They support optimistic updates (apply changes immediately before the async handler
resolves) and automatic rollback on errors. An optional confirmationMessage triggers
a confirmation dialog before execution.
The action is registered in frontendToolsAtom so the agent can invoke it. Execution state is tracked globally in executingActionsAtom for observability. The action is automatically unregistered when the component unmounts.
Related: ActionDefinition defines the action structure,
useAgentTool is for read-only tools, ActionConfirmDialog renders
confirmation UI when confirmationMessage is set.
Example
const { execute, isExecuting, error } = useAgentAction({
name: 'add_todo_item',
description: 'Adds a new item to the todo list',
inputSchema: z.object({
title: z.string(),
priority: z.enum(['low', 'medium', 'high']),
}),
handler: async (input) => {
await api.createTodoItem(input);
},
optimisticUpdate: (input) => {
setItems(prev => [...prev, { ...input, id: 'temp-' + Date.now(), status: 'pending' }]);
},
rollback: (input, error) => {
setItems(prev => prev.filter(item => !item.id.startsWith('temp-')));
toast.error('Failed to add item: ' + error.message);
},
});function useAgentAction<TInput>(definition: ActionDefinition<TInput>): UseAgentActionReturn<TInput>Parameters