ContentVersion Agent Workflow (RunAgent)

How to run an agent against a Salesforce file (ContentVersion) via Flow and let it classify/label the linked parent record.

When this works

Your Flow calls RunAgentAction with recordId set to a ContentDocument Id (069…).
The AIModel__c agent is configured for SObjectType__c = ContentDocument and has a DML-capable skill/tool (for example, dml_sobjects or a custom invoke_apex function) to write back to the parent record.
A business ContentDocumentLink exists to the target parent record; otherwise the “current record” will be the file itself.
Textract/text extraction for the ContentVersion has completed (cached text present); otherwise the API returns a “Give me a minute…” message and you must retry later.

What the model sees

RunAgentAction populates systemMessage with AIModel.getSystemPrompt(RunContext.Background), which includes:

# File Context with ContentVersionId/ContentDocumentId and ContentVersion field metadata.
# Record Context (the record you should read/update) with the EffectiveRecordId/ObjectType, resolved by walking the most recent business ContentDocumentLink (falls back to the ContentDocument if no business links).
Optional full field tables for the parent record when IncludeAllSObjectLabelsValues__c or IncludeAllSObjectMetadata__c is enabled on the agent.
Merge tags (e.g., {{RecordID}}, {{File.ContentVersionId}}) replaced with the effective values.

POSTAIResponse then builds final instructions as:

Default document assistant prompt.
The agent systemMessage above (with record + file context).
The extracted document text appended inline.

Result: the model has both the parent record ID/type and the document text at the same time, so prompts like “read the file and update these fields” are actionable.

Flow wiring (inputs to RunAgentAction)

recordId: required, must be the ContentDocument Id of the file you want processed.
agentName or systemAgentId: required agent lookup (AIModel__c).
userPrompt: optional kickoff instruction (e.g., “Classify this invoice and set Amount__c/Invoice_Date__c.”).
runAsync: keep true for background agents (default).
contentVersionId input is not used; the action always uses the latest published version of the provided ContentDocument.

Preconditions & safeguards

Ensure the agent has permission to update the target object (via the DML tool/skill and auth context). Background run uses SYSTEM_MODE for config objects; business object queries honor ExecPolicy.
Set IncludeAllSObjectLabelsValues__c (and/or IncludeAllSObjectMetadata__c) if you want all parent fields exposed in the prompt.
Verify a business CDL exists; without it the EffectiveRecordId stays on the ContentDocument, so no parent fields are available to update.
Extraction must exist: Textract/DialogueCache needs cached text for the ContentVersion; otherwise the API replies with the waiting message and does not run tools.

Operational notes

The action always targets the latest published ContentVersion of the ContentDocument passed in recordId.
Parent resolution picks the most recent business-linked ContentDocumentLink (SystemModstamp order). If multiple links exist, update the CDL you want to take precedence.
If the agent should update multiple records, add a custom skill to locate related records; only one EffectiveRecordId is injected automatically.
Use transcripts/events to confirm the run: response.message holds the assistant completion; platform events capture recordId and contentVersionId.

Troubleshooting

Prompt shows ContentDocument as record: no qualifying CDL; add a link to the target record and retry.
Assistant says to wait: text extraction not ready; rerun after Textract finishes.
Fields not visible in prompt: enable IncludeAllSObjectLabelsValues__c/IncludeAllSObjectMetadata__c on the agent; ensure the running user/ExecPolicy has access.
Agent doesn’t write back: confirm a DML-capable tool is active and permitted for the parent object; check RunContext (Background) if your tool choices differ.

Generated 2026-03-17T05:03:49.024417Z