Runtime Model

This page explains the current core runtime model in force-app. Use it as the conceptual map for the rest of the docs before diving into service-level architecture.

Core Vocabulary Concept Model Read Early

Read Architecture Next Map Concepts To Config

The Core Idea

Loom separates how work is executed from where the interaction came from.

Runtime strategy answers: is this a conversational or direct execution?
Interaction channel answers: is this work happening through chat, email, API, or another transport?
Session and message records preserve continuity independently from the runtime strategy.

That separation is one of the most important ideas in the framework. It prevents the runtime from turning into a pile of special-case agent variants for every channel and workflow combination.

Runtime Strategy vs Interaction Channel

Concern	What it controls	Core examples
`RuntimeStrategy__c` on `AIAgentDefinition__c`	Execution behavior and orchestration style	`Conversational`, `Direct`
`InteractionChannel__c` on `AgentExecution__c`	The delivery or transport surface for a work unit	`Chat`, `Email`, `Direct`, provider-backed channels
`InteractionSession__c`	Durable continuity across messages and executions	Preserves thread or conversation context
`InteractionMessage__c`	Transport-level message records	Inbound and outbound channel messages

Execution Units

Agent Definition

AIAgentDefinition__c stores the agent’s prompts, provider binding, runtime strategy, memory, trust controls, and execution preferences.

Capability

AgentCapability__c defines what the agent can do, including implementation type, JSON schema, HITL mode, and exposure level.

Execution

AgentExecution__c is the durable work unit. It captures lifecycle state, resolved strategy, interaction channel, and turn coordination data.

Execution Steps

ExecutionStep__c stores the execution trace across user turns, assistant responses, tool calls, tool results, and failures.

Why These Record Boundaries Matter

These records may sound similar at first, but they answer different operational questions:

AIAgentDefinition__c: what behavior is this agent configured to have?
AgentExecution__c: what unit of work is running or has already run?
InteractionSession__c: what longer-lived conversation or thread does this belong to?
InteractionMessage__c: what actually came in or went out over the transport?
ExecutionStep__c: what did the runtime do internally while handling the work?

Once you keep those layers distinct, debugging becomes much easier because you know which record type should contain which kind of truth.

Main Runtime Flow

flowchart TD
  Start[StartExecution]
  ResolveTarget[ResolveAgentTarget]
  ResolveStrategy[ResolveStrategyAndChannel]
  StartStrategy[StartExecutionStrategy]
  PrepareLLM[PrepareAndCallLLM]
  ProcessResult[ProcessLlmResult]
  ExecuteTool[ExecuteCapability]
  WriteTrace[WriteExecutionStateAndSteps]

  Start --> ResolveTarget
  ResolveTarget --> ResolveStrategy
  ResolveStrategy --> StartStrategy
  StartStrategy --> PrepareLLM
  PrepareLLM --> ProcessResult
  ProcessResult --> ExecuteTool
  ExecuteTool --> PrepareLLM
  ProcessResult --> WriteTrace
  ExecuteTool --> WriteTrace

Inbound and Session Continuity

For channel-driven traffic, the framework uses one shared inbound path:

flowchart TD
  Inbound[InboundMessage]
  Normalize[NormalizeEnvelope]
  Route[ResolveChannelRoute]
  Session[ResolveOrCreateInteractionSession]
  Message[PersistInteractionMessage]
  Execute[StartAgentExecution]

  Inbound --> Normalize
  Normalize --> Route
  Route --> Session
  Session --> Message
  Message --> Execute

That model gives the framework a few important properties:

channel entrypoints can stay thin
session continuity is durable
the same execution engine can be reused across multiple delivery surfaces

Trust Layers in the Runtime

PII Masking

Sensitive values can be masked before provider calls so prompts and tool payloads are safer to send outside Salesforce.

Prompt Safety

Provider adapters can run native safety checks before or during model interaction.

Tool Flow Graph

Tool eligibility can be constrained at runtime so only currently valid tools are exposed to the model.

Human-in-the-Loop

Capabilities can require confirmation or approval before executing sensitive actions.

Common Modeling Mistakes

treating runtime strategy and interaction channel as the same setting
assuming every execution should have conversational continuity
reading only AgentExecution__c and skipping ExecutionStep__c when diagnosing behavior
using one agent definition for unrelated jobs that should be separate runtimes
thinking of sessions as just chat UX state rather than durable continuity records

Extension Points

The core framework is intentionally extensible at a few clear seams:

IAgentAction and BaseAgentAction for new tool implementations
IAgentContextProvider for dynamic business context
ILLMProviderAdapter and BaseProviderAdapter for new model providers
IMemoryManager for alternative memory strategies
strategy and channel registries for runtime evolution

Continue

Architecture

Configuration

Security