Skip to main content

Arga Python SDK

Python client for Arga's Twin Runs, Saved Tests, browser Test Runs, Scenarios and Training APIs, with synchronous and asynchronous clients. Customer-side tracing and its Gmail/Stripe dependencies are included in the standard package.

Installation

pip install arga-py-sdk
# or
uv add arga-py-sdk

The examples below require v0.2.0 or later. During development, use pip install -e '.[dev]' from this checkout. Python 3.10 or later is required. Installing or importing the SDK does not enable tracing; collection starts only when explicitly configured in your application.

The default API URL is https://api.argalabs.com. The dashboard is https://app.argalabs.com. Pass base_url explicitly for another API environment.

Run a browser test

import os
from arga_sdk import Arga

with Arga(api_key=os.environ["ARGA_API_KEY"]) as client:
    run = client.test_runs.create(
        prompt="Sign in, open billing, and verify the checkout flow.",
        start_url="https://staging.example.com",
    )
    result = client.test_runs.wait(run.id, timeout=600)
    print(result.status, result.summary_text)

    # Save the recorded, editable TestConfig for reuse after inspecting it.
    if result.status == "completed" and result.test_config_json:
        test = client.tests.create("Checkout regression", run_id=result.id)
        rerun = client.tests.run(test.id, start_url="https://preview.example.com")

Test Runs execute browser flows against an already reachable application. Provision twins separately and configure your application with their endpoints before testing. The Test Run's twins, scenario_id, repository and PR fields record context; they do not deploy application code or automatically provision services.

Provision twins

with Arga(api_key=os.environ["ARGA_API_KEY"]) as client:
    run = client.twin_runs.create(
        ["gmail", "stripe"], ttl_minutes=60, public=False,
        scenario_prompt="A support mailbox with a duplicate payment needing review.",
        scenario_generation_mode="thorough",
    )
    status = client.twin_runs.wait(run.run_id)
    if status.status == "ready":
        stripe_url = status.twins["stripe"].base_url
        # Configure your application with returned endpoints and credentials.
    client.twin_runs.teardown(run.run_id)

Creating a Twin Run returns an accepted run_id; poll get or wait for state, progress, endpoints and any structured failure. wait returns terminal failures too, so inspect its status. Limits and access checks remain enforced by the backend. public=False requires the returned proxy credential when calling private surfaces.

Async usage

Every resource operation has the same interface on AsyncArga:

from arga_sdk import AsyncArga

async def check_release():
    async with AsyncArga(api_key=os.environ["ARGA_API_KEY"]) as client:
        run = await client.test_runs.create(
            "Verify checkout", start_url="https://staging.example.com",
        )
        return await client.test_runs.wait(run.id)

Current resource methods

Namespace Operations
client.twins list() retrieves the current twin catalog
client.twin_runs create, get, wait, extend, reset, lock, teardown, microsoft_scenario_snapshot
client.tests create, list, get, update, delete, run
client.test_runs create, list, get, rerun, update_config, send_message, artifact_url, wait
client.scenarios create, list, get, update, copy, delete, list_presets, get_preset, list_long_runs; existing environment methods
client.training create_upload_key, upload_evidence, list, get, generate_task, update_task, review_task, prepare_grader, get_grader, test_grader, create_environment, export_jsonl

List methods return Python lists, unwrapping the backend's Saved Test/Test Run response envelopes. tests.list(repo_full_name=...) filters by repository. scenarios.list supports twin, tag, scope, include_presets, search, limit and offset. Scenario creation supports personal/workspace scope and Fast/Thorough generation. Scenario environment creation also accepts github_actions_mode; Twin Runs additionally accept access_profile.

Updates preserve omitted fields and explicit nulls separately:

client.tests.update(test_id, description=None, repo_full_name=None, ci_enabled=False)
client.scenarios.update(scenario_id, description=None, tags=[])

