Function addCommitAction

addCommitAction<T = Record<string, any>>(
params: ICommitActionToolParams<T>,
): string

Creates and registers a commit action tool for AI to execute actions (WRITE pattern). This implements the WRITE side of the command pattern - AI calls tool to modify system state.

Flow:

AI calls tool with parameters
validateParams runs (if provided) - validates parameters and returns error message or null
If validation fails:
- Error message is committed as tool output
- failureMessage is executed (or error message if failureMessage not provided)
- Flow stops
If validation passes:
- executeAction runs - performs the action
- Action result is committed as tool output (or emptyContent if result is empty)
- successMessage is executed

Type Parameters

T = Record<string, any>
The type of parameters expected by the action

Parameters

params: ICommitActionToolParams<T>
Configuration object for the action tool

Returns string

The registered agent tool schema

Function

addCommitAction

Example

// Payment action with validation, error handling and follow-up
addCommitAction({
  toolName: "pay_credit",
  function: {
    name: "pay_credit",
    description: "Process credit payment",
    parameters: {
      type: "object",
      properties: {
        bank_name: { type: "string", enum: ["bank1", "bank2"] },
        amount: { type: "string", description: "Amount in currency" },
      },
      required: ["bank_name", "amount"],
    },
  },
  fallback: (error, clientId, agentName) => {
    logger.error("Payment execution failed", { error, clientId, agentName });
  },
  validateParams: async ({ params, clientId, agentName, toolCalls }) => {
    if (!params.bank_name) return "Bank name is required";
    if (!params.amount) return "Amount is required";
    return null; // Valid
  },
  executeAction: async (params, clientId) => {
    await commitAppAction(clientId, "credit-payment", params);
    return "Payment page opened successfully";
  },
  successMessage: "what is this page about",
  failureMessage: "Could not process payment",
});