AgentXin Plugin: Model Retry Middleware

@agentxin-ai/plugin-model-retry adds retry logic around AgentXin agent model calls. It keeps LangChain-style retry semantics while exposing only JSON-serializable configuration that can be edited in the AgentXin middleware UI.

Key Features

• Retries failed model calls with configurable retry count, exponential backoff, max delay, and optional jitter.
• Supports platform-safe retry matching by error name, HTTP status code, and message substring.
• Returns an AIMessage when retries are exhausted in continue mode, or rethrows the last error in error mode.
• Wraps retry attempts with WrapWorkflowNodeExecutionCommand so middleware-level execution tracking remains visible in AgentXin.
• Registers as a global middleware plugin so the strategy is available across the platform.
• Treats AIMessage.response_metadata.finish_reason === "network_error" as a retryable model failure, even when the provider returns a message instead of throwing.
• Treats empty AIMessage results with no tool_calls and no invalid_tool_calls as retryable model failures.

Installation

pnpm add @agentxin-ai/plugin-model-retry
# or
npm install @agentxin-ai/plugin-model-retry

Quick Start

1. Register the plugin:

   PLUGINS=@agentxin-ai/plugin-model-retry

2. Add a middleware entry using strategy ModelRetryMiddleware.
3. Configure retries:

   {
     "type": "ModelRetryMiddleware",
     "options": {
       "maxRetries": 2,
       "initialDelayMs": 1000,
       "backoffFactor": 2,
       "maxDelayMs": 60000,
       "jitter": true,
       "retryAllErrors": false,
       "retryableErrorNames": ["RateLimitError"],
       "retryableStatusCodes": [429, 503],
       "retryableMessageIncludes": ["timeout", "temporarily unavailable"],
       "onFailure": "continue"
     }
   }

Configuration

| Field | Type | Description | Default | | ----- | ---- | ----------- | ------- | | maxRetries | number | Number of retry attempts after the initial failure. 0 disables retries. | 2 | | initialDelayMs | number | Delay before the first retry attempt, in milliseconds. | 1000 | | backoffFactor | number | Exponential multiplier applied per retry attempt. 0 keeps a constant delay. | 2 | | maxDelayMs | number | Upper bound for the computed retry delay. | 60000 | | jitter | boolean | Adds a bounded random factor to each delay to reduce synchronized retries. | true | | retryAllErrors | boolean | Retry every thrown error when true. | true | | retryableErrorNames | string[] | Retry only matching error.name values when retryAllErrors=false. | [] | | retryableStatusCodes | number[] | Retry matching HTTP-style status codes from status, statusCode, or response.status. | [] | | retryableMessageIncludes | string[] | Retry when the error message contains any configured fragment. Matching is case-insensitive. | [] | | onFailure | "continue" | "error" | Return an AIMessage or rethrow after retries are exhausted. | "continue" |

LangChain Differences

• Function-based retryOn and onFailure are intentionally not supported because AgentXin middleware configuration must remain serializable.
• Retry matching uses declarative JSON fields instead of runtime classes or callback functions.
• Retry attempts are execution-tracked with AgentXin workflow commands, but no model client is recreated during retries.
• Provider responses that finish with network_error are normalized into an internal ModelNetworkError and routed through the same retry policy.
• Provider responses with empty content and no tool call payload are normalized into an internal ModelEmptyResponseError and routed through the same retry policy.

Development & Testing

NX_DAEMON=false pnpm -C /path/to/agentxin-plugins/agentxinai exec nx build @agentxin-ai/plugin-model-retry
NX_DAEMON=false pnpm -C /path/to/agentxin-plugins/agentxinai exec nx test @agentxin-ai/plugin-model-retry

TypeScript output is emitted to middlewares/model-retry/dist.