@memberjunction/ai-agents 3.4.0 → 4.0.0

package/dist/AgentRunner.d.ts

@@ -1,39 +1,251 @@
+/**
+ * @fileoverview AgentRunner provides a thin wrapper for executing AI agents
+ * using the MemberJunction AI Agent framework.
+ *
+ * This module handles agent instantiation using the ClassFactory pattern to ensure
+ * the correct agent subclass is used based on the agent type's DriverClass property.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ * @since 2.49.0
+ */
 import { UserInfo } from '@memberjunction/core';
 import { ExecuteAgentResult, ExecuteAgentParams, MediaOutput } from '@memberjunction/ai-core-plus';
+/**
+ * AgentRunner provides a thin wrapper for executing AI agents.
+ *
+ * This class handles:
+ * - Loading agent type metadata to get the DriverClass
+ * - Instantiating the correct agent class using ClassFactory
+ * - Passing through to the agent's Execute method
+ *
+ * @class AgentRunner
+ * @example
+ * ```typescript
+ * const runner = new AgentRunner();
+ * const result = await runner.RunAgent({
+ *   agent: myAgent,
+ *   conversationMessages: messages,
+ *   contextUser: currentUser
+ * });
+ * ```
+ */
 export declare class AgentRunner {
+    /**
+     * Runs an AI agent with the specified parameters.
+     *
+     * This method acts as a thin pass-through that:
+     * 1. Loads the agent type to get the DriverClass
+     * 2. Uses ClassFactory to instantiate the correct agent class
+     * 3. Calls Execute on the agent instance and returns the result
+     *
+     * @param {ExecuteAgentParams} params - Parameters for agent execution (same as BaseAgent.Execute)
+     * @template C - The type of the agent's context as provided in the ExecuteAgentParams
+     * @template R - The type of the agent's result as returned in ExecuteAgentResult
+     * @returns {Promise<ExecuteAgentResult<T>>} The execution result (same as BaseAgent.Execute)
+     *
+     * @throws {Error} Throws if agent type loading fails or agent instantiation fails
+     */
     RunAgent<C = any, R = any>(params: ExecuteAgentParams<C>): Promise<ExecuteAgentResult<R>>;
+    /**
+     * Runs an AI agent within a conversation context, handling conversation and artifact management.
+     *
+     * This method provides a complete workflow for running agents in conversations:
+     * 1. Creates or uses existing conversation
+     * 2. Creates conversation detail record for the user message
+     * 3. Executes the agent
+     * 4. Creates artifacts from the agent's payload (if configured)
+     * 5. Links artifacts to the conversation detail
+     *
+     * @param params - Core agent execution parameters
+     * @param options - Conversation-specific options
+     * @returns Promise containing the agent execution result and conversation/artifact metadata
+     *
+     * @example
+     * ```typescript
+     * const runner = new AgentRunner();
+     * const result = await runner.RunAgentInConversation({
+     *   agent: myAgent,
+     *   conversationMessages: messages,
+     *   contextUser: currentUser
+     * }, {
+     *   conversationId: existingConvoId,  // Optional - creates new if not provided
+     *   userMessage: 'User query text',
+     *   createArtifacts: true
+     * });
+     * ```
+     */
     RunAgentInConversation<C = any, R = any>(params: ExecuteAgentParams<C>, options: {
+        /** Optional existing conversation ID. If not provided, a new conversation will be created */
         conversationId?: string;
+        /** Optional existing conversation detail ID. If provided, skips conversation/detail creation */
         conversationDetailId?: string;
+        /** The user's message text for this conversation turn (required if conversationDetailId not provided) */
         userMessage?: string;
+        /** Whether to create artifacts from the agent's payload (default: true) */
         createArtifacts?: boolean;
+        /** Optional source artifact ID for versioning (agent continuity/refinement) */
         sourceArtifactId?: string;
+        /** Optional conversation name (only used when creating new conversation) */
         conversationName?: string;
+        /** Optional test run ID to link conversation and details to (for test execution traceability) */
         testRunId?: string;
     }): Promise<{
+        /** The agent execution result */
         agentResult: ExecuteAgentResult<R>;
+        /** The conversation ID (created or existing) */
         conversationId: string;
+        /** The conversation detail ID for the user message */
         userMessageDetailId: string;
+        /** The conversation detail ID for the agent response (only present if server created it) */
         agentResponseDetailId?: string;
+        /** Artifact information if created */
         artifactInfo?: {
             artifactId: string;
             versionId: string;
             versionNumber: number;
         };
     }>;
+    /**
+     * Gets the maximum version number for an artifact.
+     * Used when creating new versions of explicitly specified artifacts.
+     *
+     * @param artifactId - The artifact ID to query
+     * @param contextUser - The user context for the query
+     * @returns The maximum version number, or 0 if no versions exist
+     *
+     * @example
+     * ```typescript
+     * const runner = new AgentRunner();
+     * const maxVersion = await runner.GetMaxVersionForArtifact(artifactId, currentUser);
+     * const newVersionNumber = maxVersion + 1;
+     * ```
+     */
     GetMaxVersionForArtifact(artifactId: string, contextUser: UserInfo): Promise<number>;
+    /**
+     * Finds the most recent artifact for a conversation detail to determine versioning.
+     * Queries the junction table to locate artifacts linked to a specific conversation message.
+     *
+     * @param conversationDetailId - The conversation detail ID to query
+     * @param contextUser - The user context for the query
+     * @returns Artifact info if exists, null if this is the first artifact for this message
+     *
+     * @example
+     * ```typescript
+     * const runner = new AgentRunner();
+     * const previousArtifact = await runner.FindPreviousArtifactForMessage(detailId, currentUser);
+     * if (previousArtifact) {
+     *     console.log(`Found artifact ${previousArtifact.artifactId} at version ${previousArtifact.versionNumber}`);
+     * }
+     * ```
+     */
     FindPreviousArtifactForMessage(conversationDetailId: string, contextUser: UserInfo): Promise<{
         artifactId: string;
         versionNumber: number;
     } | null>;
+    /**
+     * Processes agent completion to create artifacts from the agent's payload.
+     * Handles artifact creation, versioning, and linking to conversation details.
+     *
+     * This method implements intelligent artifact versioning:
+     * 1. If sourceArtifactId is provided (explicit continuity), creates new version of that artifact
+     * 2. Otherwise, checks for previous artifacts on this conversation detail
+     * 3. If previous artifact exists, creates new version of it
+     * 4. If no previous artifact, creates entirely new artifact
+     *
+     * Respects the agent's ArtifactCreationMode configuration:
+     * - "Never": Skips artifact creation entirely
+     * - "System Only": Creates artifact with Visibility='System Only'
+     * - Other modes: Creates artifact with Visibility='Always'
+     *
+     * @param agentResult - The result from agent execution containing the payload
+     * @param conversationDetailId - The conversation detail to link the artifact to
+     * @param sourceArtifactId - Optional explicit artifact to version from (agent continuity)
+     * @param contextUser - The user context for the operation
+     * @returns Artifact metadata if created, undefined if skipped or failed
+     *
+     * @example
+     * ```typescript
+     * const runner = new AgentRunner();
+     * const artifactInfo = await runner.ProcessAgentArtifacts(
+     *     agentResult,
+     *     conversationDetailId,
+     *     sourceArtifactId, // Optional
+     *     currentUser
+     * );
+     * if (artifactInfo) {
+     *     console.log(`Created artifact ${artifactInfo.artifactId} version ${artifactInfo.versionNumber}`);
+     * }
+     * ```
+     */
     ProcessAgentArtifacts<R>(agentResult: ExecuteAgentResult<R>, conversationDetailId: string, sourceArtifactId: string | undefined, contextUser: UserInfo): Promise<{
         artifactId: string;
         versionId: string;
         versionNumber: number;
     } | undefined>;
+    /**
+     * Generates a conversation name and description using the "Name Conversation" AI prompt.
+     * Same approach as UI - uses AI to create a meaningful title and description from the first user message.
+     * Falls back to null if prompt not found or execution fails (caller will use fallback).
+     *
+     * @param userMessage - The first user message to base the name on
+     * @param contextUser - User context for prompt execution
+     * @returns Generated conversation name and description, or null if generation failed
+     * @private
+     */
     private GenerateConversationName;
+    /**
+     * Saves media outputs to AIAgentRunMedia table for permanent storage.
+     * This creates records for each media output promoted during agent execution.
+     *
+     * Only media with `persist !== false` is saved. Media items with `persist: false`
+     * are typically intercepted binary content that was never used in the final output.
+     *
+     * @param agentRunId - The ID of the agent run
+     * @param mediaOutputs - Array of media outputs to save
+     * @param contextUser - User context for the operation
+     * @returns Array of saved AIAgentRunMedia IDs
+     * @since 3.1.0
+     *
+     * @example
+     * ```typescript
+     * const runner = new AgentRunner();
+     * const mediaIds = await runner.SaveAgentRunMedia(
+     *     agentResult.agentRun.ID,
+     *     agentResult.mediaOutputs,
+     *     currentUser
+     * );
+     * console.log(`Saved ${mediaIds.length} media outputs`);
+     * ```
+     */
     SaveAgentRunMedia(agentRunId: string, mediaOutputs: MediaOutput[] | undefined, contextUser: UserInfo): Promise<string[]>;
+    /**
+     * Creates ConversationDetailAttachment records for media outputs.
+     * This enables media to be displayed in the conversation UI.
+     *
+     * @param conversationDetailId - The conversation detail to attach media to
+     * @param mediaOutputs - Array of media outputs
+     * @param agentRunMediaIds - Corresponding AIAgentRunMedia IDs
+     * @param contextUser - User context for the operation
+     * @returns Array of created attachment IDs
+     * @since 3.1.0
+     *
+     * @example
+     * ```typescript
+     * const runner = new AgentRunner();
+     * const attachmentIds = await runner.CreateConversationMediaAttachments(
+     *     conversationDetailId,
+     *     mediaOutputs,
+     *     agentRunMediaIds,
+     *     currentUser
+     * );
+     * ```
+     */
     CreateConversationMediaAttachments(conversationDetailId: string, mediaOutputs: MediaOutput[], agentRunMediaIds: string[], contextUser: UserInfo): Promise<string[]>;
+    /**
+     * Gets file extension from MIME type
+     * @private
+     */
     private getMimeTypeExtension;
 }
 //# sourceMappingURL=AgentRunner.d.ts.map

