@memberjunction/ai-agents 3.4.0 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/README.md +232 -2584
  2. package/dist/AgentDataPreloader.d.ts +117 -1
  3. package/dist/AgentDataPreloader.d.ts.map +1 -1
  4. package/dist/AgentDataPreloader.js +156 -58
  5. package/dist/AgentDataPreloader.js.map +1 -1
  6. package/dist/AgentRunner.d.ts +212 -0
  7. package/dist/AgentRunner.d.ts.map +1 -1
  8. package/dist/AgentRunner.js +354 -103
  9. package/dist/AgentRunner.js.map +1 -1
  10. package/dist/PayloadChangeAnalyzer.d.ts +68 -0
  11. package/dist/PayloadChangeAnalyzer.d.ts.map +1 -1
  12. package/dist/PayloadChangeAnalyzer.js +68 -32
  13. package/dist/PayloadChangeAnalyzer.js.map +1 -1
  14. package/dist/PayloadFeedbackManager.d.ts +57 -1
  15. package/dist/PayloadFeedbackManager.d.ts.map +1 -1
  16. package/dist/PayloadFeedbackManager.js +66 -21
  17. package/dist/PayloadFeedbackManager.js.map +1 -1
  18. package/dist/PayloadManager.d.ts +286 -1
  19. package/dist/PayloadManager.d.ts.map +1 -1
  20. package/dist/PayloadManager.js +423 -50
  21. package/dist/PayloadManager.js.map +1 -1
  22. package/dist/__tests__/action-changes.test.d.ts +13 -0
  23. package/dist/__tests__/action-changes.test.d.ts.map +1 -1
  24. package/dist/__tests__/action-changes.test.js +57 -4
  25. package/dist/__tests__/action-changes.test.js.map +1 -1
  26. package/dist/__tests__/agent-memory-features.test.d.ts +52 -0
  27. package/dist/__tests__/agent-memory-features.test.d.ts.map +1 -1
  28. package/dist/__tests__/agent-memory-features.test.js +96 -13
  29. package/dist/__tests__/agent-memory-features.test.js.map +1 -1
  30. package/dist/__tests__/agent-type-prompt-params.test.d.ts +12 -0
  31. package/dist/__tests__/agent-type-prompt-params.test.d.ts.map +1 -1
  32. package/dist/__tests__/agent-type-prompt-params.test.js +112 -20
  33. package/dist/__tests__/agent-type-prompt-params.test.js.map +1 -1
  34. package/dist/__tests__/chat-handling-option.test.d.ts +26 -0
  35. package/dist/__tests__/chat-handling-option.test.d.ts.map +1 -1
  36. package/dist/__tests__/chat-handling-option.test.js +41 -2
  37. package/dist/__tests__/chat-handling-option.test.js.map +1 -1
  38. package/dist/agent-context-injector.d.ts +114 -0
  39. package/dist/agent-context-injector.d.ts.map +1 -1
  40. package/dist/agent-context-injector.js +138 -19
  41. package/dist/agent-context-injector.js.map +1 -1
  42. package/dist/agent-types/base-agent-type.d.ts +354 -0
  43. package/dist/agent-types/base-agent-type.d.ts.map +1 -1
  44. package/dist/agent-types/base-agent-type.js +288 -17
  45. package/dist/agent-types/base-agent-type.js.map +1 -1
  46. package/dist/agent-types/flow-agent-type.d.ts +328 -2
  47. package/dist/agent-types/flow-agent-type.d.ts.map +1 -1
  48. package/dist/agent-types/flow-agent-type.js +503 -63
  49. package/dist/agent-types/flow-agent-type.js.map +1 -1
  50. package/dist/agent-types/index.d.ts +14 -3
  51. package/dist/agent-types/index.d.ts.map +1 -1
  52. package/dist/agent-types/index.js +14 -23
  53. package/dist/agent-types/index.js.map +1 -1
  54. package/dist/agent-types/loop-agent-prompt-params.d.ts +190 -0
  55. package/dist/agent-types/loop-agent-prompt-params.d.ts.map +1 -1
  56. package/dist/agent-types/loop-agent-prompt-params.js +23 -6
  57. package/dist/agent-types/loop-agent-prompt-params.js.map +1 -1
  58. package/dist/agent-types/loop-agent-response-type.d.ts +62 -0
  59. package/dist/agent-types/loop-agent-response-type.d.ts.map +1 -1
  60. package/dist/agent-types/loop-agent-response-type.js +3 -2
  61. package/dist/agent-types/loop-agent-response-type.js.map +1 -1
  62. package/dist/agent-types/loop-agent-type.d.ts +139 -2
  63. package/dist/agent-types/loop-agent-type.d.ts.map +1 -1
  64. package/dist/agent-types/loop-agent-type.js +207 -35
  65. package/dist/agent-types/loop-agent-type.js.map +1 -1
  66. package/dist/base-agent.d.ts +1344 -1
  67. package/dist/base-agent.d.ts.map +1 -1
  68. package/dist/base-agent.js +2282 -211
  69. package/dist/base-agent.js.map +1 -1
  70. package/dist/index.d.ts +24 -14
  71. package/dist/index.d.ts.map +1 -1
  72. package/dist/index.js +25 -35
  73. package/dist/index.js.map +1 -1
  74. package/dist/memory-cleanup-agent.d.ts +53 -1
  75. package/dist/memory-cleanup-agent.d.ts.map +1 -1
  76. package/dist/memory-cleanup-agent.js +89 -21
  77. package/dist/memory-cleanup-agent.js.map +1 -1
  78. package/dist/memory-manager-agent.d.ts +61 -1
  79. package/dist/memory-manager-agent.d.ts.map +1 -1
  80. package/dist/memory-manager-agent.js +260 -116
  81. package/dist/memory-manager-agent.js.map +1 -1
  82. package/dist/types/payload-operations.d.ts +51 -0
  83. package/dist/types/payload-operations.d.ts.map +1 -1
  84. package/dist/types/payload-operations.js +54 -15
  85. package/dist/types/payload-operations.js.map +1 -1
  86. package/dist/utils/ConversationMessageResolver.d.ts +79 -1
  87. package/dist/utils/ConversationMessageResolver.d.ts.map +1 -1
  88. package/dist/utils/ConversationMessageResolver.js +99 -9
  89. package/dist/utils/ConversationMessageResolver.js.map +1 -1
  90. package/package.json +20 -19
