sandbox-ai-sdk
The Python client for Sandbox AI. An agent proposes a change to a record in a business system, such as Salesforce or ServiceNow, and gets back what Sandbox AI decided for each field: applied, held for a person's approval, or blocked by a rule. Built on httpx and Pydantic. Python 3.11 and later.
Alpha. This is an early release, and the API may change before 1.0. It needs access to a Sandbox AI gateway: an agent key and the gateway's address.
Install
pip install sandbox-ai-sdk
Or uv add sandbox-ai-sdk. The import is sandbox_ai.
Quick start
-
In the Sandbox AI dashboard, open Agents, add your agent and create a key. Copy it: you only see it once.
-
Give the client the key and your gateway's address, as arguments or as environment variables. Both are required:
export SANDBOX_AI_API_KEY=sbx_... export SANDBOX_AI_BASE_URL=https://your-gateway.example.com -
Propose a change:
from sandbox_ai import Client
client = Client() # reads SANDBOX_AI_API_KEY and SANDBOX_AI_BASE_URL
# or: Client(api_key="sbx_...", base_url="https://your-gateway.example.com")
decision = client.propose_change(
"salesforce", # system
"account", # object
"001-SAMPLE-0142", # record_id: None to create a record
{"OwnerId": "005-SAMPLE-MARCUS"},
reason="Customer asked to work with Marcus", # shown to approvers
)
if decision.status == "needs_approval":
# A person decides. Check again later.
decision = client.get_decision(decision.change_id)
The key identifies the agent, so there's no agent id to pass. Use the client as a context manager (with Client(...) as client:) or call client.close() when done.
What the status means
decision.status |
What happened | What the agent should do |
|---|---|---|
applied |
Every field was written and confirmed | Carry on |
needs_approval |
A rule sent it to a person | Call get_decision later |
partially_applied |
Some fields were written. The rest were blocked by rules, declined by the approver, or not decided in time | Check decision.fields, and decision.approval.comment for what the approver said |
blocked, rejected, expired |
Nothing was written | Read decision.message or field.message for why |
conflict |
The record changed since Sandbox AI read it | Read the record again, then propose again |
error |
The system refused the change | Read field.message |
observed |
The connection is watch-only, so nothing was written | Keep writing through your existing path |
Each item in decision.fields has the field, before, after, the outcome (allow, needs_approval or blocked), the rule_ids that decided it, and whether it was written.
decision.message and decision.rule_ids say why for the change as a whole. A delete has no fields and is always blocked, in watch-only too, so those two are always set for one.
Errors
Everything raises SandboxAIError, with:
code: the API's error code, such asunauthorized,agent_paused,invalid_request,unknown_systemorrate_limited. The SDK adds its own:missing_api_key,invalid_api_key,missing_base_url,invalid_base_url,timeout,network_errorandunexpected_response.message: plain words, safe to show to people and to agents.status: the HTTP status, when there was one.retry_after: whole seconds to wait, from theRetry-Afterheader, afterrate_limited.Noneif the gateway didn't say.details: the extra context the gateway sent, such as which fields failed aninvalid_request.Noneif it sent none.idempotency_key: the key to retry with, afterpropose_changefailed in a way that may have left the change made.Noneotherwise.
Retrying a change safely
Every propose_change call sends an idempotency key: yours, or one the SDK makes. If the call times out waiting for an answer, the connection drops after sending, or the gateway answers with a 5xx or something the SDK can't read, the change may already have been made. Retry with the key from the error, within 24 hours, and the gateway returns the first decision instead of making the change twice:
from sandbox_ai import Client, SandboxAIError
client = Client()
try:
decision = client.propose_change("salesforce", "account", None, {"Name": "Acme"})
except SandboxAIError as error:
if not error.idempotency_key:
raise
decision = client.propose_change(
"salesforce", "account", None, {"Name": "Acme"}, idempotency_key=error.idempotency_key
)
The error's message names the key too, so it's there for an agent reading the text. If the connection never opened, such as a refused connection, a connection that timed out before it opened, or a wrong address, nothing was sent: idempotency_key is None and the message says to check the address. A 4xx means the gateway refused the request, so it's None then too.
Keys belong to the API key that sent them, so another agent's key never matches yours. get_decision only reads, so after a timeout there's no key to think about: just call it again.
The API key never appears in errors, logs or repr(client).
Settings
| Argument | Environment variable | Default |
|---|---|---|
api_key |
SANDBOX_AI_API_KEY |
required |
base_url |
SANDBOX_AI_BASE_URL |
required: the address of your Sandbox AI gateway |
timeout |
10 seconds |
A blank or whitespace-only api_key or base_url argument counts as not given, so the client falls back to SANDBOX_AI_API_KEY or SANDBOX_AI_BASE_URL.
License
Apache-2.0. The full license text is in the LICENSE file included in the package.
Metadata
Release files for sandbox-ai-sdk 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sandbox_ai_sdk-0.1.0.tar.gz | 12.2 kB | Without provenance | Details for sandbox_ai_sdk-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sandbox_ai_sdk-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for sandbox_ai_sdk-0.1.0-py3-none-any.whl |
Total release size: 26.7 kB
Release files / sandbox_ai_sdk-0.1.0.tar.gz
| Download URL | sandbox_ai_sdk-0.1.0.tar.gz |
|---|---|
| Size | 12.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0d2747a3619e701d0d6bf5ee5a4f638cc943853f32d6cd34734c1383e522c10d
|
|
BLAKE2b-256 checksum How to use checksums |
3193cdf4cf61ab3f2e9ef6e4263236091bcae142748a2120884a6f86ee194f72
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / sandbox_ai_sdk-0.1.0-py3-none-any.whl
| Download URL | sandbox_ai_sdk-0.1.0-py3-none-any.whl |
|---|---|
| Size | 14.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3378b2f02f63468567b6998246913313a2b8e156ae969ea8f64c170461c0a16d
|
|
BLAKE2b-256 checksum How to use checksums |
26b95f67f6dfc982e4553afebbba81fa64a618320fef138a7d6e9274d4cfe6e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for sandbox-ai-sdk 0.1.0
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.