package/dist/AgentRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentRunner.d.ts","sourceRoot":"","sources":["../src/AgentRunner.ts"],"names":[],"mappings":"AAYA,OAAO,EAAgF,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAG9H,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAuBnG,qBAAa,WAAW;IAgBP,QAAQ,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IA2EzF,sBAAsB,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,EAChD,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC7B,OAAO,EAAE;QAEL,cAAc,CAAC,EAAE,MAAM,CAAC;QAExB,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAE9B,WAAW,CAAC,EAAE,MAAM,CAAC;QAErB,eAAe,CAAC,EAAE,OAAO,CAAC;QAE1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAE1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAE1B,SAAS,CAAC,EAAE,MAAM,CAAC;KACtB,GACF,OAAO,CAAC;QAEP,WAAW,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;QAEnC,cAAc,EAAE,MAAM,CAAC;QAEvB,mBAAmB,EAAE,MAAM,CAAC;QAE5B,qBAAqB,CAAC,EAAE,MAAM,CAAC;QAE/B,YAAY,CAAC,EAAE;YACX,UAAU,EAAE,MAAM,CAAC;YACnB,SAAS,EAAE,MAAM,CAAC;YAClB,aAAa,EAAE,MAAM,CAAC;SACzB,CAAC;KACL,CAAC;IA4RW,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAuCpF,8BAA8B,CACvC,oBAAoB,EAAE,MAAM,EAC5B,WAAW,EAAE,QAAQ,GACtB,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAuEnD,qBAAqB,CAAC,CAAC,EAChC,WAAW,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAClC,oBAAoB,EAAE,MAAM,EAC5B,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,WAAW,EAAE,QAAQ,GACtB,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;YAgK1E,wBAAwB;IA4EzB,iBAAiB,CAC1B,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,WAAW,EAAE,GAAG,SAAS,EACvC,WAAW,EAAE,QAAQ,GACtB,OAAO,CAAC,MAAM,EAAE,CAAC;IA6HP,kCAAkC,CAC3C,oBAAoB,EAAE,MAAM,EAC5B,YAAY,EAAE,WAAW,EAAE,EAC3B,gBAAgB,EAAE,MAAM,EAAE,EAC1B,WAAW,EAAE,QAAQ,GACtB,OAAO,CAAC,MAAM,EAAE,CAAC;IA6FpB,OAAO,CAAC,oBAAoB;CAiB/B"}
+{"version":3,"file":"AgentRunner.d.ts","sourceRoot":"","sources":["../src/AgentRunner.ts"],"names":[],"mappings":"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"}