artifact_url(run_id, filename) returns the backend's signed storage URL without forwarding the Arga credential to storage. Fetch that URL separately if needed. Run events are available in test_runs.get(run_id).events_json; the backend's browser WebSocket stream requires a session JWT and is not exposed as an API-key SSE stream. test_runs.list() currently returns the backend's latest 25 runs. Reset uses the backend's existing /validate/twins/provision/{id}/reset route; the other Twin Run lifecycle methods use /twin-runs.

The older client.runs.* and twin provision/status helpers remain available for compatibility. New integrations should use the current resource methods above. Historical custom-code/agent deployment is not a current SDK quickstart workflow.

Training review

Agent processes should hold a source-bound upload key and send locally filtered evidence. An authenticated control-plane client can then inspect and prepare tasks:

dataset = client.training.get(dataset_id)
task = client.training.generate_task(dataset.id, trace_id=dataset.traces[0]["id"])
grader = client.training.get_grader(dataset.id, task.id)
# Review the task, assumptions, starting state and grader before approving it.

Task edits and review calls require the current revision. Approval requires explicit assumption and grader acknowledgements. export_jsonl returns approved task records as the backend's JSONL text, preserving provenance and grader artifacts. Environment creation provisions reviewed Scenario twins; it does not host customer agents or train models. Upload-only credentials cannot perform these administrative operations. Generation can take several minutes; configure Arga(timeout=300) or AsyncArga(timeout=300) for task generation or Thorough scenario generation.

Examples and errors

Runnable workflows are in examples/README.md. Configure your application and credentials before running a live example; tests use mocked transports.

from arga_sdk import ArgaAPIError, ArgaError

try:
    result = client.test_runs.get(run_id)
except ArgaAPIError as error:
    print(error.status_code, error.message)

Customer-side tracing for Training

The v0.2 tracing module collects selected Gmail/Stripe evidence for Arga Training. Selection, identity aliases and text filtering run in your process. Provider API keys, headers, arbitrary metadata, model prompts/reasoning, raw MIME and attachments are not exported. Free text is disabled until you explicitly select fields.

Install the standard package, including tracing and the Gmail/Stripe client libraries:

pip install arga-py-sdk

This version must be released before that command installs v0.2. For development, install this checkout with pip install -e '.[dev]'.

Create a source-bound upload key once, outside your agent process, using a full Arga credential. Store the returned secret in your own secret manager as ARGA_TRACE_KEY:

import os
from arga_sdk import Arga

with Arga(api_key=os.environ["ARGA_API_KEY"], base_url="https://api.argalabs.com") as arga:
    credential = arga.training.create_upload_key(source="support-agent")
    upload_secret = credential.key.get_secret_value()  # Store securely; do not log.

Upload keys expire after 30 days, accept evidence only for their source, and cannot read datasets, generate tasks, approve tasks or provision environments. Rotating the account's legacy API key or revoking its sessions invalidates these upload keys. There is no individual upload-key revocation list in v1; use short operational rotation and the account-wide controls when needed.

Wrap your existing provider clients once, then wrap the agent entry point:

from arga_sdk.tracing import CapturePolicy, init

tracing = init(
    source="support-agent",
    # ARGA_TRACE_KEY is read from the environment. No provider credentials go to Arga.
    policy=CapturePolicy(
        text_fields=frozenset({"goal", "policy", "gmail.subject", "gmail.body"}),
        revision="support-v1",
        # Add transform_text=your_local_filter for names and proprietary content.
    ),
)
stripe_client = tracing.wrap_stripe(existing_stripe_client)
gmail_service = tracing.wrap_gmail(existing_gmail_service)
# Configure your existing agent to use these wrapped clients.

@tracing.agent(
    goal=lambda request: request["task"],
    policies=["Customer confirmations require the accountable owner's review before sending."],
)
async def handle(request):
    return await existing_agent.run(request)

# During graceful shutdown, after agent work finishes:
# await tracing.aflush(timeout=5)
# tracing.close()

The existing_* names represent your application objects. No global library patches, code scanning, framework prompt capture or extra provider requests occur. Only calls made through wrapped clients inside an active episode are observed. Sync Stripe calls, Stripe *_async methods, modern StripeClient.v1 services and legacy Stripe resources are supported. Gmail observes discovery-client requests when .execute() is called. Batch requests, implicit auto-pagination, streaming/generator lifetimes, other providers and arbitrary custom tools need additional adapters; do not assume these are captured. Use with tracing.episode(goal=..., policies=[...]): around generator consumption. Unknown executed operations and overlapping calls become explicit coverage gaps.

Selected text is still potentially sensitive business information. Built-in masking replaces recognized emails, Stripe IDs and common credential formats; it does not reliably detect people's names, every secret format, or proprietary facts. Supply a local transform_text callback or export only locally extracted task facts for stronger requirements. The callback runs before built-in masking and must not send raw data to Arga or another service without your authorization. Bump revision when its behavior changes. A filter exception drops the affected evidence and blocks generation.

For a completely local preview, set upload=False and inspect tracing.last_episode after a run, or episode.preview() inside an explicit episode. Preview does not send network requests. tracing.recent_uploads() returns bounded dataset receipts linking to /training/{dataset_id}. tracing.diagnostics() returns content-free queued, uploaded, dropped and failed counts. flush()/aflush() report queue drainage, not guaranteed upload success; check those counters. Export uses a bounded in-memory queue and makes up to three attempts for transient failures. There is no disk spool; exhausted retries, queue overflow and abrupt process termination can lose evidence. Shutdown does not delay the agent indefinitely. Call close() after flushing to release exporter resources.

Each completed episode becomes one private Training collection. Identical payloads deduplicate per owner; changed source evidence creates a separate immutable collection. Tasks remain drafts until reviewed, with the existing assumptions and grader acknowledgements. This prepares tasks, verifiers and twin environments; it does not execute customer agents or train models in Arga. Uploaded evidence is retained by the existing Training dataset storage and selected for Arga's configured generation model when you request generation; v1 adds no automatic evidence expiry or retention policy.

Braintrust sync in your infrastructure

Run the sync worker in your own Linux/macOS host or container. Both credentials stay there. Arga receives only the same arga.evidence.v1 projection used by the live SDK. The worker does not use Arga's older server-side Braintrust import endpoint.

Create a local trace-policy.json:

{
  "revision": "support-v1",
  "text_fields": ["goal", "policy", "gmail.subject", "gmail.body"],
  "goal_pointer": "/input/task",
  "policies": ["Customer confirmations require owner review before sending."],
  "operations": {
    "fetch_charge": "stripe.charges.retrieve",
    "issue_refund": "stripe.refunds.create",
    "read_message": "gmail.messages.get"
  }
}

The goal pointer selects a string from the root span; use /input if the root's input is already a task string. Only select the policy excerpts you intend to share. Mappings identify executed tool spans. Their input must contain provider arguments and output must contain a provider-shaped response. Canonical names such as stripe.charges.retrieve need no mapping. LLM/score/eval spans are ignored, including their tool-call suggestions. A wrapper that stores responses under another object must normalize those locally before using project_trace; v1 does not guess shapes.

With BRAINTRUST_API_KEY (project read access) and ARGA_TRACE_KEY set securely:

python -m arga_sdk.tracing sync \
  --source support-agent --project YOUR_BRAINTRUST_PROJECT_UUID \
  --state /var/lib/arga/braintrust-state.json \
  --since 2026-11-17T00:00:00+00:00 --policy ./trace-policy.json --watch

Without --watch, one window is processed. The watcher processes bounded five-minute windows, re-reads two minutes of overlap and waits 30 seconds when caught up. Complete span trees are retrieved even when children fall outside the root's window. Each query is capped at 2 MB/1,000 records; dense sources should use smaller windows through the BraintrustSync Python API. A missing parent, conflicting revision, repeated pagination cursor, invalid response or unacknowledged upload prevents checkpoint advancement. metrics.start/metrics.end must establish completed, non-overlapping tool calls; missing or ambiguous timing is uploaded as incomplete evidence and cannot generate tasks.

