Quick start (Python)

Install: pip install rai-control-plane-sdk. Requires Python 3.10 or newer and a RaiCentral / RAI Control Plane deployment with runtime agent credentials.

Minimal flow: construct RAIClient with base_url, api_key, and integration_id; call heartbeat(); start_session(); optionally observe_input(); call authorize_action() before any consequential side effect; execute only when decision.allowed is true; then report_execution(); finally session.end() and client.close().

Example:
from rai_sdk import RAIClient

client = RAIClient(
    base_url="https://rai.example.com",
    api_key="rai_...",
    integration_id="...",
)
client.heartbeat()
session = client.start_session(external_session_id="session-001", channel="application")
session.observe_input("Create an order")
decision = session.authorize_action(
    tool="create_order",
    parameters={"amount": 100, "currency": "USD"},
)
if decision.allowed:
    # Execute your application's business action here.
    decision.report_execution(client, status="SUCCEEDED")
session.end()
client.close()

Decisions: ALLOW means execute then report; DENY means do not execute; REQUIRE_APPROVAL means hold for a human and do not execute until approved; MONITOR is observability-oriented — only decision.allowed (ALLOW) means it is safe to perform a consequential side effect.

Fail-closed: with fail_closed=True (default), network errors and unreachable control-plane endpoints raise RAIError with code RAI_UNAVAILABLE. Do not execute consequential side effects when the plane is unavailable.

Full reference: https://github.com/ztechnium/rai-python-sdk