Testing Agentforce
Author and run Salesforce Agentforce topic-routing test specs with the Salesforce CLI instead of hand-rolling invalid AiEvaluationDefinition YAML.
Overview
testing-agentforce is an agent skill for the Ship phase that helps you write Salesforce-cli-compatible Agentforce test YAML and run topic-routing checks against your agent.
Install
npx skills add https://github.com/forcedotcom/sf-skills --skill testing-agentforceWhat is this skill?
- Documents the exact @salesforce/agents YAML fields that deploy—explicitly excludes apiVersion, kind, metadata, and setti
- Includes ready-to-fill topic routing test cases with utterance and expectedTopic pairs
- Maps Testing Center "topic" API terms to Agent Script subagent blocks in .agent files
- Documents create and run flows: `sf agent test create` and `sf agent test run` with JSON result format
- Requires name, subjectType AGENT, and subjectName aligned to BotDefinition DeveloperName
- Template centers on topic routing test cases with utterance and expectedTopic pairs
- Documents three required top-level fields: name, subjectType AGENT, and subjectName
Adoption & trust: 661 installs on skills.sh; 513 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You changed Agent Script subagents but have no validated utterance-to-topic spec that the Salesforce agents test API will actually accept.
Who is it for?
Solo builders shipping custom Agentforce agents who already use `sf` against a dev or scratch org and want minimal structured routing tests.
Skip if: Teams testing only Apex, flows, or non-agent Einstein features, or anyone needing full conversational quality scoring beyond topic routing.
When should I use this skill?
You are creating or updating Agentforce agents and need a valid basic test spec for topic routing via Salesforce CLI.
What do I get? / Deliverables
You get a deployable basic-test-spec pattern and CLI commands so topic routing is exercised before users hit the wrong subagent in production.
- Filled basic-test-spec YAML for `sf agent test create`
- JSON results from `sf agent test run` documenting topic routing outcomes
Recommended Skills
Journey fit
Agent behavior verification belongs on the ship shelf because it gates release confidence for custom Agent Script topics and subagents. Testing subphase is where structured utterance-to-topic cases and `sf agent test run` fit the solo builder’s pre-deploy checklist.
How it compares
Use this YAML-plus-CLI template instead of copying generic AI evaluation YAML that Agentforce deploy will reject.
Common Questions / FAQ
Who is testing-agentforce for?
Salesforce-focused solo builders and small teams authoring Agent Script agents who need CLI-driven topic routing tests before release.
When should I use testing-agentforce?
Use it in Ship/testing when you add or rename subagents, during Build/agent-tooling while iterating on .agent files, and before launch prep whenever routing regressions would break user journeys.
Is testing-agentforce safe to install?
It is a documentation and template skill; review the Security Audits panel on this Prism page and treat org credentials and `sf` access as sensitive when running tests.
SKILL.md
READMESKILL.md - Testing Agentforce
# Basic Test Specification Template # Compatible with: sf agent test create --spec <file> --api-name <name> # # Usage: # 1. Replace <placeholders> with actual values # 2. Create: sf agent test create --spec basic-test-spec.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> # # IMPORTANT: This YAML is parsed by @salesforce/agents — NOT a generic AiEvaluationDefinition format. # Only the fields below are recognized. Do NOT add apiVersion, kind, metadata, or settings. # # NOTE: The Testing Center API uses "topic" terminology. In Agent Script, topics are called # "subagents" (e.g., the `subagent` block). When writing tests, use "topic" to match the API, # but understand that each expectedTopic value maps to a subagent in your .agent file. # Required: Display name for the test (MasterLabel) — deploy FAILS without this name: "<Agent_Name> Basic Tests" # Required: Must be AGENT subjectType: AGENT # Required: Agent BotDefinition DeveloperName (API name) subjectName: <Agent_Name> testCases: # ═══════════════════════════════════════════════════════════════ # TOPIC ROUTING TESTS # Test that user messages route to the correct topic # ═══════════════════════════════════════════════════════════════ - utterance: "<User message that should trigger primary topic>" expectedTopic: <topic_name> - utterance: "<User message that should trigger secondary topic>" expectedTopic: <another_topic_name> # ═══════════════════════════════════════════════════════════════ # ACTION INVOCATION TESTS # expectedActions is a FLAT list of action name strings # ═══════════════════════════════════════════════════════════════ - utterance: "<User message that should trigger action>" expectedTopic: <topic_name> expectedActions: - <action_name> # ═══════════════════════════════════════════════════════════════ # OUTCOME VALIDATION TESTS # expectedOutcome is optional — omitting causes harmless ERROR # in output_validation (test still passes topic/action checks) # ═══════════════════════════════════════════════════════════════ - utterance: "<User message with expected outcome>" expectedTopic: <topic_name> expectedOutcome: "Agent should provide a helpful response about <topic>" # ═══════════════════════════════════════════════════════════════ # ESCALATION TEST # Standard topics like Escalation use localDeveloperName # ═══════════════════════════════════════════════════════════════ - utterance: "I want to talk to a real person" expectedTopic: Escalation # Guardrail and Boundary Test Specification Template # Compatible with: sf agent test create --spec <file> --api-name <name> # # Patterns covered: # 1. Standard platform topics — Inappropriate_Content, Prompt_Injection, Reverse_Engineering # 2. Off-topic deflection — agent should redirect gracefully # 3. Session management — agent should never prematurely end sessions # 4. Auth gate verification (if applicable) — business intents must route to auth first # # Usage: # 1. Replace <placeholders> with actual values # 2. Deploy: sf agent test create --spec guardrail-test-spec.yaml --api-name Guardrail_Tests --target-org <alias> # 3. Run: sf agent test run --api-name Guardrail_Tests --wait 10 --result-format json --target-org <alias> # # NOTE: The Testing Center API uses "topic" terminology. In Agent Script, topics are called # "subagents" (e.g., the `subagent` block). When writing tests, use "topic" to match the API, # but understand that each expectedTopic value maps to a subagent in your .agent file. name: "<Agent_Name> Guardrail Tests" subjectType: AGENT subjectName: <Agent_Name> testCases: # ═══════════════════════════════════════════════════════════════ # STANDARD PLATFORM TOPIC TESTS # These platform-level topics intercept BEFORE custom planner # routing. The custom planner never sees the utterance.