Python

Integrate aelio-sdk with Python backends — FastAPI, Django, and async frameworks.

The official Python SDK (aelio-sdk) provides the same wire protocol and API surface as the Node.js SDK.

Install

pip install aelio-sdk
pip install websockets>=12.0

Requires Python ≥ 3.9.

Quick integration

import os
from aelio_sdk import Aelio

aelio = Aelio(
    secret=os.environ["AELIO_SDK_SECRET"],
    url="ws://127.0.0.1:3010"
)

@aelio.expose("getOrderStatus", description="Get order status", params={"orderId": "string"}, safety="read")
async def get_order_status(args, ctx):
    return {"status": "shipped", "customerId": ctx["customerId"]}

aelio.run()

Guides in this section

Guide	Framework	Example
FastAPI	FastAPI + uvicorn	`examples/python-fastapi/`
Django	Django	`examples/python-django/` (stub)

API parity with Node.js SDK

Python	Node.js	Purpose
`aelio.expose()`	`aelio.expose()`	Register tool
`aelio.persona()`	`aelio.persona()`	Assistant tone
`aelio.describe()`	`aelio.describe()`	Product description
`aelio.state()`	`aelio.state()`	Lifecycle state
`aelio.policy()`	`aelio.policy()`	Conversation policy
`aelio.flow()`	`aelio.flow()`	Guided flow
`aelio.on_send()`	`aelio.onSend()`	BYO channel delivery
`aelio.ingest()`	`aelio.ingest()`	Push inbound message
`aelio.set_customer_state()`	`aelio.setCustomerState()`	Push lifecycle state
`aelio.listen()` / `aelio.run()`	`aelio.listen()`	Connect to server

Handler signature

async def handler(args: dict, ctx: dict) -> any:
    # args — tool parameters from LLM
    # ctx — { customerId, sessionId, channel, channelAddress, locale?, metadata? }
    return {"result": "data"}

Environment variables

AELIO_SDK_SECRET=change-me-in-production
AELIO_SERVER_URL=ws://127.0.0.1:3010

SDK source

The Python SDK is a single ~330 line file: sdk/python/sdk.py. Use it as a reference for implementing the wire protocol in other languages.