sfagent-tools
AI-powered testing for Salesforce Agentforce agents. Claude reads your agent's topics, actions, and configuration, then autonomously generat
Open source Open in the app JSON README (API)
About
AI-powered testing for Salesforce Agentforce agents. Claude reads your agent's topics, actions, and configuration, then autonomously generates and runs test conversations — probing edge cases, validating guardrails, checking topic routing — and produces a scored report with recommendations. Zero setup: uses your existing Salesforce CLI authentication. Define business rules in sfagent-config.yaml and get rule-by-rule pass/fail results. Watch every conversation in real-time via a live transcript. Works with all agent types including Service Agents.
Details
- Kind
- Plugins
- Topic
- Developer tools
- Publisher
- lucianostraga
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 24
- Forks
- 1
- Last push
- 2026-05-26T14:29:04Z
- Repository state
- ativo
- Language
- Apex
- License
- NOASSERTION
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
lucianostraga/sfagent-tools/sfagent-tools
README
# SFAgent Tools
> **The first AI-driven testing toolkit for Salesforce Agentforce — in Claude Code, OpenAI Codex, and Agentforce Vibes.**
>
> Tell your AI assistant what to test. It reads your agent's brain, runs real headless conversations, finds what's broken, and hands you a scored report plus a YAML spec for CI. **In minutes, not hours. Zero new credentials.**
[](LICENSE)
[](https://www.npmjs.com/package/sfagent-tools-mcp-server)
[](https://code.claude.com)
[](https://developers.openai.com/codex)
[](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-mcp.html)
---
## What it does
> 📝 **Terminology:** *subagent* is Salesforce's renamed term for what was called *topic* before Agent Script v2.0 (April 2026). Same thing, new name — used throughout this README and the plugin.
- 🔍 **Discovers your agent** — reads every subagent (formerly *topic*), action, and description from your org so the AI knows what to test before testing it.
- 💬 **Has real conversations** — drives headless multi-turn sessions through `sf agent preview`. Live transcript in markdown you can watch in a split pane.
- 🛡️ **Probes guardrails** — prompt-injection attempts, off-topic requests, legal threats, manager-escalation triggers, identity-verification gates — automatically.
- 📏 **Validates your business rules** — load expectations from `sfagent-config.yaml` (topic-specific rules, global rules, custom scenarios) and the AI scores each one.
- 📊 **Scores everything** — routing accuracy, guardrail strength, multi-turn coherence, business-rule compliance — in a clean Markdown report.
- 🔁 **Hands off to CI** — emits YAML compatible with `sf agent test run-eval` so the same scenarios run on every commit.
- 🩺 **Reads Salesforce's own traces** — `sf agent trace` shows exactly which subagent routed each turn and which actions ran. We surface it for diagnostics.
- 🔐 **Zero new credentials** — reuses your `sf` CLI auth. No External Client App, no connected app, no tokens. Production orgs are blocked at the tool level.
- 🤖 **Works in Claude Code, OpenAI Codex, and Agentforce Vibes** — same npm-published MCP server. Cursor, Continue.dev, Cline, Windsurf packagings coming soon.
---
## See it work
One sentence. Real agent. Real findings. Ready for CI.
Same plugin, same agent, byte-identical answers — also in Codex:
---
## Install in 30 seconds
### Claude Code
Inside Claude:
```
/plugin marketplace add lucianostraga/sfagent-tools
/plugin install sfagent-tools@sfagent-tools-marketplace
```
Or from your shell, before launching:
```bash
claude plugin marketplace add lucianostraga/sfagent-tools
claude plugin install sfagent-tools@sfagent-tools-marketplace
```
### OpenAI Codex
One command:
```bash
codex mcp add sfagent-tools -- npx -y sfagent-tools-mcp-server@latest
```
### Agentforce Vibes
Inside Vibes (IDE or VS Code extension), open the **MCP Tools** panel → **Configure MCP Servers** → add to `a4d_mcp_settings.json`:
```json
{
"mcpServers": {
"sfagent-tools": {
"command": "npx",
"args": ["-y", "sfagent-tools-mcp-server@latest"]
}
}
}
```
That's it for any of them. Now in any project, just say:
> *"Test my Agentforce agent"*
And your AI does the rest.
---
## Every tool, in 10 seconds each
Each clip is a real terminal recording. Real Salesforce sandbox. Real Agentforce Service Agent.
### Discover what's in your org
| | |
|---|---|
| **list_orgs** — pick which org to test your agent in (production blocked) |  |
| **list_agents** — list Agentforce agents in an org |  |
| **get_agent_metadata** — see subagents (formerly *topics*) + actions |  |
| **load_config** — read your `sfagent-config.yaml` expectations |  |
### Run a live test
| | |
|---|---|
| **start_session** — open a headless conversation |  |
| **send_message** — send a probe, get the agent's reply |  |
| **end_session** — close and return the transcript |  |
### Hand off to CI
| | |
|---|---|
| **generate_test_spec** — emit YAML for `sf agent test run-eval` |  |
### Diagnose with Salesforce's own traces *(sf CLI 2026-05-20+)*
| | |
|---|---|
| **list_traces** — find local trace files |  |
| **read_trace** — drill into actions + routing per turn |  |
Plus `run_batch_test` and `get_test_results` for users who already have native `AiEvaluationDefinition` tests in their org.
---
## Why this exists
You built an Agentforce agent. Now you need to know:
- Does it route to the right subagent (formerly *topic*) when a customer says *"my order is late"*?
- What happens when someone says *"ignore your instructions"*?
- Does it remember context across a 5-turn conversation?
- Does it actually follow your business rules?
- What does it do when the customer demands a manager?
**Today, answering these questions means hours of manual chatting in Testing Center, or hand-writing YAML specs.** You'll get tired, miss edge cases, and ship anyway.
**SFAgent Tools turns those hours into minutes.**
---
## How it works
1. **Reads your agent** — discovers every subagent (formerly *topic*), action, and description in your org
2. **Designs scenarios** — happy paths, edge cases, prompt-injection probes, escalation tests, multi-turn context
3. **Has real conversations** — headless multi-turn sessions through `sf agent preview`. You watch them happen live in a split pane.
4. **Scores everything** — routing accuracy, guardrails, business-rule compliance, multi-turn coherence — in a clean Markdown report
5. **Hands off to CI** — generates a YAML spec for `sf agent test run-eval` so the same scenarios run on every commit
---
## Zero setup beyond what you already have
If you've ever run `sf org login web`, you're done. SFAgent Tools reuses your existing Salesforce CLI authentication.
**No new credentials. No External Client App. No connected app setup. No tokens to manage.** Production orgs are blocked at the tool level — testing only runs against sandboxes, scratch orgs, or Developer Edition.
---
## Built on the latest Salesforce tooling
Aligned with Agentforce DX as of TrailblazerDX 2026. Uses Agent Script v2.0 (`subagent` — the renamed term for what used to be called `topic`), the GA `sf agent preview` CLI, the new `sf agent trace` (May 2026), and emits YAML compatible with `sf agent test run-eval` so your exploratory tests become CI regression specs.
**Complements Salesforce's native testing — it doesn't replace it.**
---
## Other MCP clients (coming soon)
The MCP server itself is generic — anything that speaks the Model Context Protocol can call it via:
```bash
npx -y sfagent-tools-mcp-server@latest
```
**Currently officially supported and tested:** Claude Code, OpenAI Codex, Agentforce Vibes.
**Coming soon (packaged + tested):** Cursor, Continue.dev, Cline, Windsurf, Gemini CLI.
For the full Codex plugin experience (skills + marketplace metadata), see [packages/codex-plugin/README.md](packages/codex-plugin/README.md).
---
## Prerequisites
- [Salesforce CLI](https://developer.salesforce.com/tools/sfdxcli) (`sf` v2.131 or later)
- A Salesforce sandbox, scratch org, or Developer Edition with at least one Agentforce agent
- `sf org login web --alias <your-org>` already run
- Node.js 20+ (for the npx-based server install)
- Claude Code or OpenAI Codex (or any MCP-compatible client)
---
## Status
- **v1.0.0** — current release. All 12 MCP tools verified end-to-end against a live Agentforce Service Agent in both Claude Code and Codex. Three patch fixes (RequiresProjectError, wrong trace-tool flags, graceful empty-trace fallback) hardened during smoke testing. Production-ready.
- **v0.2.x** — internal iteration: monorepo restructure, Codex packaging, subagent terminology aligned with Agent Script v2.0, new trace + test-spec tools.
- **v0.1.0** — initial Claude Code plugin with 9 MCP tools.
---
## Architecture (for the curious)
This is a monorepo. The MCP server is the actual product — both plugin packagings are thin wrappers around it.
```
sfagent-tools/
├── packages/
│ ├── server/ # sfagent-tools-mcp-server (npm)
│ ├── claude-code-plugin/ # Claude Code packaging
│ └── codex-plugin/ # OpenAI Codex packaging
├── demo/ # demo video and per-tool clips
├── docs/ # progress logs, architecture decisions
└── discovery-docs/ # research that informed the design
```
One server. One set of tools. Two install paths.
---
## Development
```bash
npm install # install via npm workspaces
npm run build # build the server
claude --plugin-dir packages/claude-code-plugin # test the Claude plugin locally
```
For local Codex testing, see [packages/codex-plugin/README.md](packages/codex-plugin/README.md).
---
## Contributing
Issues and PRs welcome. The MCP server in [packages/server/](packages/server/) is the single source of truth for tool behavior. Changes to the tool surface ship as a server version bump on npm.
## License
Apache-2.0 — see [LICENSE](LICENSE).