SDK and Web Widget
Use this page when you want AION outside the Chat UI: from your own code, or as a chat bubble on a website. The SDKs (software development kits) are client libraries that wrap the AION API; the widget is a ready-made script you paste into a web page. This page is for developers and for the web team that embeds the widget.
The SDKs (Python and TypeScript) and the Web Widget are currently under active development. Some features may not be stable, undergo substantial interface changes, or not function correctly under all conditions. Use them with caution.
To facilitate the adoption of AION Agents in different ecosystems, official SDKs are available for Python and TypeScript, in addition to a "drop-in" widget for websites.
All clients authenticate with a personal API key created from chat-ui → Settings → API keys (the admin must enable the feature for the user). The key acts as its owner: any user_id passed by the client is ignored. See API keys.
Python SDK
The Python SDK allows for programmatic interaction with AION, ideal for backend automations or integrations into other Python services.
Installation
pip install ./sdk/python
Usage example
from aion_client import AionClient
client = AionClient(
base_url="https://aion.example.com",
api_key="aion_your_key_here"
)
# Start a conversation
conv = client.conversations.create(
profile="aion_std",
user_id="user_123"
)
# Chat in streaming
for event in client.chat.stream(conv.id, "Hello, how can you help me?"):
if event.type == "token":
print(event.content, end="", flush=True)
TypeScript / JavaScript SDK
Ideal for modern web applications (React, Vue, Node.js).
Installation
npm install ./sdk/typescript
Usage example
import { AionClient } from '@aion/client';
const client = new AionClient({
baseUrl: 'https://aion.example.com',
apiKey: 'aion_your_key_here'
});
const stream = client.chat.stream({
conversationId: '...',
message: 'Analyze the file report.csv'
});
for await (const event of stream) {
if (event.type === 'token') {
process.stdout.write(event.content);
}
}
Web Widget (Drop-in)
The widget allows you to add an AION chat to your website with a few lines of code.
Inclusion
<script src="https://aion.example.com/static/widget/aion-widget.js"></script>
<script>
AionWidget.init({
baseUrl: 'https://aion.example.com',
apiKey: 'aion_public_widget_key',
profile: 'aion_std',
user: { id: 'anonymous-user' },
theme: 'dark'
});
</script>
Widget Security
A key embedded in a public page is visible to anyone, and whoever holds it acts as the key's owner. When you expose a widget publicly, use a key that belongs to a dedicated (non-admin) user, grant only the chat scope (no conversations:* or files:*), and choose a short expiration. Revoke it from chat-ui → Settings → API keys if it leaks. See API keys.
Recommended patterns
- Error Handling: Both SDKs automatically handle exponential retries on transient errors (5xx, 429).
- Large files: The SDKs automatically detect if a file exceeds the direct upload threshold and autonomously switch to the Presigned PUT flow to ensure stability with large files.
- Cancellation: Use the
.stop()method of the SDK to send the interruption signal if the user closes the window or cancels the client-side operation.