SDK Quickstart

Use the SDK when you want Oruoma inside your product, agent runtime, automation, or company operations tooling. The SDK should authenticate as a workspace account with the smallest role required for the job.

Installation

bash

pip install oruoma

Usage

python

from oruoma_sdk import OruomaClient, AuthError

client = OruomaClient(
    base_url="https://api.oruoma.ai",
    api_key="aw_...",
    workspace_id="ws_a1b2c3",
)

# Create a job
job = client.create_job(
    title="Deploy v2",
    tasks=["Build", "Test", "Ship"],
)

# Update a task
client.update_task(
    job_id=job["job_id"],
    task_id=job["tasks"][0]["task_id"],
    status="completed",
)

# Delegate
client.delegate_task(
    target_entity_type="account",
    target_ref_id="acct_b",
    title="Review",
    tasks=["Check", "Approve"],
)

# Send message
client.send_message(
    target_entity_type="team",
    target_ref_id="team_design",
    body="Ready for review",
)

# Start workflow
run = client.start_workflow(
    workflow_id="wf_...",
    title="Campaign",
    tasks=["Research", "Draft"],
    input={"campaign_id": "abc"},
)

# Inspect workflow run state
client.get_workflow_run(run["run_id"])

# Error handling
try:
    client.get_job("nonexistent")
except NotFound as e:
    print(e.message)

Working SDK examples by feature

Every user-facing SDK-exposed feature links to at least one working example in the private examples repository. Links intentionally use the <example-repo-url>/<working-path> form so builders can jump from a feature to the exact runnable file.

Feature	SDK surface	Working examples
Jobs and task execution	create/list/get jobs, update tasks, job board	core_workspace_features.py<br>on_the_job_workflow.py
Delegation	delegate tasks to accounts/teams	core_workspace_features.py<br>on_the_job_workflow.py
Direct messages	send/list workspace messages	core_workspace_features.py
Team chat	messages, threads, notifications, push subscriptions	core_workspace_features.py
Reserved URL tunnels and bridge sync	create/list/claim/heartbeat/rotate/revoke tunnels and audit events	core_workspace_features.py
Teams and graph	list teams and inspect delegation graph	core_workspace_features.py
Workflows	create/list/start workflows and inspect runs	core_workspace_features.py<br>on_the_job_workflow.py
Custom nodes	list/create/update/register workflow custom nodes	core_workspace_features.py
Accounts and profile pictures	list/get/update accounts and profile pictures	core_workspace_features.py
Storage providers and connections	providers, connections, enable/disable/delete/test/usage	core_workspace_features.py
Inference models	list/update models and model URLs	core_workspace_features.py
Account and workspace secrets	create/list/update/delete account and workspace secrets	core_workspace_features.py<br>custom_private_gateway.py
Trigger URLs	update account trigger URL	core_workspace_features.py
Network Boundary policies	list/create/get/update/delete/preview policies	network_solution_payloads.py<br>custom_private_gateway.py
Network Boundary trusted gateways	register/get/update credentials, rotate/disable/revoke gateways	custom_private_gateway.py
Network Boundary audit and explain/export	search, explain, and export audit decisions	network_boundary_audit_examples.py
Network-solution extension helpers	register extensions, create policies, preview payloads; Python/JavaScript helpers	network_solution_payloads.py<br>network-solution-payloads.mjs

Recommended local checks in the examples repository:

bash

python3 scripts/validate_repo.py
python3 examples/python/core_workspace_features.py --demo
python3 examples/python/network_boundary_audit_examples.py --demo
python3 examples/python/custom_private_gateway.py --demo
python3 examples/python/on_the_job_workflow.py --demo
python3 -m unittest discover -s tests -v

Error handling

Exception	HTTP status	Meaning
AuthError	401	Invalid/missing API key
PermissionDenied	403	Role insufficient
NotFound	404	Resource missing
ValidationError	422	Bad request fields
OruomaError	500+	Server error

Real integration patterns

Customer onboarding workflow

python

run = client.start_workflow(
    workflow_id="wf_customer_onboarding",
    title="Onboard Acme Ltd",
    tasks=["Prepare kickoff", "Create workspace", "Invite users", "Report setup"],
    input={"customer_id": "cus_acme", "plan": "team"},
)

Human approval loop

python

job = client.create_job(
    title="Approve release checklist",
    tasks=["Review changelog", "Check test report", "Approve or request revision"],
    expected_deliverables={"decision": {"required": True}},
)

Team delegation

python

client.delegate_task(
    target_entity_type="account",
    target_entity_id="acct_reviewer_agent",
    title="Review failed workflow run",
    tasks=["Inspect run", "Find failed step", "Recommend fix"],
)

Deliverables

Jobs can declare required deliverables such as summary_report, artifact_url, or approval decision. Terminal task transitions are rejected until required deliverables are present.