agentassure-agentforce
Test Salesforce Agentforce agents with AgentAssure (the agentassure package). Talk to an
agent through the Agent API as real test users, then check its replies, the records it changed in the org
and whether it respected each user's permissions.
Installing it next to agentassure registers everything; there is nothing to import:
| You get | Use it as |
|---|---|
| Agent API adapter | adapter: agentforce on an agent in agentassure.yaml |
| Org state provider | the sf fixture: create test records, run SOQL, diff org changes |
| Permission checker | expect(reply).respects_permissions(), checked per persona with UserRecordAccess |
| Native test runner | agentassure native run (Agentforce Testing Center) |
Install
pip install AgentAssure-ai AgentAssure-ai-agentforce
Requires Python 3.11+. The Salesforce CLI is not needed; everything goes through Salesforce's REST APIs.
Safe by design
- Production orgs are refused. The org type is checked on connect, and production stops the run
(exit code
10). Sandboxes, scratch, Developer Edition and trial orgs are allowed. - Test data is cleaned up. Records made with
sf.create(...)are deleted after each run. Setcleanup.agent_created: trueto also delete records the agent created. - No client secret. Sign-in uses the OAuth JWT bearer flow with an External Client App; the private key never leaves your machine or CI runner.
- One org only. Every signed-in user (admin, personas) must belong to the same org, so diffs and permission checks never read a different org from the one the agent runs in.
Configure
agentassure.yaml:
project: service-agents
agents:
service_agent:
adapter: agentforce
api_name: Customer_Service_Agent # BotDefinition.DeveloperName
watch: [Case, CaseComment, Task] # objects sf.watch() diffs by default
env/qa.yaml:
org:
instance_url: ${SF_QA_INSTANCE_URL}
jwt:
client_id: ${SF_QA_JWT_CLIENT_ID} # External Client App consumer key
private_key_path: ${SF_QA_JWT_KEY_PATH}
username: ${SF_QA_USERNAME} # the user AgentAssure signs in as
personas: # real test users, for permission checks
west_rep:
username: west.rep@acme.qa
context_variables:
$Context.EndUserLanguage: en_US
Then check the connection:
agentassure doctor --env qa # auth, org type, agent and active version, personas
Agent options (set on the agent in agentassure.yaml):
| Option | Meaning |
|---|---|
api_name |
the agent's API name; resolved to the org's agent ID and active version on each run |
session_user |
agent (default): conversations run as the agent's own user. persona: each conversation signs in as the persona's user, as for employee agents. |
evidence |
messages (default) or session_trace (beta): read tool calls and topics from Session Tracing |
context_variables |
session variables sent when a conversation starts |
Write a test
import agentassure as aa
@aa.test(agent="service_agent", personas=["west_rep"])
def test_escalation(agent: aa.Conversation, sf: aa.StateProvider, expect: aa.Expect):
case = sf.create("Case", Subject="Delayed order", Priority="Medium")
with sf.watch() as diff:
reply = agent.ask("Escalate case {n} to high priority", n=case.CaseNumber)
expect(reply).response_satisfies("Confirms the case is now high priority")
expect(reply).respects_permissions() # shows no records the persona can't read
expect(diff).record(case).changed_only(Priority="High")
expect(diff).no_unexpected_mutations() # nothing else in the org changed
agentassure test --env qa --agent service_agent -n 4
What the Agent API can and can't show
The Agent API returns the agent's messages, but not which topic it picked or which actions it called.
Checks that need those (routed_to, tool_called, ...) report missing evidence rather than passing.
To cover them:
- set
evidence: session_trace(beta) to read them from Session Tracing, or - run your existing Agentforce Testing Center tests with
agentassure native run --env qa --api-name <AiEvaluationDefinition>, which brings their results into the same reports and gates.
Modules
| Module | Purpose |
|---|---|
adapter |
Agent API sessions, preflight and doctor checks |
auth |
JWT bearer token flow (External Client App) |
client |
REST/SOQL client: pagination, CRUD, describe, server time, retries |
org |
shared org connection, API version, org classification, production guard, same-org check |
state |
SalesforceStateProvider: test records with cleanup, SOQL, snapshot and SystemModstamp diffs |
permissions |
persona record access through UserRecordAccess; Salesforce ID detection |
trace |
Session Trace (beta) parsing: OTLP spans to tool calls and topics per turn |
native |
agentassure native run (Testing API) |
Documentation
Setup step by step (External Client App, scopes, users, personas) is in the user guide under
docs/gitbook/getting-started/connect-salesforce.md in the source repository.
Author & Maintainer
Created and maintained by Prakash Narkhede:
- LinkedIn: prakashnarkhede89
- GitHub: @prakashnarkhede
Metadata
Release files for AgentAssure-ai-agentforce 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentassure_ai_agentforce-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for agentassure_ai_agentforce-0.1.1-py3-none-any.whl |
Release files / agentassure_ai_agentforce-0.1.1-py3-none-any.whl
| Download URL | agentassure_ai_agentforce-0.1.1-py3-none-any.whl |
|---|---|
| Size | 38.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2c673fddd69d1d83723a198f3d4dac1297857964f122d8a7db920737ade77f16
|
|
BLAKE2b-256 checksum How to use checksums |
e3ef873e412ca620d5aa0e40bf22e9c195210c0b5a97ba0e1c98db0f191ec6ee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for AgentAssure-ai-agentforce 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.