Class AgentRunner

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

AgentRunner

Example

const runner = new AgentRunner();
const result = await runner.RunAgent({
  agent: myAgent,
  conversationMessages: messages,
  contextUser: currentUser
});

Index

Constructors

constructor

Methods

CheckForDuplicateVersion CreateMediaArtifacts FindPreviousArtifactForMessage GetMaxVersionForArtifact LinkArtifactToConversationDetail ProcessAgentArtifacts ProcessFileArtifacts RunAgent RunAgentInConversation SaveAgentRunMedia

Constructors

constructor

new AgentRunner(provider?: IMetadataProvider): AgentRunner
Parameters
- Optionalprovider: IMetadataProvider
Returns AgentRunner
- Defined in AI/Agents/src/AgentRunner.ts:63

Methods

`Protected`CheckForDuplicateVersion

CheckForDuplicateVersion(
    artifactId: string,
    candidateContent: string,
    latestVersionNumber: number,
    contextUser: UserInfo,
    provider?: IMetadataProvider,
): Promise<string>
Checks whether the serialized content for a new artifact version is identical to the latest existing version of the same artifact, using SHA-256 content hashing.

When the content is unchanged, creating a new version adds noise without value. This method computes the hash of the candidate content and compares it against the ContentHash stored on the most recent version (populated by MJArtifactVersionEntityServer.Save()).
Parameters
- artifactId: string
  The artifact whose latest version to compare against
- candidateContent: string
  The serialized (JSON-stringified) content that would become the new version
- latestVersionNumber: number
  The version number of the current latest version
- contextUser: UserInfo
  User context for the RunView query
- Optionalprovider: IMetadataProvider
Returns Promise<string>
The existing version's ID if content is identical, or null if a new version should be created
- Defined in AI/Agents/src/AgentRunner.ts:643

CreateMediaArtifacts

CreateMediaArtifacts(
    conversationDetailId: string,
    mediaOutputs: MediaOutput[],
    contextUser: UserInfo,
    provider?: IMetadataProvider,
): Promise<void>
Creates MJ: Artifact + MJ: Artifact Version + MJ: Conversation Detail Artifact junction records for agent-produced media outputs (images, audio, video).

Replaces the deprecated CreateConversationMediaAttachments path which wrote to the MJ: Conversation Detail Attachments table (then auto-paired to an artifact via the server-side hook). Writing artifacts directly removes the deprecated-entity dependency and the redundant dual-write.

Reuses createArtifactWithVersion — the same helper that ProcessFileArtifacts uses — so artifact creation logic (MIME resolution, transaction wrapping, junction linking) lives in exactly one place.
Parameters
- conversationDetailId: string
  The conversation detail to link artifacts to
- mediaOutputs: MediaOutput[]
  Media outputs to persist as artifacts
- contextUser: UserInfo
  User context for DB operations
- Optionalprovider: IMetadataProvider
  Optional metadata provider for multi-provider support
Returns Promise<void>
Since
5.38.0
- Defined in AI/Agents/src/AgentRunner.ts:1213

FindPreviousArtifactForMessage

