Server SDKs for Node.js and Python

Node.js and TypeScript (available (v0.1))

Create an API key in Dashboard > Settings > API keys and store it as OCTADEZX_API_KEY. The SDK refuses to run in a browser, requires HTTPS outside localhost and never follows redirects with the key.

A conversation

import { OctaDezx, OctaDezxApiError } from "@octadezx/sdk";

const client = new OctaDezx({ apiKey: process.env.OCTADEZX_API_KEY! });

const turn = await client.agent.start({
  message: "Where is my order 1001?",
  user: { id: "u_123", email: "jo@example.com", name: "Jo" },
});
if (turn.status === "handed_off") notifyUser("A teammate will reply here soon.");

const next = await client.agent.reply({ conversationId: turn.conversationId, message: "Thanks!" });

Streaming

for await (const event of client.agent.stream({ conversationId, message: "And on Sunday?" })) {
  if (event.type === "status") showTyping(event.data.state);
  if (event.type === "delta") append(event.data.text);
  if (event.type === "done") finish(event.data);
}

Errors

try {
  await client.agent.reply({ conversationId, message });
} catch (e) {
  if (e instanceof OctaDezxApiError) {
    console.log(e.status, e.code, e.retryAfterSeconds, e.messageAccepted);
  }
}

Python (early access)

OctaDezxApiError carries status, code, retry_after_seconds, conversation_id and message_accepted. GETs retry 502, 503 and 504; turns never retry. Pass transport= to use another HTTP stack such as httpx.

Sync

import os
from octadezx import OctaDezx, OctaDezxApiError

client = OctaDezx(os.environ["OCTADEZX_API_KEY"])

turn = client.agent_start(
    "Where is my order 1001?",
    user={"id": "u_123", "email": "jo@example.com", "name": "Jo"},
)
print(turn["status"], turn["reply"])

for event in client.agent_stream("And on Sunday?", conversation_id=turn["conversationId"]):
    if event.type == "delta":
        print(event.data["text"], end="", flush=True)

Async

import asyncio
from octadezx import AsyncOctaDezx

async def main():
    client = AsyncOctaDezx(os.environ["OCTADEZX_API_KEY"])
    turn = await client.agent_start("Hello")
    async for event in client.agent_stream("And you?", conversation_id=turn["conversationId"]):
        ...

asyncio.run(main())

The Python SDK is available for early access. It is built and tested but not on PyPI yet; it is coming to PyPI. Until then, contact us and we will send the package and the setup steps. Contact us for early access (kevin@octadezx.com).

User tokens, webhooks and devices

Node.js

import { signUserToken, verifyWebhookEvent } from "@octadezx/sdk";

res.json({ token: signUserToken(req.user.id, process.env.OCTADEZX_IDENTITY_SECRET!, { ttlSeconds: 3600, email: req.user.email }) });

const event = verifyWebhookEvent(rawBody, headers, process.env.OCTADEZX_WEBHOOK_SECRET!);
await client.registerDevice({ userId: "u_123", token: fcmToken, platform: "android" });

Python

from octadezx import sign_user_token, verify_webhook_event

token_for_page = sign_user_token(user.id, os.environ["OCTADEZX_IDENTITY_SECRET"], ttl_seconds=3600)
event = verify_webhook_event(request.body, request.headers, os.environ["OCTADEZX_WEBHOOK_SECRET"])
client.register_device("u_123", fcm_token, "android", app_id="com.yourapp")

Google ADK adapter (available (v0.1))

@octadezx/adk exposes a bound-conversation read tool and a human-approved customer-message tool to Google ADK agents. It is published on npm at version 0.1.0 under the MIT license, with @octadezx/sdk as a peer dependency.

Install

@octadezx/sdk (available, v0.1.0, MIT license)

Server SDK for Node.js 20 and newer: Agent API with streaming, signed user tokens, webhook verification and devices.

npm install @octadezx/sdk

@octadezx/sdk on npm

@octadezx/adk (available, v0.1.0, MIT license)

Google ADK adapter for the OctaDezx conversation API.

npm install @octadezx/adk @octadezx/sdk

Peer dependency: @octadezx/sdk. See the package README for the Google ADK version it is pinned to.

@octadezx/adk on npm

Questions or a larger rollout? Contact us (kevin@octadezx.com).