SDK Installation & Setup¶

The ARX SDK (agentvault-sdk) is a Python package that provides a governed interface to security tools through the ARX platform. This page covers installation, configuration, and initial connectivity verification.

Requirements¶

Python 3.11 or later
An ARX API key with deployer role or higher

Install¶

Install from PyPI:

pip install agentvault-sdk

The package installs the following dependencies automatically:

httpx -- Async HTTP client used for API communication
structlog -- Structured logging library

To install in an isolated virtual environment:

python -m venv .venv
source .venv/bin/activate
pip install agentvault-sdk

Environment Variables¶

The SDK reads two environment variables:

Variable	Required	Default	Description
`ARX_API_KEY`	Yes	None	Your ARX API key. Starts with `arx_sk_`.
`ARXSEC_API_URL`	No	`https://api.arxsec.io`	The ARX API base URL. Override for staging or self-hosted environments.

Set them in your shell:

export ARX_API_KEY="arx_sk_your_api_key_here"
export ARXSEC_API_URL="https://api.arxsec.io"

Or in a .env file loaded by your application framework. Do not commit API keys to version control.

ARXClient Constructor¶

The ARXClient class is the primary entry point. It accepts two optional parameters that override environment variables:

from agentvault import ARXClient

# Option 1: Read from environment variables (recommended)
client = ARXClient()

# Option 2: Pass values explicitly
client = ARXClient(
    api_key="arx_sk_your_api_key_here",
    api_url="https://api.arxsec.io",
)

Constructor parameters:

Parameter	Type	Default	Description
`api_key`	`str \\| None`	`os.environ["ARX_API_KEY"]`	API key for authentication. If not provided, read from the `ARX_API_KEY` environment variable.
`api_url`	`str \\| None`	`os.environ["ARXSEC_API_URL"]` or `https://api.arxsec.io`	API base URL. Trailing slashes are stripped automatically.

If api_key is not provided and the ARX_API_KEY environment variable is not set, the constructor raises a ValueError.

The client creates an httpx.AsyncClient internally with the following defaults:

Authorization: Bearer {api_key}
Content-Type: application/json
User-Agent: agentvault-sdk/0.1.0
Timeout: 60 seconds

Async Context Manager¶

ARXClient implements the async context manager protocol. Use async with to ensure the HTTP client is closed when the block exits:

import asyncio
from agentvault import ARXClient


async def main():
    async with ARXClient() as arx:
        cs = arx.crowdstrike()
        detections = await cs.get_detections(limit=10)
        print(detections)


asyncio.run(main())

If you cannot use async with, close the client manually:

arx = ARXClient()
try:
    cs = arx.crowdstrike()
    detections = await cs.get_detections(limit=10)
finally:
    await arx.close()

Failing to close the client may result in unclosed connection warnings from httpx.

Verify Connectivity¶

Run the following script to confirm that the SDK can reach the ARX API and that your API key is valid:

import asyncio
from agentvault import ARXClient


async def verify():
    async with ARXClient() as arx:
        # A simple operation to confirm connectivity.
        # If the API key is invalid, this raises an HTTP 401 error.
        cs = arx.crowdstrike()
        result = await cs.execute("detections:read", {"limit": 1})
        print("Connection verified. Response:", result)


asyncio.run(verify())

If the API key is invalid or expired, you will receive an httpx.HTTPStatusError with status code 401. If the ARXSEC_API_URL is unreachable, you will receive an httpx.ConnectError.

Session Context¶

The SDK automatically tracks operation history within a client session. Each execute() call appends the connector and operation to an internal session context list (capped at the last 100 actions). This context is sent with every request and used by the policy engine for behavioral analysis and drift detection.

A new ARXClient instance starts with an empty session context. If your agent runs across multiple sessions, each session has its own independent context.