Sf Ai Agentforce Testing
Author and run Salesforce CLI Agent Script test specs for Agentforce bots, including conversationHistory setups that reach Apex and Flow actions past start_agent routing.
Overview
Sf-ai-agentforce-testing is an agent skill for the Ship phase that helps you write and run Salesforce CLI Agent Script test specs for Agentforce bots, including conversationHistory setups that actually exercise Apex and
Install
npx skills add https://github.com/jaganpro/sf-skills --skill sf-ai-agentforce-testingWhat is this skill?
- Agent Script two-level actions: topic.actions definitions vs reasoning.actions @actions invocations
- Documents single-utterance CLI limitation when start_agent burns the first reasoning cycle on go_<topic>
- conversationHistory pattern to pre-position the agent in-target topic before asserting Apex/Flow actions
- Template aligned with sf agent test create --spec and sf agent test run --wait --result-format json
- Points to five detailed Agent Script testing patterns in references/agentscript-testing-patterns.md
- Two-level Agent Script action system (definition topic.actions vs invocation reasoning.actions)
- Five detailed test patterns referenced in agentscript-testing-patterns.md
Adoption & trust: 1.1k installs on skills.sh; 418 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your Agentforce CLI tests pass topic routing but never hit the Apex or Flow actions because start_agent consumes the first reasoning cycle on multi-topic agents.
Who is it for?
Salesforce developers and solo builders validating Agent Script / Agentforce bots in scratch or staging orgs with the modern sf agent test CLI.
Skip if: Non-Salesforce agent projects, or teams that only need prompt-level LLM evals without BotDefinition subjectName bindings and org deployment.
When should I use this skill?
Creating or debugging Salesforce Agent Script CLI test specs when multi-topic routing blocks action assertions in single-utterance tests.
What do I get? / Deliverables
You get copy-ready YAML specs, create tests with sf agent test create, and run JSON-result validations that assert actions fire after the agent is already in the correct topic.
- Filled Agent Script test specification YAML for sf agent test create
- Documented conversationHistory pre-positioning for action-level assertions
- JSON test run results from sf agent test run
Recommended Skills
Journey fit
Agentforce validation belongs on the Ship → testing shelf because it executes formal agent test runs against org-bound BotDefinitions before customers touch the agent in production. Testing is the right subphase for YAML-driven sf agent test create/run workflows rather than initial Agent Script authoring in build integrations.
How it compares
Skill-delivered test-spec patterns for Salesforce Agent Script—not a generic Playwright or MCP browser testing server.
Common Questions / FAQ
Who is sf-ai-agentforce-testing for?
Developers shipping Salesforce Agentforce agents who use Agent Script bundles and need CLI-driven regression tests tied to BotDefinition developer names.
When should I use sf-ai-agentforce-testing?
During Ship testing after your .agent file exists—when you are creating specs with sf agent test create and running sf agent test run before launch or after action changes.
Is sf-ai-agentforce-testing safe to install?
Tests interact with your Salesforce org via CLI; treat credentials and org data carefully and review the Security Audits panel on this Prism page before install.
SKILL.md
READMESKILL.md - Sf Ai Agentforce Testing
# Agent Script Test Specification Template # Compatible with: sf agent test create --spec <file> --api-name <name> # # PURPOSE: Testing agents built with Agent Script (.agent files / AiAuthoringBundle). # # Agent Script agents use a TWO-LEVEL ACTION SYSTEM: # Level 1 (Definition): topic.actions block — defines actions with target: "apex://ClassName" # Level 2 (Invocation): reasoning.actions block — invokes via @actions.<name> # # KEY TESTING CHALLENGE: # Multi-topic Agent Script agents with start_agent routing burn the first # reasoning cycle on the topic transition (go_<topic>). The actual Apex/Flow # action fires in a SECOND cycle, which single-utterance CLI tests don't reach. # # SOLUTION: Use conversationHistory to pre-position the agent in the target topic, # then test the action directly — bypassing the start_agent routing step. # # Usage: # 1. Replace <placeholders> with actual values # 2. Create: sf agent test create --spec this-file.yaml --api-name <Test_Name> --target-org <alias> # 3. Run: sf agent test run --api-name <Test_Name> --wait 10 --result-format json --target-org <alias> # # See also: references/agentscript-testing-patterns.md for 5 detailed test patterns. # Required: Display name for the test (MasterLabel) name: "<Agent_Name> Agent Script Tests" # Required: Must be AGENT subjectType: AGENT # Required: Agent BotDefinition DeveloperName (same name as config.developer_name in .agent file) subjectName: <Agent_Name> testCases: # ═══════════════════════════════════════════════════════════════════ # PATTERN 1: ROUTING TESTS # Verify start_agent routes to the correct topic. # Single-utterance tests capture the TRANSITION action (go_<topic>), # NOT the business action (check_status, get_order, etc.). # ═══════════════════════════════════════════════════════════════════ - utterance: "<user message that should route to topic_1>" expectedTopic: <topic_1_name> # NOTE: For Agent Script, the expectedActions here is the TRANSITION action # from start_agent's reasoning.actions block, e.g., go_<topic_name>. # The Apex/Flow business action is NOT captured in single-utterance tests. expectedActions: - go_<topic_1_name> - utterance: "<alternative phrasing for topic 1>" expectedTopic: <topic_1_name> - utterance: "<user message that should route to topic_2>" expectedTopic: <topic_2_name> expectedActions: - go_<topic_2_name> # ═══════════════════════════════════════════════════════════════════ # PATTERN 2: ACTION TESTS (with conversationHistory) # Use conversationHistory to skip start_agent routing and test the # actual business action (apex://, flow://) directly. # # The conversationHistory pre-positions the agent in the target topic # so the test utterance triggers the action instead of a transition. # ═══════════════════════════════════════════════════════════════════ - utterance: "<user provides input needed by the action, e.g., 'Order ID is 12345'>" conversationHistory: - role: "user" message: "<initial message that triggered the topic routing>" - role: "agent" topic: "<topic_name>" message: "<agent greeting/prompt asking for the action input>" expectedTopic: <topic_name> expectedActions: - <action_definition_name> # Level 1 name from topic.actions block expectedOutcome: "<expected result, e.g., 'Agent retrieves and displays order details'>" # ═══════════════════════════════════════════════════════════════════ # PATTERN 3: ERROR HANDLING TESTS # Test how the agent handles invalid input or missing data. # ═══════════════════════════════════════════════════════════════════ - utterance: "<invalid input, e.g., 'Check order INVALID_ID'>" conversationHistory: - role: "user" message: "<initial message for topic>" - role: "agent" topic: "<topic_name>" message: "<agent prompt asking for input>" expectedTopic: