Configuration

Configuration is where the framework stops being abstract and starts becoming a real operating model inside your Salesforce org.

This page is not just a field inventory. It is a guide to making good decisions about:

• what kind of work an agent should do
• what tools it should be allowed to use
• how much continuity and autonomy it should have
• what trust and approval controls should wrap that behavior

Public docs boundary

This page focuses on core configuration in force-app. Addon-only authoring surfaces and internal extensions are intentionally not documented here.

Admin Guide Architecture To Metadata Production Behavior

Review Runtime Model See Pattern Examples

Start With Decisions, Not Fields

The most useful way to approach configuration is to answer four questions in order:

1. What kind of runtime is this: conversational or direct?
2. What tools should the agent be allowed to see and use?
3. How much continuity, iteration, and autonomy should it have?
4. What controls should protect provider calls and side effects?

When teams skip these questions and jump straight into record editing, they often end up with agents that are technically valid but operationally hard to trust.

Configuration Layers

Agent definition

Sets prompts, provider binding, runtime strategy, memory behavior, trust controls, and execution preferences.

Capabilities

Define the tools exposed to the model, including implementation type, schema, and human-review settings.

Provider config

Controls how the framework talks to the LLM provider, including credentials, adapter class, and model defaults.

Channel metadata

Routes inbound channel traffic and delivery policy independently from the runtime strategy.

A Simple Mental Model

You can think of core configuration as four layers:

• the agent definition says what the agent is and how it should behave
• provider configuration says how the framework talks to the model
• capabilities say what the model is allowed to do
• routing and channel settings say how inbound traffic reaches the agent

That separation matters because changing one layer should not require rethinking the whole system.

Choose The Runtime Shape First

Before editing prompts or capabilities, decide what shape of work you are configuring.

If the agent should…	Start with…
support an ongoing conversation or thread	RuntimeStrategy__c = Conversational
complete a bounded task with a clear input and output	RuntimeStrategy__c = Direct
preserve continuity across user turns	conversational strategy plus session-aware surfaces
behave more like automation than conversation	direct strategy plus narrow capability contracts

This decision affects almost everything that follows: prompts, memory, tool choice, testing approach, and approval design.

Agent Definition

The agent definition is the highest-level behavior record. It is where you decide what the agent is, how it reasons, how much continuity it carries, and what safety controls apply before tools even run.

The settings that matter most

Field	Purpose	Notes
DeveloperName__c	Stable API-facing name	Used in entrypoints and component configuration
RuntimeStrategy__c	Execution style	Core values are Conversational and Direct
LLMConfiguration__c	Provider binding	Points to the provider configuration record
IsActive__c	Activation state	Disable quickly when troubleshooting or rolling back

The rest of the agent definition mostly falls into three buckets:

• prompt and behavior settings
• memory and execution settings
• trust and control settings

You do not need to obsess over every field on day one. What matters most is whether the agent has a clear job, a sensible runtime shape, and a small enough amount of autonomy to be trustworthy.

Prompt and behavior fields

Field	Purpose
IdentityPrompt__c	Who the agent is
InstructionsPrompt__c	How the agent should behave
EnableActionTransparency__c	Whether tool execution details are exposed to users
EnableToolReasoning__c	Whether tool-choice rationale is captured
AuditLevel__c	Logging depth for execution traces

Prompt configuration should define role and behavior, not hide business routing or access rules that belong elsewhere. If a prompt is carrying core security or routing logic, the metadata model is probably underused.

Memory and execution fields

Field	Purpose	Typical starting point
MemoryStrategy__c	How history is retained	Buffer Window for shorter conversations
HistoryTurnLimit__c	Number of turns carried forward	8 to 10
AsyncDispatchType__c	Queueable vs high-throughput dispatch choice	Low for debugging, High for scale
MaxProcessingCycles__c	Limits LLM-tool iteration depth	Keep conservative for early rollout

For first production rollout, conservative settings are usually better:

• shorter history windows
• fewer processing cycles
• smaller capability sets
• lower temperature

You can always expand autonomy later after the runtime is trustworthy.

Trust and control fields

Field	Purpose
PIIMaskingPreset__c	Controls masking breadth before provider calls
PromptSafetyPreset__c	Enables provider-adapter safety behavior
EnableToolFlowGraph__c	Turns on runtime tool gating
ToolFlowGraph__c	JSON graph describing entry tools and allowed transitions

These settings should be chosen based on workflow risk, not turned on blindly. A narrow direct automation path and a sensitive conversational support assistant do not need the same control mix.

Service-user routing

Use service-user routing only when the workflow genuinely needs a different execution user context.

Field	Purpose
RequiresServiceUserContext__c	Routes through the service-user path
ServiceUserNamedCredential__c	Named Credential used for loopback service-user calls

Use this mode only when there is a clear need for a distinct execution user context. It should be a deliberate architectural choice, not a default workaround for missing permissions.

