Member Junction
    Preparing search index...

    Class AIPromptParams

    Parameters for executing an AI prompt

    Index

    Constructors

    constructor

    Properties

    additionalParameters? agentRunId? apiKeys? attemptJSONRepair? cancellationToken? childPrompts? cleanValidationSyntax? configurationId? contextUser? conversationMessages? credentialId? data? effortLevel? forceFullModelEvaluation? maxErrorLength? modelSelectionPrompt? nativeFileInputs? onProgress? onPromptRunCreated? onStreaming? override? parentPromptRunId? prompt provider? rerunFromPromptRunID? skipValidation? systemPromptOverride? templateData? templateMessageRole? timeoutMS? verbose?

    Constructors

    Properties

    additionalParameters?: Record<string, any>

    Additional model-specific parameters that will be passed through to the underlying model. For chat/LLM models, this can include parameters like temperature, topP, topK, etc. The AIPromptRunner will pass these through when building model-specific parameters.

    agentRunId?: string

    Optional agent run ID to link this prompt execution to a parent agent run When provided, the AIPromptRun record will include this as AgentRunID for comprehensive execution tracking

    apiKeys?: AIAPIKey[]

    Optional API keys to use for this prompt execution. When provided, these keys will override the global API keys for the specified driver classes. This allows for runtime API key configuration without modifying environment variables or global settings.

    const params = new AIPromptParams();
    params.prompt = myPrompt;
    params.apiKeys = [
      { driverClass: 'OpenAILLM', apiKey: 'sk-...' },
      { driverClass: 'AnthropicLLM', apiKey: 'sk-ant-...' }
    ];
    attemptJSONRepair?: boolean

    NOTE: Only applies when prompt.OutputType is 'object'

    If this parameter is set to true, the runner will attempt to repair JSON parsing errors with a two step process, after a normal attempt to parse the JSON as-is where an error occurs:

    1. We will use the JSON5 library to attempt to parse the JSON as-is. This is a fast and deterministic method to parse JSON that handles some common invalid strict JSON issues such as
      • Trailing commas
      • Unquoted keys
      • Single quotes around strings
      • Unescaped control characters
      • Comments
    2. If Step 1 fails, we will use a small LLM using a prompt called 'Repair JSON' within the MJ: System category This prompt will attempt to fix the JSON with a small LLM that knows how to emit proper JSON
    cancellationToken?: AbortSignal

    Optional cancellation token to abort the prompt execution When this signal is aborted, the execution will be cancelled and any running operations will be terminated as gracefully as possible

    childPrompts?: ChildPromptParam[]

    Optional array of child prompts to execute before this prompt.

    When provided, the AIPromptRunner will:

    1. Execute all child prompts in a depth-first manner
    2. At each level, execute sibling prompts in parallel for performance
    3. Collect all child prompt results
    4. Replace the corresponding placeholders in the parent template with child results
    5. Execute the parent prompt with all child results embedded

    This enables hierarchical prompt architectures where:

    • Child prompts can contain their own nested child prompts (unlimited depth)
    • Each child result is embedded at a specific placeholder in the parent template
    • Parallel execution optimizes performance at each level
    • Complex multi-step reasoning can be decomposed into manageable units

    Each child prompt can specify its own execution parameters including models, validation, etc.

    const params = new AIPromptParams();
    params.prompt = parentPrompt;
    params.childPrompts = [
      new ChildPromptParam(childPrompt1, 'analysis'),
      new ChildPromptParam(childPrompt2, 'summary')
    ];
    // Parent template can use {{ analysis }} and {{ summary }} placeholders
    cleanValidationSyntax?: boolean

    Whether to clean validation syntax from the AI result. When true, the AIPromptRunner will automatically remove validation syntax (like ?, *, :type, :[N+], :!empty) from JSON keys in the AI's response.

    Note: For JSON outputs with an OutputExample defined, validation syntax is ALWAYS cleaned automatically before validation, regardless of this setting. This parameter is only needed for edge cases where you want cleaning without an OutputExample.

    Default: false

    // If AI returns: { "name?": "John", "items:[2+]": ["a", "b"] }
    // With cleanValidationSyntax: true OR with OutputExample defined
    // Result becomes: { "name": "John", "items": ["a", "b"] }
    configurationId?: string

    Optional configuration ID for environment-specific behavior

    contextUser?: UserInfo

    User context for authentication and permissions

    conversationMessages?: ChatMessage[]

    Optional conversation messages for multi-turn conversations When provided, these messages will be combined with the rendered template for direct conversation-style prompting

    credentialId?: string

    Optional credential ID for per-request authentication override.

    Takes highest priority in the credential resolution hierarchy:

    1. This parameter (per-request override) - highest priority
    2. AIPromptModel.CredentialID (prompt-model specific)
    3. AIModelVendor.CredentialID (model-vendor specific)
    4. AIVendor.CredentialID (vendor default)
    5. Legacy: apiKeys[] parameter
    6. Legacy: AI_VENDOR_API_KEY__ environment variables

    Important: When any credential ID is set (priorities 1-4), the system uses the Credentials system exclusively and ignores legacy authentication methods (priorities 5-6). This ensures consistent, audited credential usage.

    Use this for:

    • Multi-tenant scenarios where different tenants have different API keys
    • Testing with specific credentials without modifying database configuration
    • Runtime credential rotation or override
    // Override credential at runtime for a specific tenant
    const params = new AIPromptParams();
    params.prompt = myPrompt;
    params.credentialId = tenantCredentialId;  // Highest priority
    params.contextUser = currentUser;

    const result = await AIPromptRunner.RunPrompt(params);

    AI Authentication Guide

    data?: Record<string, unknown>

    Data context for template rendering and prompt execution

    effortLevel?: number

    Optional effort level override for this prompt execution (1-100).

    Higher values request more thorough reasoning and analysis from AI models. Each provider maps the 1-100 scale to their specific effort parameters:

    • OpenAI: Maps to reasoning_effort (1-33=low, 34-66=medium, 67-100=high)
    • Anthropic: Maps to thinking mode with token budgets
    • Groq: Maps to reasoning_effort parameter (experimental)
    • Gemini: Controls reasoning mode intensity

    Precedence hierarchy (highest to lowest priority):

    1. This effortLevel parameter (runtime override)
    2. Agent's DefaultPromptEffortLevel (if executed via agent)
    3. Prompt's EffortLevel property (prompt default)
    4. No effort level (provider default behavior)
    const params = new AIPromptParams();
    params.prompt = myPrompt;
    params.effortLevel = 85; // High effort for thorough analysis

    const result = await AIPromptRunner.RunPrompt(params);
    forceFullModelEvaluation?: boolean

    Forces the model-selection step to evaluate credential availability for EVERY candidate model-vendor combination, even after a usable candidate has already been found.

    By default (false) the runner short-circuits: it stops probing candidates as soon as the highest-priority candidate with valid credentials is identified, and records the remaining candidates as "not-evaluated" in the ModelSelection telemetry. This avoids unnecessary credential/env-var lookups on every prompt run for fleets with many configured models.

    Set this to true when you need a complete availability report for ALL candidates (e.g. an admin "which of my models are actually configured?" diagnostic), at the cost of probing credentials for every candidate.

    Default: false

    maxErrorLength?: number

    Optional maximum length for error messages returned in results.

    When set, error messages longer than this value will be truncated with "... [truncated]" appended. When undefined (default), error messages are returned in full without truncation.

    This is useful for handling extremely long error messages (like provider-specific JSON dumps) while still allowing full error details when needed for debugging.

    Default: undefined (no truncation)

    const params = new AIPromptParams();
    params.prompt = myPrompt;
    params.maxErrorLength = 500; // Truncate errors longer than 500 characters

    const result = await AIPromptRunner.RunPrompt(params);
    // Long errors will be truncated: "Error message text... [truncated]"
    modelSelectionPrompt?: MJAIPromptEntityExtended

    Optional prompt to use for model selection instead of the main prompt. When executing hierarchical prompts, this allows using a child prompt's model selection configuration instead of the parent prompt's configuration. If not specified, the main prompt's model selection will be used.

    nativeFileInputs?: NativeFileInput[]

    Optional file artifacts that may be attached as native content blocks when the resolved LLM driver supports the file's MIME type natively.

    The AIPromptRunner checks each entry against the driver's FileCapabilities after model selection. Files that pass the resolver are injected as content blocks in the last user message; others are left for artifact tool-based exploration.

    onProgress?: ExecutionProgressCallback

    Optional callback for receiving execution progress updates Provides real-time information about the execution progress

    onPromptRunCreated?: (promptRunId: string) => void | Promise<void>

    Optional callback fired immediately after the PromptRun record is created and saved. Provides the PromptRun ID for immediate tracking/monitoring purposes.

    This callback is useful for:

    • Linking the PromptRun to parent records (e.g., AIAgentRunStep.TargetLogID)
    • Real-time monitoring and tracking
    • Early logging and debugging

    The callback is invoked after the PromptRun is successfully saved but before the actual AI model execution begins. If the callback throws an error, it will be logged but won't fail the prompt execution.

    Type Declaration

      • (promptRunId: string): void | Promise<void>

      • Parameters

        • promptRunId: string

          The ID of the newly created AIPromptRun record

        Returns void | Promise<void>

    const params = new AIPromptParams();
    params.onPromptRunCreated = async (promptRunId) => {
      console.log(`Prompt run started: ${promptRunId}`);
      // Update parent records, send monitoring events, etc.
    };
    onStreaming?: ExecutionStreamingCallback

    Optional callback for receiving streaming content updates Called when AI models support streaming responses

    override?: { modelId?: string; vendorId?: string }

    Optional runtime override for prompt execution. When specified, these values take precedence over any model selection configuration in the prompt or modelSelectionPrompt. Currently supports model and vendor overrides, but can be extended for future needs.

    Model selection precedence (highest to lowest):

    1. override (this parameter) - Runtime override, highest priority
    2. modelSelectionPrompt - If specified, uses this prompt's model configuration
    3. Main prompt's model configuration - Based on:
      • AIPromptModels associations (if SelectionStrategy is 'Specific')
      • AIModelTypeID filtering (if specified)
      • SelectionStrategy ('Default', 'Specific', or 'ByPower')
      • PowerPreference and MinPowerRank settings

    For agents, the modelSelectionPrompt is determined by the agent's ModelSelectionMode:

    • "Agent": Uses the agent's specific prompt for model selection
    • "Agent Type": Uses the agent type's system prompt for model selection
    // Override model at runtime
    const params = new AIPromptParams();
    params.prompt = myPrompt;
    params.override = {
      modelId: 'specific-model-id',
      vendorId: 'specific-vendor-id'
    };
    parentPromptRunId?: string

    Internal: Parent prompt run ID for hierarchical execution tracking. This is automatically set by the system when executing child prompts.

    prompt: MJAIPromptEntityExtended

    The AI prompt to execute. Note: Get prompts from AIEngine.Instance.Prompts after calling AIEngine.Config()

    provider?: IMetadataProvider

    Optional per-request metadata provider for multi-user server isolation. Set by BaseAgent when invoking prompts so prompt run records are saved via the same isolated provider as the rest of the agent execution. When omitted, falls back to the global Metadata.Provider.

    rerunFromPromptRunID?: string

    Optional ID of a previous prompt run to indicate this is a rerun. When provided, the new AIPromptRun record will have its RerunFromPromptRunID field set to this value, establishing a link between the original and rerun executions.

    skipValidation?: boolean

    Whether to skip validation of the prompt output

    systemPromptOverride?: string

    Optional system prompt override that bypasses template rendering. When provided, this exact system prompt will be used instead of rendering the prompt's template. This is useful for re-running prompts with the exact system prompt from a previous run.

    templateData?: Record<string, unknown>

    Optional custom template data that augments the main data context

    templateMessageRole?: TemplateMessageRole

    Determines how the rendered template should be used in conversation messages 'system' - Add rendered template as system message (default) 'user' - Add rendered template as user message 'none' - Don't add rendered template to conversation

    timeoutMS?: number

    Optional wall-clock bound, in milliseconds, applied to EACH model call this prompt makes (per failover candidate / per validation retry / per parallel task — mirroring the parallel coordinator's existing taskTimeoutMS semantics).

    When set, AIPromptRunner composes this with cancellationToken (if any) into a single abort signal: BOTH bounds apply and whichever fires first aborts the call. Exceeding the timeout rejects with a typed AIPromptTimeoutError (classified as a retriable NetworkError), so it flows into the normal failover/retry machinery instead of hanging forever.

    When omitted (and the runner declares no DefaultPromptTimeoutMS), the model call is bounded ONLY by cancellationToken — i.e. unbounded if no token is supplied.

    verbose?: boolean

    Whether to enable verbose logging during prompt execution. When true, detailed information about model selection, API key checking, and execution steps will be logged. Can also be controlled via MJ_AI_VERBOSE environment variable.

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties