Metadata-Version: 2.5
Name: AgentAssure-ai-agentforce
Version: 0.1.0
Summary: Salesforce Agentforce adapter for AgentAssure: Agent API sessions, SOQL state diffs, persona permissions, native test integration.
License: Proprietary
Requires-Python: >=3.11
Requires-Dist: agentassure-ai>=0.1.0
Requires-Dist: httpx>=0.27
Requires-Dist: pyjwt[crypto]>=2.9
Requires-Dist: pyyaml>=6
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# 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

```bash
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`:

```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`:

```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:

```bash
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

```python
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
```

```bash
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.
