Python SDK

PyPI

The Python SDK handles E2E encryption transparently -- content is encrypted before it leaves your process and decrypted only on the recipient's device. 

pip install hiloop

Quick start

agent.py 
from hiloop import HiloopClient

client = HiloopClient(
    api_key="hlp_xxx",
    agent_name="my-bot",
)

# Create a session and send a message
session = client.create_session(title="Deploy v2.4.1?")

client.send_message(session.id, components=[
    {"type": "text", "data": {"content": "Ready to deploy."}},
    {"type": "button_group", "data": {"buttons": [
        {"label": "Approve", "action": "approve", "variant": "primary"},
        {"label": "Reject", "action": "reject", "variant": "danger"},
    ]}},
])

# Wait for the human to respond
result = client.await_response(session.id)
print(f"Decision: {result.response}")

Examples

Preview

Approval flow

Gate dangerous actions behind human approval with rich context and action buttons.

agent.py 
from hiloop import HiloopClient

client = HiloopClient(
    api_key="hlp_xxx",
    agent_name="deploy-bot",
)

session = client.create_session(
    title="Deploy v2.4.1 to production?")

client.send_message(session.id, components=[
    {"type": "kv", "data": {"entries": [
        {"key": "Service", "value": "api-gateway"},
        {"key": "Version", "value": "2.4.1"},
        {"key": "Changes", "value": "12 features, 34 fixes"},
        {"key": "Author", "value": "ci-bot"},
    ]}},
    {"type": "button_group", "data": {"buttons": [
        {"label": "Approve", "action": "approve",
         "variant": "primary"},
        {"label": "Reject", "action": "reject",
         "variant": "danger"},
    ]}},
])

result = client.await_response(session.id)
if result.response == "approve":
    deploy()
Preview

Data report

Deliver structured reports with metrics, tables, and charts that humans can review at a glance.

agent.py 
client.send_message(session.id, components=[
    {"type": "metric_grid", "data": {"metrics": [
        {"label": "Revenue", "value": "$4.87M",
         "change": "+14%"},
        {"label": "New MRR", "value": "$312K",
         "change": "+8%"},
        {"label": "Churn", "value": "1.2%",
         "change": "-0.3%"},
    ]}},
    {"type": "table", "data": {
        "headers": ["Region", "Revenue", "Growth"],
        "rows": [
            ["North America", "$2.1M", "+18%"],
            ["Europe", "$1.8M", "+12%"],
            ["Asia Pacific", "$970K", "+9%"],
        ],
    }},
])
Preview

Form input

Collect structured data with radio buttons, checkboxes, and text fields -- all in one message.

agent.py 
client.send_message(session.id, components=[
    {"type": "qa", "data": {"questions": [
        {"id": "severity", "label": "Severity?",
         "type": "radio",
         "options": ["Critical", "High", "Medium",
                     "Low"]},
        {"id": "affected",
         "label": "Affected systems",
         "type": "checkbox",
         "options": ["API", "Dashboard", "Mobile",
                     "Database"]},
        {"id": "details", "label": "Description",
         "type": "textarea"},
    ]}},
])
Preview

Tabbed dashboard

Organize multi-section information in tabs -- perfect for dashboards, config panels, or detailed reports.

agent.py 
client.send_message(session.id, components=[
    {"type": "tabs", "children": [
        {"type": "tab", "data": {"label": "Overview"},
         "children": [
            {"type": "metric_grid", "data": {
                "metrics": [
                    {"label": "Uptime",
                     "value": "99.97%"},
                    {"label": "Latency",
                     "value": "45ms"},
                ]}},
        ]},
        {"type": "tab", "data": {"label": "Endpoints"},
         "children": [
            {"type": "table", "data": {
                "headers": ["Endpoint", "P50",
                            "P99"],
                "rows": [...]}},
        ]},
    ]},
])

Reading the timeline

Fetch all messages and responses in a session to see the full conversation history.

Python 
timeline = client.get_timeline(session.id)
for item in timeline.items:
    if item.kind == "message":
        print(f"[{item.sender_type}] {item.content}")
    if item.kind == "response":
        print(f"Response: {item.response}")

Webhooks

Webhooks are configured centrally via the admin panel (Admin > Webhooks), not per-agent. Each webhook covers a scope of spaces and agents. Events are automatically delivered to matching webhook endpoints.

To inspect deliveries for your agent:

Python 
deliveries = client.list_webhook_deliveries(limit=50)
stats = client.get_webhook_delivery_stats()

# Retry a failed delivery
client.retry_webhook_delivery(delivery_id="dlv_xxx")

Webhooks include Authorization: Bearer (your token) and X-Hiloop-Signature: sha256=<hmac> for verification.

Error handling

Python 
from hiloop import HiloopError

try:
    session = client.create_session(title="Deploy?")
except HiloopError as e:
    print(f"API error {e.status}: {e.message}")

See also