FindPreviousArtifactForMessage(
    conversationDetailId: string,
    contextUser: UserInfo,
    provider?: IMetadataProvider,
): Promise<{ artifactId: string; versionNumber: 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.
Parameters
- conversationDetailId: string
  The conversation detail ID to query
- contextUser: UserInfo
  The user context for the query
- Optionalprovider: IMetadataProvider
Returns Promise<{ artifactId: string; versionNumber: number }>
Artifact info if exists, null if this is the first artifact for this message
Example
```
const runner = new AgentRunner();
const previousArtifact = await runner.FindPreviousArtifactForMessage(detailId, currentUser);
if (previousArtifact) {
    console.log(`Found artifact ${previousArtifact.artifactId} at version ${previousArtifact.versionNumber}`);
}
```
- Defined in AI/Agents/src/AgentRunner.ts:725

GetMaxVersionForArtifact

GetMaxVersionForArtifact(
    artifactId: string,
    contextUser: UserInfo,
    provider?: IMetadataProvider,
): Promise<number>
Gets the maximum version number for an artifact. Used when creating new versions of explicitly specified artifacts.
Parameters
- artifactId: string
  The artifact ID to query
- contextUser: UserInfo
  The user context for the query
- Optionalprovider: IMetadataProvider
Returns Promise<number>
The maximum version number, or 0 if no versions exist
Example
```
const runner = new AgentRunner();
const maxVersion = await runner.GetMaxVersionForArtifact(artifactId, currentUser);
const newVersionNumber = maxVersion + 1;
```
- Defined in AI/Agents/src/AgentRunner.ts:606

`Protected`LinkArtifactToConversationDetail

LinkArtifactToConversationDetail(
    versionId: string,
    conversationDetailId: string,
    artifactId: string,
    versionNumber: number,
    contextUser: UserInfo,
    provider: IMetadataProvider,
): Promise<{ artifactId: string; versionId: string; versionNumber: number }>
Creates a ConversationDetailArtifact junction record linking an artifact version to a conversation detail, then returns the standard artifact result tuple.

Extracted as a helper so both the normal version-creation path and the duplicate-skip path can share the same linking and return logic.
Parameters
- versionId: string
  The artifact version ID to link
- conversationDetailId: string
  The conversation detail to link to
- artifactId: string
  The parent artifact ID (passed through to the return value)
- versionNumber: number
  The version number (passed through to the return value)
- contextUser: UserInfo
  User context for the save operation
- provider: IMetadataProvider
  Metadata provider for entity creation
Returns Promise<{ artifactId: string; versionId: string; versionNumber: number }>
The standard artifact result tuple
- Defined in AI/Agents/src/AgentRunner.ts:683

ProcessAgentArtifacts

ProcessAgentArtifacts<R>(
    agentResult: ExecuteAgentResult<R>,
    conversationDetailId: string,
    sourceArtifactId: string,
    contextUser: UserInfo,
    provider?: IMetadataProvider,
): Promise<{ artifactId: string; versionId: string; versionNumber: number }>
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'
Type Parameters
- R
Parameters
- agentResult: ExecuteAgentResult<R>
  The result from agent execution containing the payload
- conversationDetailId: string
  The conversation detail to link the artifact to. May be undefined for runs executed OUTSIDE a conversation context (e.g. realtime voice delegations): the artifact + version are still created, but the previous-artifact lookup and the ConversationDetailArtifact junction link are skipped.
- sourceArtifactId: string
  Optional explicit artifact to version from (agent continuity)
- contextUser: UserInfo
  The user context for the operation
- Optionalprovider: IMetadataProvider
Returns Promise<{ artifactId: string; versionId: string; versionNumber: number }>
Artifact metadata if created, undefined if skipped or failed
Example
```
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}`);
}
```
- Defined in AI/Agents/src/AgentRunner.ts:803

ProcessFileArtifacts

ProcessFileArtifacts(
    fileOutputs: FileOutputRef[],
    conversationDetailId: string,
    contextUser: UserInfo,
    resolvedStorageAccountId?: string,
    provider?: IMetadataProvider,
    acceptUnregisteredFiles?: boolean,
): Promise<void>
Creates MJ: Artifact records for file outputs collected during agent execution. Reads directly from ExecuteAgentResult.fileOutputs — no DB query needed.

Called automatically by RunAgentInConversation after the agent completes.
Parameters
- fileOutputs: FileOutputRef[]
  File outputs collected by BaseAgent during action execution
- conversationDetailId: string
  The conversation detail to link artifacts to
- contextUser: UserInfo
  User context for DB operations
- OptionalresolvedStorageAccountId: string
  Pre-resolved FileStorageAccount ID from the agent's hierarchical resolution chain (Runtime → Agent → Category → Type → fallback). When provided, uploads use this specific account instead of picking the first active one.
- Optionalprovider: IMetadataProvider
- OptionalacceptUnregisteredFiles: boolean
Returns Promise<void>
- Defined in AI/Agents/src/AgentRunner.ts:1284

RunAgent

RunAgent<C = any, R = any>(
params: ExecuteAgentParams<C>,
): Promise<ExecuteAgentResult<R>>
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
Type Parameters
- C = any
  The type of the agent's context as provided in the ExecuteAgentParams
- R = any
  The type of the agent's result as returned in ExecuteAgentResult
Parameters
- params: ExecuteAgentParams<C>
  Parameters for agent execution (same as BaseAgent.Execute)
Returns Promise<ExecuteAgentResult<R>>
The execution result (same as BaseAgent.Execute)

Throws
Throws if agent type loading fails or agent instantiation fails
- Defined in AI/Agents/src/AgentRunner.ts:83

RunAgentInConversation

RunAgentInConversation<C = any, R = any>(
    params: ExecuteAgentParams<C>,
    options: {
        conversationDetailId?: string;
        conversationId?: string;
        conversationName?: string;
        createArtifacts?: boolean;
        sourceArtifactId?: string;
        testRunId?: string;
        userMessage?: string;
    },
): Promise<
    {
        agentResponseDetailId?: string;
        agentResult: ExecuteAgentResult<R>;
        artifactInfo?: {
            artifactId: string;
            versionId: string;
            versionNumber: number;
        };
        conversationId: string;
        userMessageDetailId: string;
    },
>
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
Type Parameters
- C = any
- R = any
Parameters
- params: ExecuteAgentParams<C>
  Core agent execution parameters
- options: {
      conversationDetailId?: string;
      conversationId?: string;
      conversationName?: string;
      createArtifacts?: boolean;
      sourceArtifactId?: string;
      testRunId?: string;
      userMessage?: string;
  }
  Conversation-specific options
  - OptionalconversationDetailId?: string
    Optional existing conversation detail ID. If provided, skips conversation/detail creation
  - OptionalconversationId?: string
    Optional existing conversation ID. If not provided, a new conversation will be created
  - OptionalconversationName?: string
    Optional conversation name (only used when creating new conversation)
  - OptionalcreateArtifacts?: boolean
    Whether to create artifacts from the agent's payload (default: true)
  - OptionalsourceArtifactId?: string
    Optional source artifact ID for versioning (agent continuity/refinement)
  - OptionaltestRunId?: string
    Optional test run ID to link conversation and details to (for test execution traceability)
  - OptionaluserMessage?: string
    The user's message text for this conversation turn (required if conversationDetailId not provided)
Returns Promise<
    {
        agentResponseDetailId?: string;
        agentResult: ExecuteAgentResult<R>;
        artifactInfo?: {
            artifactId: string;
            versionId: string;
            versionNumber: number;
        };
        conversationId: string;
        userMessageDetailId: string;
    },
>
Promise containing the agent execution result and conversation/artifact metadata
Example
```
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
});
```
- Defined in AI/Agents/src/AgentRunner.ts:159

SaveAgentRunMedia

SaveAgentRunMedia(
    agentRunId: string,
    mediaOutputs: MediaOutput[],
    contextUser: UserInfo,
    provider?: IMetadataProvider,
): Promise<string[]>
Saves media outputs to AIAgentRunMedia table for permanent storage. Creates a record for each media output promoted during agent execution. All items in the array are saved.
Parameters
- agentRunId: string
  The ID of the agent run
- mediaOutputs: MediaOutput[]
  Array of media outputs to save
- contextUser: UserInfo
  User context for the operation
- Optionalprovider: IMetadataProvider
Returns Promise<string[]>
Array of saved AIAgentRunMedia IDs
Since
3.1.0
Example
```
const runner = new AgentRunner();
const mediaIds = await runner.SaveAgentRunMedia(
    agentResult.agentRun.ID,
    agentResult.mediaOutputs,
    currentUser
);
console.log(`Saved ${mediaIds.length} media outputs`);
```
- Defined in AI/Agents/src/AgentRunner.ts:1051

Class AgentRunner

Example

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns AgentRunner

Methods

ProtectedCheckForDuplicateVersion

Parameters

Returns Promise<string>

CreateMediaArtifacts

Parameters

Returns Promise<void>

Since

FindPreviousArtifactForMessage

Parameters

Returns Promise<{ artifactId: string; versionNumber: number }>

Example

GetMaxVersionForArtifact

Parameters

Returns Promise<number>

Example

ProtectedLinkArtifactToConversationDetail

Parameters

Returns Promise<{ artifactId: string; versionId: string; versionNumber: number }>

ProcessAgentArtifacts

Type Parameters

Parameters

Returns Promise<{ artifactId: string; versionId: string; versionNumber: number }>

Example

ProcessFileArtifacts

Parameters

Returns Promise<void>

RunAgent

Type Parameters

Parameters

Returns Promise<ExecuteAgentResult<R>>

Throws

RunAgentInConversation

Type Parameters

Parameters

OptionalconversationDetailId?: string

OptionalconversationId?: string

OptionalconversationName?: string

OptionalcreateArtifacts?: boolean

OptionalsourceArtifactId?: string

OptionaltestRunId?: string

OptionaluserMessage?: string

Returns Promise< { agentResponseDetailId?: string; agentResult: ExecuteAgentResult<R>; artifactInfo?: { artifactId: string; versionId: string; versionNumber: number; }; conversationId: string; userMessageDetailId: string; },>

Example

SaveAgentRunMedia

Parameters

Returns Promise<string[]>

Since

Example

Settings

On This Page

`Protected`CheckForDuplicateVersion

`Protected`LinkArtifactToConversationDetail

`Optional`conversationDetailId?: string

`Optional`conversationId?: string

`Optional`conversationName?: string

`Optional`createArtifacts?: boolean

`Optional`sourceArtifactId?: string

`Optional`testRunId?: string

`Optional`userMessage?: string

Returns Promise<
{
agentResponseDetailId?: string;
agentResult: ExecuteAgentResult<R>;
artifactInfo?: {
artifactId: string;
versionId: string;
versionNumber: number;
};
conversationId: string;
userMessageDetailId: string;
},
>