Skip to main content

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

  1. In the Sandbox AI dashboard, open Agents, add your agent and create a key. Copy it: you only see it once.

  2. 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
    
  3. 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 as unauthorized, agent_paused, invalid_request, unknown_system or rate_limited. The SDK adds its own: missing_api_key, invalid_api_key, missing_base_url, invalid_base_url, timeout, network_error and unexpected_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 the Retry-After header, after rate_limited. None if the gateway didn't say.
  • details: the extra context the gateway sent, such as which fields failed an invalid_request. None if it sent none.
  • idempotency_key: the key to retry with, after propose_change failed in a way that may have left the change made. None otherwise.

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)

Source distribution for sandbox-ai-sdk 0.1.0
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)

Table of built distributions (wheels) for sandbox-ai-sdk 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files 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