Arga Python SDK

Typed Python client for the Arga API. Supports both synchronous and asynchronous usage.

Installation

Install with uv:

uv add arga-py-sdk

Or, if you're using pip:

pip install arga-py-sdk

Quick Start

from arga_sdk import Arga

client = Arga(api_key="arga_...")

# Create a URL run with service twins
run = client.runs.create_url_run(
    url="https://staging.myapp.com",
    twins=["stripe", "slack", "salesforce", "waterfall"],
)
print(run.run_id, run.status)

# Poll until the run completes
detail = client.runs.wait(run.run_id, timeout=300)
print(detail.status, detail.results_json)

# Stream live results
for event in client.runs.stream_results(run.run_id):
    print(event)

# Cancel a run
client.runs.cancel(run.run_id)

Async Usage

import asyncio
from arga_sdk import AsyncArga

async def main():
    client = AsyncArga(api_key="arga_...")

    run = await client.runs.create_url_run(url="https://staging.myapp.com")

    # Stream results
    async for event in client.runs.stream_results(run.run_id):
        print(event)

    # Wait for completion
    detail = await client.runs.wait(run.run_id)
    print(detail.status)

    await client.close()

asyncio.run(main())

Context Manager

Both clients support context managers to ensure proper cleanup:

with Arga(api_key="arga_...") as client:
    run = client.runs.create_url_run(url="https://staging.myapp.com")

async with AsyncArga(api_key="arga_...") as client:
    run = await client.runs.create_url_run(url="https://staging.myapp.com")

Examples

Runnable examples live in examples/. They are the best way to see realistic customer workflows end to end.

Before running any example, set your API key:

export ARGA_API_KEY=arga_your_api_key

If you need a non-default API environment, you can also set:

export ARGA_BASE_URL=https://app.argalabs.com

Start with the staging validation example:

uv run python examples/validate_staging_release.py

Each example is a small workflow script with an editable config block near the top of the file. Open the file, adjust the business-specific values, then run it with uv.

Choose an example based on the customer job you want to model:

• examples/validate_staging_release.py: validate staging before a release
• examples/create_checkout_scenario.py: create a reusable checkout scenario
• examples/ensure_scenario_twin_urls.py: ensure stable scenario twin URLs
• examples/provision_checkout_twins.py: provision disposable integrations like Stripe or Salesforce
• examples/explore_staging_with_agent.py: let Arga explore staging autonomously

See examples/README.md for exact commands, required edits, and expected output for each example.

Available Methods

Runs

Twins

Scenarios

Scenario generation modes

scenario = client.scenarios.create(
    name="Support escalation",
    prompt="A Slack support channel with linked escalation threads and consistent message authors",
    generation_mode="thorough",
)

Fast is the default for everyday scenarios. Thorough handles complex requirements with a longer wait. Explicit seed_config bypasses generation. Import ScenarioGenerationMode from arga_sdk for typed helpers.

Generate seed data from a prompt

result = client.twins.provision(
    twins=["slack"],
    scenario_prompt="A support channel with linked escalation threads and consistent message authors",
    scenario_generation_mode="thorough",
)
run_id = result["run_id"]

Use scenario_generation_mode="fast" for everyday scenarios, or omit it to use the server's Fast default. Thorough handles complex requirements with a longer wait. A scenario_id takes precedence and reuses saved seed data. These options work with both Arga and AsyncArga; await calls on the async client.

Error Handling

from arga_sdk import Arga, ArgaAPIError, ArgaError

client = Arga(api_key="arga_...")

try:
    run = client.runs.get("nonexistent-id")
except ArgaAPIError as e:
    print(e.status_code)  # e.g. 404
    print(e.message)
except ArgaError as e:
    print(e.message)

Documentation

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