mcp-ai-agent-guidelines/dist/tools/shared/async-patterns.d.ts

A comprehensive Model Context Protocol server providing advanced tools, resources, and prompts for implementing AI agent best practices

/**
 * Async Patterns for A2A Orchestration
 *
 * Provides common async orchestration patterns:
 * - Map-Reduce for parallel processing with aggregation
 * - Pipeline with transformations between steps
 * - Conditional branching based on runtime state
 * - Scatter-Gather for fan-out/fan-in patterns
 */
import type { A2AContext } from "./a2a-context.js";
import type { ToolResult } from "./tool-registry.js";
/**
 * Map-Reduce pattern: Apply a tool to multiple inputs in parallel, then reduce
 *
 * @param toolName - Tool to apply to each input
 * @param inputs - Array of inputs
 * @param context - A2A context
 * @param reducer - Function to combine results
 * @returns Reduced result
 */
export declare function mapReduceTools<T, R>(toolName: string, inputs: T[], context: A2AContext, reducer: (results: ToolResult[]) => R): Promise<R>;
/**
 * Pipeline pattern: Chain tools with transformations between steps
 *
 * @param pipeline - Array of pipeline steps
 * @param context - A2A context
 * @param initialInput - Initial input for first tool
 * @returns Final result
 */
export declare function pipelineTools(pipeline: Array<{
    toolName: string;
    transform?: (previousOutput: unknown) => unknown;
}>, context: A2AContext, initialInput?: unknown): Promise<ToolResult>;
/**
 * Conditional branch pattern: Execute one of two tools based on a condition
 *
 * @param condition - Function to evaluate condition
 * @param trueBranch - Tool to execute if condition is true
 * @param falseBranch - Tool to execute if condition is false
 * @param args - Arguments for the selected tool
 * @param context - A2A context
 * @returns Result from the executed branch
 */
export declare function branchOnCondition(condition: (state: Map<string, unknown>) => boolean, trueBranch: string, falseBranch: string, args: unknown, context: A2AContext): Promise<ToolResult>;
/**
 * Scatter-Gather pattern: Fan out to multiple tools, then gather results
 *
 * @param tools - Array of tools to invoke
 * @param args - Arguments (can be per-tool or shared)
 * @param context - A2A context
 * @param gatherer - Function to process gathered results
 * @returns Gathered result
 */
export declare function scatterGatherTools<R>(tools: Array<{
    toolName: string;
    args: unknown;
}>, context: A2AContext, gatherer: (results: Map<string, ToolResult>) => R): Promise<R>;
/**
 * Fan-out pattern: Execute a tool multiple times with different arguments
 *
 * @param toolName - Tool to execute
 * @param argsArray - Array of argument sets
 * @param context - A2A context
 * @param maxConcurrency - Maximum concurrent executions (undefined = unlimited)
 * @returns Array of results
 */
export declare function fanOut(toolName: string, argsArray: unknown[], context: A2AContext, maxConcurrency?: number): Promise<ToolResult[]>;
/**
 * Waterfall pattern: Execute tools in sequence, each using the previous result
 *
 * Similar to pipeline but without explicit transforms (tools handle previous output)
 *
 * @param tools - Array of tool names
 * @param context - A2A context
 * @param initialInput - Initial input
 * @returns Final result
 */
export declare function waterfallTools(tools: string[], context: A2AContext, initialInput?: unknown): Promise<ToolResult>;
/**
 * Race pattern: Execute multiple tools in parallel, return first success
 *
 * @param tools - Array of tools to race
 * @param args - Arguments (can be per-tool or shared)
 * @param context - A2A context
 * @returns First successful result
 */
export declare function raceTools(tools: Array<{
    toolName: string;
    args: unknown;
}>, context: A2AContext): Promise<ToolResult>;
/**
 * Retry pattern: Retry a tool invocation with exponential backoff and optional jitter
 *
 * @param toolName - Tool to retry
 * @param args - Tool arguments
 * @param context - A2A context
 * @param maxRetries - Maximum retry attempts
 * @param initialDelayMs - Initial delay before first retry
 * @param backoffMultiplier - Multiplier for exponential backoff
 * @param jitterMs - Optional maximum jitter in milliseconds (default: 0)
 * @returns Tool result
 *
 * @remarks
 * Jitter is added to each retry delay to prevent thundering herd problems when
 * multiple tool chains fail simultaneously and retry at the same time.
 */
export declare function retryTool(toolName: string, args: unknown, context: A2AContext, maxRetries?: number, initialDelayMs?: number, backoffMultiplier?: number, jitterMs?: number): Promise<ToolResult>;
/**
 * Fallback pattern: Try primary tool, fall back to secondary if it fails
 *
 * @param primaryTool - Primary tool to try
 * @param fallbackTool - Fallback tool if primary fails
 * @param args - Tool arguments
 * @param context - A2A context
 * @returns Result from primary or fallback
 */
export declare function fallbackTool(primaryTool: string, fallbackTool: string, args: unknown, context: A2AContext): Promise<ToolResult>;
/**
 * Common reducer functions for map-reduce
 */
export declare const reducers: {
    /**
     * Collect all successful results into an array
     */
    collectSuccessful: (results: ToolResult[]) => unknown[];
    /**
     * Count successful executions
     */
    countSuccessful: (results: ToolResult[]) => number;
    /**
     * Check if all executions succeeded
     */
    allSucceeded: (results: ToolResult[]) => boolean;
    /**
     * Check if any execution succeeded
     */
    anySucceeded: (results: ToolResult[]) => boolean;
    /**
     * Merge all results into a single object
     */
    mergeResults: (results: ToolResult[]) => Record<string, unknown>;
};
//# sourceMappingURL=async-patterns.d.ts.map