Unfinished roots stay in a bounded pending set and are revisited even after leaving the overlap window; their changing partial payloads are not uploaded. The checkpoint is atomically written with mode 0600 and locked against concurrent workers. It contains the local alias key, pending root references and acknowledgement hashes, not API keys or span payloads. Preserve it across restarts; protect it like other customer-local secrets. The cache is scoped to the source, project, policy, initial start and Arga destination/ account. A scoped-key renewal for the same account preserves compatibility. Use a new checkpoint when changing those settings. Late spans beyond the configured overlap require an intentional backfill; sync is not a lossless production audit log.

For custom local text filtering, instantiate BraintrustSync(policy=CapturePolicy(..., transform_text=your_filter), ...) in Python instead of the JSON-only CLI.

Evidence contract and coverage

The shared fixtures and JSON Schema are in tests/fixtures/. Gmail projections retain aliased message/thread identities, selected sender/recipient addresses, labels and dates; selected subject/plain-text body fields are opt-in. Stripe projections retain aliased customer/payment/charge/refund relationships, amounts, currency, status and relevant payment/refund state. Names, billing details, query strings, arbitrary request options, custom metadata, MIME and attachments are omitted. Aliases are consistent within an episode and cannot be reversed using data uploaded to Arga.

Limits are 100 KB/episode, 100 operations and 50 records/operation. Limits do not silently truncate critical evidence: coverage flags block task generation. complete applies to a selected resource or returned page, never the whole production account. Missing fields are unknown. Starting-state reconstruction remains partial, and generated assumptions require review. No automatic production snapshot or permission-grant enumeration is performed in v1; do not infer unobserved permissions from a successful call.

Documentation

Full API documentation is available at docs.argalabs.com.

The shared JSON Schema checks resource/provider agreement, resource-specific fields, and record types and labels. Runtime validation additionally requires contiguous event sequence numbers. Braintrust sync accepts concurrent reads; overlapping reads/writes remain a coverage gap because their starting state is ambiguous. Malformed trace trees stay in the private checkpoint for retry while healthy roots continue; coverage_gaps reports their count for the current window. Pending roots are bounded to 1,000.

Metadata

Release files for arga-py-sdk 0.2.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 arga-py-sdk 0.2.0
File Size Uploaded Provenance Actions
arga_py_sdk-0.2.0.tar.gz 150.1 kB With provenance Details for arga_py_sdk-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for arga-py-sdk 0.2.0
File Interpreter ABI Platform Actions
arga_py_sdk-0.2.0-py3-none-any.whl Python 3 none any Details for arga_py_sdk-0.2.0-py3-none-any.whl

Total release size: 194.5 kB

Release files / arga_py_sdk-0.2.0.tar.gz

Download URL arga_py_sdk-0.2.0.tar.gz
Size 150.1 kB
Tags Source
SHA-256 checksum
How to use checksums
d947fdde10e03da37a495c039599ca6a5886b65d2665fdf1003d52d0e993b4f2
BLAKE2b-256 checksum
How to use checksums
c0fb0d54ab1fde3aa58399082d6c5d98abe2ee90b368ba79ba265b03f59c49cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / arga_py_sdk-0.2.0-py3-none-any.whl

Download URL arga_py_sdk-0.2.0-py3-none-any.whl
Size 44.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7a8a2813e1e32ba8107e4604579995b3cee83d12377f3ed0352ea102318a6846
BLAKE2b-256 checksum
How to use checksums
a1a11866dfb6c9aaae99677a0f59d0e1b28b3a62d8c17bfe577c10f35d89f4fa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for arga-py-sdk 0.2.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for arga_py_sdk-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

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.

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