Skip to main content

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. Set cleanup.agent_created: true to 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:

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)

Table of built distributions (wheels) for AgentAssure-ai-agentforce 0.1.1
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page