LLM Configuration

Provider configuration is the connection layer between Salesforce and the model.

It answers questions like:

• which provider are we calling?
• which model should we use by default?
• how is authentication handled?
• what baseline settings should agent requests inherit?

Field	Purpose
NamedCredential__c	Provider endpoint and auth
ProviderAdapterClass__c	Adapter implementation such as OpenAIProviderAdapter
DefaultModelIdentifier__c	Model sent on provider calls
DefaultTemperature__c	Default response variability
IsActive__c	Controls availability for agents

Predictable tool use

For early production rollout, start with a lower default temperature. It usually produces more consistent action selection and less prompt drift.

Provider configuration should answer transport-level questions, not business ones. It is about model access, endpoint behavior, and defaults, not about what the agent should be allowed to do.

Capabilities

Capabilities are the tool contracts the model sees. Keep them narrow, explicit, and observable.

In practice, this is where many agent quality and trust problems are created or avoided.

Capability design principles

• one clear business purpose per capability
• descriptions that explain when to use and when not to use the tool
• schemas that constrain the model toward valid inputs
• backend configuration that keeps sensitive or operational values under admin control

Good capabilities feel like well-designed APIs. Poor capabilities feel like vague internal shortcuts.

Capability fields

Field	Purpose
CapabilityName__c	Tool name surfaced to the model
Description__c	Primary model guidance for when and how to use the tool
ImplementationType__c	Standard, Apex, Flow, or Agent
BackendConfiguration__c	Admin-owned JSON configuration
Parameters__c	JSON Schema for runtime inputs
ExposureLevel__c	Whether the tool is visible to the model
RunAsynchronously__c	Moves tool execution into a separate transaction when appropriate

Three fields matter especially at the start:

• Description__c, because it strongly shapes tool choice
• Parameters__c, because it constrains what the model can pass
• BackendConfiguration__c, because it keeps operational values under admin control

If those three are weak, the rest of the configuration will rarely rescue the outcome.

Human review fields

Field	Purpose	Notes
HITLMode__c	Human review mode	Includes Confirmation, Approval, ConfirmationThenApproval, and ConditionalApproval
HITLNotificationPreference__c	Notification behavior for approval-based flows	Used when approval records are involved

Configuration caveat

ConfirmationThenApproval is only valid for interactive conversational agents and should not be combined with asynchronous tool execution.

Use approval modes to express business risk, not to patch unclear tool design. If a capability is so broad that every use feels risky, it usually needs to be split into smaller capabilities first.

Channel and Routing Metadata

For channel-driven interaction, the framework uses configuration instead of burying routing logic inside prompts or code.

Metadata or object	Role
AgentChannelRoute__mdt	Maps channel and entry conditions to an agent
ChannelEndpoint__mdt	Defines endpoint and provider settings for channel ingress and delivery
InteractionChannelType__mdt	Describes available channel types and adapter classes

This is where channel routing lives. It is separate from runtime strategy.

That distinction matters. A conversational agent can still behave differently across chat, email, and other channels because the interaction channel shapes payload normalization, session behavior, and delivery policy even when the runtime strategy is the same.

In other words:

• strategy says how the work behaves
• channel says how the interaction arrives and how replies should be handled
• route metadata says which agent should own the work

Recommended Starting Profiles

Conversational assistant

• RuntimeStrategy__c = Conversational
• MemoryStrategy__c = Buffer Window
• one read-only capability first
• confirmation or approval on any write capability
• masking and prompt safety enabled for sensitive domains

Direct automation

• RuntimeStrategy__c = Direct
• minimal capability set
• lower temperature
• asynchronous execution for heavier tasks
• strict schemas and concise tool descriptions

These are starting points, not permanent answers. The right profile depends on the workflow, regulatory risk, user expectations, and how much runtime autonomy the team is prepared to operate.

Configuration Review Checklist

1. Verify strategy, provider, and memory settings on the agent definition.
2. Confirm capability descriptions, JSON schema, and backend configuration are narrow and specific.
3. Turn on approval or confirmation for any side-effecting capability.
4. Validate Named Credentials and provider adapter settings before debugging prompts.
5. Test with realistic users to confirm sharing, CRUD, FLS, and route behavior.

Common Configuration Anti-Patterns

• using one agent as a catch-all for unrelated workflows
• exposing too many write capabilities before read-only behavior is stable
• keeping tool descriptions vague because “the model is smart enough”
• using service-user routing as the first answer to permission problems
• enabling trust controls without defining the operational ownership for approval, rejection, and fallback behavior

Final Advice

Good configuration is not about setting every field. It is about making the runtime legible, bounded, and governable.

If you are unsure what to configure next, do not ask “what else can this agent do?” Ask:

• is the current behavior trustworthy?
• are the tool contracts narrow enough?
• are the permissions and approval rules clear?
• can we explain why the agent behaved the way it did?