@@ -1,34 +1,377 @@
1
+ /**
2
+ * @fileoverview Base agent type abstraction for the MemberJunction AI Agent framework.
3
+ *
4
+ * This module defines the abstract BaseAgentType class that serves as the foundation
5
+ * for different agent execution patterns. Agent types encapsulate reusable behavior
6
+ * patterns (like loops, decision trees, or linear flows) that can be applied to
7
+ * multiple agents through configuration rather than code duplication.
8
+ *
9
+ * @module @memberjunction/ai-agents
10
+ * @author MemberJunction.com
11
+ * @since 2.49.0
12
+ */
1
13
  import { AIPromptParams, AIPromptRunResult, BaseAgentNextStep, AgentPayloadChangeRequest, AgentAction, AgentSubAgentRequest, ExecuteAgentParams, AgentConfiguration } from '@memberjunction/ai-core-plus';
2
14
  import { AIAgentTypeEntity } from '@memberjunction/core-entities';
3
15
  import { AIPromptEntityExtended } from "@memberjunction/ai-core-plus";
4
16
  import { JSONValidator } from '@memberjunction/global';
5
17
  import { ActionResult } from '@memberjunction/actions-base';
18
+ /**
19
+ * Abstract base class for agent type implementations.
20
+ *
21
+ * Agent types define reusable execution patterns that control how agents behave.
22
+ * Each agent type is associated with a system prompt that guides the LLM's output
23
+ * format and decision-making process. Common agent type patterns include:
24
+ *
25
+ * - **Loop**: Continues executing until a goal is achieved
26
+ * - **SinglePass**: Executes once and returns a result
27
+ * - **DecisionTree**: Makes branching decisions based on conditions
28
+ * - **Pipeline**: Executes a series of steps in sequence
29
+ *
30
+ * The agent type's system prompt should be designed to produce output that can
31
+ * be parsed by the DetermineNextStep method to decide what happens next in the
32
+ * agent's execution flow.
33
+ *
34
+ * @abstract
35
+ * @class BaseAgentType
36
+ *
37
+ * @example
38
+ * ```typescript
39
+ * export class LoopAgentType extends BaseAgentType {
40
+ * public async DetermineNextStep(): Promise<BaseAgentNextStep> {
41
+ * // Parse LLM output to determine if goal is achieved
42
+ * const goalAchieved = // ... parsing logic
43
+ *
44
+ * return {
45
+ * step: goalAchieved ? 'success' : 'action',
46
+ * payload: result
47
+ * };
48
+ * }
49
+ * }
50
+ * ```
51
+ */
6
52
  export declare abstract class BaseAgentType {
53
+ /**
54
+ * JSON validator instance for cleaning and validating responses
55
+ * @protected
56
+ */
7
57
  protected _jsonValidator: JSONValidator;
58
+ /**
59
+ * Common placeholder for current payload injection
60
+ * @static
61
+ */
8
62
  static readonly CURRENT_PAYLOAD_PLACEHOLDER = "_CURRENT_PAYLOAD";
63
+ /**
64
+ * This method allows each agent type to initialize its agent-run-specific state package as required. Not all agent
65
+ * types require this and are able to live off just the current payload or other properties passed to them to
66
+ * DetermineNextStep(), but some require more complex internal state tracking.
67
+ * @param params - the agent execution params
68
+ * @returns the fully initialized initial agent-type state
69
+ */
9
70
  abstract InitializeAgentTypeState<ATS = any, P = any>(params: ExecuteAgentParams<any, P>): Promise<ATS>;
71
+ /**
72
+ * Analyzes the output from prompt execution to determine the next step.
73
+ *
74
+ * This method is called after the hierarchical prompts have been executed
75
+ * and should parse the LLM's response to determine what the agent should
76
+ * do next. The implementation depends on the specific agent type's logic
77
+ * and the format of output expected from its system prompt.
78
+ *
79
+ * @abstract
80
+ * @param {AIPromptRunResult | null} promptResult - Result from prompt execution (null for non-prompt steps)
81
+ * @param {ExecuteAgentParams} params - The full execution parameters including agent and context
82
+ * @returns {Promise<BaseAgentNextStep>} The determined next step and optional return value
83
+ *
84
+ * @example
85
+ * ```typescript
86
+ * public async DetermineNextStep(): Promise<BaseAgentNextStep> {
87
+ * // Implementation might parse JSON output from LLM
88
+ * const response = JSON.parse(this.lastExecutionResult);
89
+ *
90
+ * if (response.taskComplete) {
91
+ * return { step: 'success', payload: response.payload };
92
+ * } else if (response.needsSubAgent) {
93
+ * return { step: 'subagent', payload: response.subAgentConfig };
94
+ * } else {
95
+ * return { step: 'action', payload: response.nextAction };
96
+ * }
97
+ * }
98
+ * ```
99
+ */
10
100
  abstract DetermineNextStep<P = any, ATS = any>(promptResult: AIPromptRunResult | null, params: ExecuteAgentParams<any, P>, payload: P, agentTypeState: ATS): Promise<BaseAgentNextStep<P>>;
101
+ /**
102
+ * Determines the initial step when no previous decision exists.
103
+ *
104
+ * This method allows agent types to customize how they begin execution.
105
+ * For example:
106
+ * - Loop agents might execute a prompt to determine initial actions
107
+ * - Flow agents might look up their starting step from configuration
108
+ * - Pipeline agents might execute the first step in their sequence
109
+ *
110
+ * @abstract
111
+ * @param {ExecuteAgentParams} params - The full execution parameters including agent, payload, and context
112
+ * @returns {Promise<BaseAgentNextStep<P> | null>} The initial step, or null to use default behavior (prompt execution)
113
+ *
114
+ * @since 2.76.0
115
+ */
11
116
  abstract DetermineInitialStep<P = any, ATS = any>(params: ExecuteAgentParams<P>, payload: P, agentTypeState: ATS): Promise<BaseAgentNextStep<P> | null>;
117
+ /**
118
+ * Pre-processes a retry step to allow agent types to customize retry behavior.
119
+ *
120
+ * This method is called when the previous step returned 'Retry' as the next step.
121
+ * Agent types can override this to provide custom behavior instead of the default
122
+ * prompt execution. This is particularly useful for:
123
+ * - Flow agents that need to evaluate paths after action execution
124
+ * - State machine agents that need to transition based on results
125
+ * - Pipeline agents that need to move to the next stage
126
+ *
127
+ * @abstract
128
+ * @param {ExecuteAgentParams} params - The full execution parameters
129
+ * @param {BaseAgentNextStep} retryStep - The retry step that was returned
130
+ * @returns {Promise<BaseAgentNextStep | null>} Custom next step, or null to use default retry behavior (prompt execution)
131
+ *
132
+ * @since 2.76.0
133
+ */
12
134
  abstract PreProcessNextStep<P = any, ATS = any>(params: ExecuteAgentParams<P>, step: BaseAgentNextStep<P>, payload: P, agentTypeState: ATS): Promise<BaseAgentNextStep<P> | null>;
135
+ /**
136
+ * The agent type is responsible for injecting a payload into the prompt. This can be done by updating the
137
+ * system prompt by replacing a special non-Nunjucks placeholder, or by adding extra messages to the prompt.
138
+ * @param payload - The payload to inject
139
+ * @param prompt - The prompt parameters to update
140
+ * @param agentInfo - Agent identification info including agent ID and run ID
141
+ */
13
142
  abstract InjectPayload<P = any, ATS = any>(payload: P, agentTypeState: ATS, prompt: AIPromptParams, agentInfo: {
14
143
  agentId: string;
15
144
  agentRunId?: string;
16
145
  }): Promise<void>;
146
+ /**
147
+ * Allows agent types to provide a custom prompt for a specific step.
148
+ * This is used by agent types that need to override the default prompt
149
+ * selection logic (e.g., Flow agents that use different prompts for different steps).
150
+ *
151
+ * The base implementation should return the default prompt from configuration.
152
+ * Agent types can override this to provide custom prompt selection logic.
153
+ *
154
+ * @param {ExecuteAgentParams} params - The full execution parameters for additional context
155
+ * @param {AgentConfiguration} config - The loaded agent configuration with default prompts
156
+ * @param {BaseAgentNextStep | null} previousDecision - The previous step decision that may contain context
157
+ * @returns {Promise<AIPromptEntityExtended | null>} A prompt entity to use (either custom or config.childPrompt)
158
+ *
159
+ * @abstract
160
+ * @since 2.76.0
161
+ */
17
162
  abstract GetPromptForStep<P = any, ATS = any>(params: ExecuteAgentParams, config: AgentConfiguration, payload: P, agentTypeState: ATS, previousDecision?: BaseAgentNextStep<P> | null): Promise<AIPromptEntityExtended | null>;
163
+ /**
164
+ * Helper method that retrieves an instance of the agent type based on the provided agent type entity.
165
+ *
166
+ * This method uses the ClassFactory to create an instance of the agent type class
167
+ * specified in the DriverClass field of the agent type entity. If the DriverClass is not
168
+ * specified, it throws an error.
169
+ *
170
+ * @async
171
+ * @static
172
+ * @method GetAgentTypeInstance
173
+ * @param {AIAgentTypeEntity} agentType - The agent type entity to instantiate
174
+ *
175
+ * @returns {Promise<BaseAgentType>} An instance of the agent type class
176
+ *
177
+ * @throws {Error} If the agent type does not have a DriverClass specified or if instantiation fails
178
+ * @param agentType
179
+ * @returns
180
+ */
18
181
  static GetAgentTypeInstance(agentType: AIAgentTypeEntity): Promise<BaseAgentType>;
182
+ /**
183
+ * Instantiates the appropriate agent type class based on the agent type entity.
184
+ *
185
+ * This method uses the MemberJunction class factory to dynamically instantiate
186
+ * agent type classes. It uses the DriverClass field. If DriverClass is not specified
187
+ * it throws an error.
188
+ *
189
+ * @param {AIAgentTypeEntity} agentType - The agent type entity to instantiate
190
+ *
191
+ * @returns {Promise<BaseAgentType | null>} Instance of the agent type class
192
+ *
193
+ * @example
194
+ * // For an agent type with DriverClass "LoopAgentType"
195
+ * const agentTypeInstance = await this.getAgentTypeInstance(loopAgentType);
196
+ *
197
+ * @protected
198
+ */
19
199
  protected static getAgentTypeInstance(agentType: AIAgentTypeEntity): Promise<BaseAgentType | null>;
200
+ /**
201
+ * Instantiates an agent type class using a specific driver class name.
202
+ *
203
+ * This method is used when an individual agent has its own DriverClass override,
204
+ * allowing for specialized implementations per agent instance.
205
+ *
206
+ * @param {string} driverClass - The driver class name to instantiate
207
+ *
208
+ * @returns {Promise<BaseAgentType | null>} Instance of the agent type class
209
+ *
210
+ * @protected
211
+ */
20
212
  protected static getAgentInstanceWithDriverClass(driverClass: string): Promise<BaseAgentType | null>;
213
+ /**
214
+ * Parses JSON response from prompt execution with automatic validation syntax cleaning
215
+ *
216
+ * @template T The expected response type
217
+ * @param {AIPromptRunResult} promptResult - The prompt execution result
218
+ *
219
+ * @returns {T | null} Parsed response or null if parsing fails
220
+ *
221
+ * @protected
222
+ */
21
223
  protected parseJSONResponse<T>(promptResult: AIPromptRunResult): T | null;
224
+ /**
225
+ * Creates a standardized next step object with common defaults
226
+ *
227
+ * @template P The payload type
228
+ * @param {BaseAgentNextStep['step']} step - The step type
229
+ * @param {Partial<BaseAgentNextStep<P>>} options - Additional options to merge
230
+ *
231
+ * @returns {BaseAgentNextStep<P>} The next step object
232
+ *
233
+ * @protected
234
+ */
22
235
  protected createNextStep<P>(step: BaseAgentNextStep['step'], options?: Partial<BaseAgentNextStep<P>>): BaseAgentNextStep<P>;
236
+ /**
237
+ * Creates a retry step with a standardized error message
238
+ *
239
+ * @template P The payload type
240
+ * @param {string} errorMessage - The error message
241
+ * @param {Partial<BaseAgentNextStep<P>>} options - Additional options
242
+ *
243
+ * @returns {BaseAgentNextStep<P>} Retry step
244
+ *
245
+ * @protected
246
+ */
23
247
  protected createRetryStep<P>(errorMessage: string, options?: Partial<BaseAgentNextStep<P>>): BaseAgentNextStep<P>;
248
+ /**
249
+ * Creates a success step with optional payload changes
250
+ *
251
+ * @template P The payload type
252
+ * @param {Partial<BaseAgentNextStep<P>>} options - Success options
253
+ *
254
+ * @returns {BaseAgentNextStep<P>} Success step
255
+ *
256
+ * @protected
257
+ */
24
258
  protected createSuccessStep<P>(options?: Partial<BaseAgentNextStep<P>>): BaseAgentNextStep<P>;
259
+ /**
260
+ * Pre-processes an action step before execution.
261
+ *
262
+ * This method is called by BaseAgent before action(s) are executed.
263
+ * Agent types can override this method to perform custom pre-processing,
264
+ * such as mapping payload values to action input parameters or modifying action configurations.
265
+ *
266
+ * @param {AgentAction[]} actions - The actions that will be executed (can be modified)
267
+ * @param {P} currentPayload - The current payload
268
+ * @param {BaseAgentNextStep<P>} currentStep - The current step being executed
269
+ *
270
+ * @returns {Promise<void>} Actions are modified in place
271
+ *
272
+ * @since 2.76.0
273
+ */
25
274
  PreProcessActionStep<P = any, ATS = any>(actions: AgentAction[], currentPayload: P, agentTypeState: ATS, currentStep: BaseAgentNextStep<P>, params?: ExecuteAgentParams<P>): Promise<void>;
275
+ /**
276
+ * Post-processes the result of action execution.
277
+ *
278
+ * This method is called by BaseAgent after action(s) have been executed.
279
+ * Agent types can override this method to perform custom processing of action results,
280
+ * such as mapping output parameters to the payload or storing results in agent-specific context.
281
+ *
282
+ * @param {ActionResult[]} actionResults - The results from action execution
283
+ * @param {AgentAction[]} actions - The actions that were executed
284
+ * @param {P} currentPayload - The current payload
285
+ * @param {BaseAgentNextStep<P>} currentStep - The current step being executed
286
+ *
287
+ * @returns {Promise<AgentPayloadChangeRequest<P> | null>} Optional payload change request
288
+ *
289
+ * @since 2.76.0
290
+ */
26
291
  PostProcessActionStep<P = any, ATS = any>(actionResults: ActionResult[], actions: AgentAction[], currentPayload: P, agentTypeState: ATS, currentStep: BaseAgentNextStep<P>): Promise<AgentPayloadChangeRequest<P> | null>;
292
+ /**
293
+ * Post-processes the result of sub-agent execution.
294
+ *
295
+ * This method is called by BaseAgent after a sub-agent has been executed.
296
+ * Agent types can override this method to perform custom processing of sub-agent results,
297
+ * such as extracting specific data from the sub-agent's payload or updating context.
298
+ *
299
+ * @param {any} subAgentResult - The result from sub-agent execution
300
+ * @param {AgentSubAgentRequest} subAgentRequest - The sub-agent request that was executed
301
+ * @param {P} currentPayload - The current payload
302
+ * @param {BaseAgentNextStep<P>} currentStep - The current step being executed
303
+ *
304
+ * @returns {Promise<AgentPayloadChangeRequest<P> | null>} Optional payload change request
305
+ *
306
+ * @since 2.76.0
307
+ */
27
308
  PostProcessSubAgentStep<P = any, ATS = any>(subAgentResult: any, subAgentRequest: AgentSubAgentRequest, currentPayload: P, agentTypeState: ATS, currentStep: BaseAgentNextStep<P>): Promise<AgentPayloadChangeRequest<P> | null>;
309
+ /**
310
+ * Indicates whether this agent type requires agent-level prompts (AI Agent Prompts relationship).
311
+ *
312
+ * Some agent types (like Flow) use step-level prompts exclusively and don't need agent-level prompts.
313
+ * Other agent types (like Loop) require agent-level prompts for their main reasoning loop.
314
+ *
315
+ * Default: true (most agent types require agent-level prompts)
316
+ *
317
+ * @returns {boolean} True if agent-level prompts are required, false if optional
318
+ * @since 2.113.0
319
+ */
28
320
  get RequiresAgentLevelPrompts(): boolean;
321
+ /**
322
+ * Provides agent-type-specific guidance for configuration errors related to missing prompts.
323
+ * This allows each agent type to give contextual help based on its architecture.
324
+ *
325
+ * Default implementation provides generic guidance. Agent types should override to provide
326
+ * specific instructions relevant to their configuration requirements.
327
+ *
328
+ * @returns {string} Configuration guidance specific to this agent type
329
+ * @since 2.113.0
330
+ */
29
331
  GetPromptConfigurationGuidance(): string;
332
+ /**
333
+ * Determines how to handle Success or Failed steps when no explicit termination is requested.
334
+ *
335
+ * This allows agent types to control their own fallback behavior:
336
+ * - Loop agents use default behavior (return null) to process results with their main prompt
337
+ * - Flow agents should terminate instead of falling back to prompts (return terminate step)
338
+ * - Pipeline agents might want to move to the next stage
339
+ *
340
+ * Default implementation returns null, which causes base-agent to fall back to prompt execution
341
+ * if prompts are configured. Agent types can override this to provide custom behavior.
342
+ *
343
+ * @param {BaseAgentNextStep<P>} step - The Success or Failed step that needs fallback handling
344
+ * @param {AgentConfiguration} config - The loaded agent configuration
345
+ * @param {ExecuteAgentParams} params - The execution parameters
346
+ * @param {P} payload - The current payload
347
+ * @param {ATS} agentTypeState - Agent type's state
348
+ * @returns {Promise<BaseAgentNextStep<P> | null>} Custom step to execute, or null for default behavior
349
+ *
350
+ * @since 2.113.0
351
+ */
30
352
  HandleStepFallback<P = any, ATS = any>(step: BaseAgentNextStep<P>, config: AgentConfiguration, params: ExecuteAgentParams<P>, payload: P, agentTypeState: ATS): Promise<BaseAgentNextStep<P> | null>;
353
+ /**
354
+ * Determines if loop results should be injected as a temporary user message
355
+ * before the next prompt execution (for LLM reasoning).
356
+ *
357
+ * Default: true (most agent types benefit from seeing loop results)
358
+ * Flow agents override to false (deterministic path navigation, no LLM)
359
+ *
360
+ * @returns true to inject results as message, false to skip
361
+ * @since 2.112.0
362
+ */
31
363
  get InjectLoopResultsAsMessage(): boolean;
364
+ /**
365
+ * Called before each loop iteration to prepare parameters and payload.
366
+ *
367
+ * Loop agents use this to resolve template variables ("item.email").
368
+ * Flow agents typically don't need this (params already resolved).
369
+ *
370
+ * @param context - Current iteration context
371
+ * @param agentTypeState - Agent type's state
372
+ * @returns Modified context or null for default behavior
373
+ * @since 2.112.0
374
+ */
32
375
  BeforeLoopIteration?<P>(context: {
33
376
  item: any;
34
377
  index: number;
@@ -50,6 +393,17 @@ export declare abstract class BaseAgentType {
50
393
  };
51
394
  payload?: P;
52
395
  } | null;
396
+ /**
397
+ * Called after each loop iteration completes to process results.
398
+ *
399
+ * Flow agents use this to apply ActionOutputMapping and update payload.
400
+ * Loop agents typically don't need this (just collect results).
401
+ *
402
+ * @param iterationResult - Results from this iteration
403
+ * @param agentTypeState - Agent type's state
404
+ * @returns Modified payload or null for default behavior (just collect result)
405
+ * @since 2.112.0
406
+ */
53
407
  AfterLoopIteration?<P>(iterationResult: {
54
408
  actionResults?: ActionResult[];
55
409
  subAgentResult?: any;
@@ -1 +1 @@
1
- {"version":3,"file":"base-agent-type.d.ts","sourceRoot":"","sources":["../../src/agent-types/base-agent-type.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"base-agent-type.d.ts","sourceRoot":"","sources":["../../src/agent-types/base-agent-type.ts"],"names":[],"mappings":"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"}