AI Agent Studio is built on a modular, plugin-based architecture using Strategy, Factory, and Chain of Responsibility patterns. The framework separates concerns across orchestration, execution, memory, security, and observability layers.
Orchestrators
Four execution patterns: Conversational (multi-turn chat), Function (single-task with sync/async routing), Workflow (multi-agent state machines), Email (thread processing with auto-reply).
All extend BaseAgentOrchestrator and implement IAgentOrchestrator interface.
LLM Providers
Multi-provider support: OpenAI, Claude (addon), Gemini (addon). Extensible via ILLMProviderAdapter interface.
BaseProviderAdapter provides common HTTP handling, retry logic, and error normalization.
Actions
Standard actions: GetRecordDetails, CreateRecord, UpdateRecord, FlowHandler, PostChatter.
Addon actions: RunReport, SearchKnowledge, SendNotification.
Extend BaseAgentAction implementing IAgentAction interface.
Context Providers
Dynamic data enrichment: Supply related records, user context, and computed data to agents.
Implement IAgentContextProvider interface with bulk-safe, security-enforced queries.
Request Entry
Request enters via AgentExecutionService.startExecution() (invocable from Flow/Apex) or REST API endpoint /services/apexrest/ai/agent/process/.
Orchestrator Routing
AgentExecutionService.getOrchestrator() uses AgentOrchestratorMapping__mdt to route by agent type to ConversationalOrchestrator, FunctionOrchestrator, WorkflowOrchestrator, or EmailOrchestrator.
Security Checks
Prompt Safety: PromptSafetyService runs 3-layer detection (pattern-based, heuristic, structural) with configurable response modes (Block/Sanitize/Flag/LogOnly).
PII Masking: PIIMaskingService applies hybrid masking (schema-based + pattern-based) with deterministic token replacement.
Context Assembly
Memory: ContextManagerService retrieves conversation history via IMemoryManager implementations (BufferWindow or SummaryBuffer).
Dynamic Context: ContextResolverService invokes registered IAgentContextProvider implementations to gather related data.
System Prompt: SystemPromptBuilder assembles identity, instructions, context, and orchestrator-specific additions.
LLM Inference
Request Building: LLMInteractionService.prepareAndCallLLM() formats messages and tools via LLMFormattingService.
Tool Reasoning: If enabled, adds _rationale parameter to all tools for explainability.
Provider Call: Routes to ILLMProviderAdapter implementation (OpenAIProviderAdapter, ClaudeProviderAdapter, GeminiProviderAdapter).
Response Parsing: Normalizes provider-specific responses into ProviderResult.
Response Processing
OrchestrationService.processLlmResult() selects handler based on response type:
ToolCallResponseHandler validates dependencies (if enabled), executes tools, manages async dispatchContentResponseHandler processes text responses, handles email replies for EmailOrchestratorThree-Tier Error Policy: Capability FailFast → MaxRetries → Pass to LLM for recovery
Action Execution
CapabilityExecutionService routes to action implementations:
StandardActionHandler__mdt to framework actionsType.forName()Flow.Interview.createInterview()HITL: If configured, routes through HITLGatewayService for approval workflows.
Security: TypeCoercionService.coerceArgumentTypesForSObject() enforces FLS on field access.
State Management
Execution Records: AgentStateService manages AgentExecution__c lifecycle with status tracking (Idle/Processing/Completed/Failed/Cancelled).
Step Logging: ExecutionStepService creates ExecutionStep__c for detailed execution trace (UserInput/AgentResponse/ToolCall/ToolResult/Error).
Decision Steps: AgentDecisionStepLogger creates AgentDecisionStep__c for UI storyboard display.
Turn Tracking: CurrentTurnIdentifier__c enables stale execution detection via StaleJobDetector.
Async Continuation
Follow-up LLM: FollowUpLLMEngine handles multi-turn responses, supports deferred DML optimization.
Async Actions: AsyncActionEngine executes long-running tools in separate queueable.
Multi-LLM Optimization: TransactionContext tracks DML/callout operations to determine if immediate follow-up is possible.
Completion
Status Update: AgentStateService.updateStatus() commits buffered DML (if deferred mode enabled) and sets terminal state.
Events: Publishes AgentResponse__e Platform Event for conversational agents.
Workflow Callbacks: For child agents, triggers onChildComplete() on parent orchestrator.
| Service | Responsibility |
|---|---|
AgentExecutionService | Entry point, orchestrator routing, service user context switching |
OrchestrationService | LLM response processing, handler selection (ToolCallResponseHandler vs ContentResponseHandler) |
LLMInteractionService | LLM communication, prompt building, provider adapter routing |
AgentStateService | Execution lifecycle management, status updates, Platform Event publishing |
CapabilityExecutionService | Tool/action execution, handler factory (Standard/Apex/Flow) |
ContextManagerService | Context ledger, memory strategy selection (BufferWindow vs SummaryBuffer) |
AIAgentConfigService | Configuration repository (agents, capabilities, context providers) |
ExecutionStepService | Execution step CRUD, deferred DML buffering |
TypeCoercionService | Type conversion with FLS enforcement for SObject fields |
AgentJobEnqueuer | Async job dispatch (Queueable vs Platform Event based on AsyncDispatchType__c) |
AgentDecisionStepLogger | Decision logging for storyboard UI explainability |
TransactionContext | Multi-LLM optimization, deferred DML mode, LLM call tracking, tool safety detection |
PromptSafetyService | Multi-layer jailbreak detection with configurable response modes |
PIIMaskingService | Hybrid PII masking (schema-based + pattern-based) with bidirectional unmask |
ToolDependencyValidator | Declarative tool sequencing constraint enforcement |
AgentExecutionDispatcher | DLQ-based dispatch for multi-record executions with BatchId correlation |
AgentExecutionWorker | DLQ worker with self-pull pattern and FOR UPDATE locking |
StaleJobDetector | Scheduled recovery of stuck executions (checks ProcessingStartedAt__c) |
Core agent configuration:
Identity & Behavior: AgentType__c (Conversational/Function/Workflow/Email), IdentityPrompt__c and InstructionsPrompt__c (System prompt components), EnableToolReasoning__c (Require LLM to explain tool selection), EnableParallelToolCalling__c (Allow multiple tools per response).
Memory & Context: LLMConfiguration__c (LLM provider settings lookup), MemoryStrategy__c (Buffer Window/Summary Buffer), HistoryTurnLimit__c (Number of turns to remember).
Security & Trust: PIIMaskingMode__c (Hybrid/Schema-Only/Pattern-Only), SensitiveClassifications__c (Data classifications to mask), PromptSafetyMode__c (Block/Sanitize/Flag/LogOnly), SafetyThreshold__c (Threat score threshold 0.0-1.0).
Performance: AsyncDispatchType__c (High for Platform Events / Low for Queueable), MaxProcessingCycles__c (Max LLM turns per execution), EnableDependencyValidation__c (Enforce tool dependency graph).
Workflow: ToolDependencyGraph__c (JSON dependency graph for validation).
Tool/function definitions:
Basic Config: CapabilityName__c (Tool name exposed to LLM), Description__c (When and how to use this tool - critical for LLM guidance), ImplementationType__c (Standard/Apex/Flow), StandardActionType__c (Maps to StandardActionHandler__mdt), ImplementationDetail__c (Apex class name or Flow API name).
Schema: Parameters__c (JSON Schema for LLM defining expected arguments), BackendConfiguration__c (Admin config JSON passed to action implementation).
Execution: RunAsynchronously__c (Execute in separate queueable), FailFastOnError__c (Immediate failure on error vs pass to LLM), HITLMode__c (Human-in-the-loop mode: Disabled/Confirmation/Approval/ConfirmationThenApproval), ExposureLevel__c (External visible to LLM / Internal framework only / Disabled).
Execution tracking:
Status Fields: ExecutionStatus__c (Idle/Processing/Completed/Failed/Cancelled for lifecycle-level), ProcessingStatus__c (Idle/Processing/Awaiting Action/Awaiting Followup/Failed for turn-level), CurrentTurnIdentifier__c (Stale execution detection via StaleJobDetector).
Context: SourceRecordId__c (Context record like Account or Case), OriginalUserId__c (User who initiated execution), ServiceUserId__c (Service user if RequiresServiceUserContext__c).
Multi-Record DLQ: BatchId__c (Correlation ID for grouping related executions), Priority__c (Execution priority where higher = more urgent, default 0), ProcessingStartedAt__c (Timestamp when worker started for stale detection), RetryCount__c, MaxRetries__c, NextRetryAt__c (Exponential backoff tracking).
Async Coordination: PendingAsyncToolCount__c (Atomic counter for async tool tracking).
Detailed execution log for observability:
Step Metadata: StepType__c (UserInput/AgentResponse/ToolCall/ToolResult/Error), StepRole__c (User/Assistant/Tool), TurnIdentifier__c (Groups steps by LLM turn).
Content: Content__c (Step payload/result data), ToolRationale__c (LLM reasoning for tool selection if EnableToolReasoning__c), IsAsyncToolExecution__c (Async execution flag).
Token Economics: PromptTokens__c, CompletionTokens__c, TotalTokens__c, EstimatedCostUSD__c (Cost tracking for budget monitoring).
Enables multiple LLM calls within a single transaction when intervening tools don’t perform DML or callouts.
Flow: Entry enables deferred DML → ExecutionStepService buffers inserts → After each LLM call, check eligibility → If safe: continue in same transaction → On completion: commit all buffered DML
Eligibility: Deferred mode enabled + Pre-existing execution + No DML/callouts + Under max LLM calls limit
Benefits: Reduced latency (no queueable delays), fewer async jobs, faster UX
Multi-record executions use DLQ pattern for resilient processing at scale.
Flow: Dispatcher creates AgentExecution__c records with BatchId__c → Enqueue limited workers → Worker claims with FOR UPDATE → Process → On completion, trigger chains next pending record → Workers exhaust naturally
Features: Priority ordering (Priority__c DESC), exponential backoff (NextRetryAt__c), stale job recovery (StaleJobDetector), progress tracking (getBatchProgress)
Declarative tool sequencing prevents workflow hallucinations.
Flow: LLM generates dependency graph → Admin approves → System enforces at runtime
Two-Phase: Pre-flight validation + topological sort → Runtime validation during execution
Circuit Breaker: Tracks violations, fails if threshold exceeded
Storyboard UI: AgentStoryboardController provides data for LWC components (agentStoryboard, agentExecutionView, workflowView, agentStoryboardStep)
Execution Trace: ExecutionStep__c records capture complete interaction history with token tracking
Decision Timeline: AgentDecisionStep__c provides user-friendly execution visualization
Tool Reasoning: When enabled, captures LLM rationale for tool selection for transparency
Cost Analytics: Token and cost tracking per step enables budget monitoring and optimization