Akrion One Developer Docs

Overview

Akrion One is a multi-tenant autonomous AI assistant platform designed for APRA-regulated mid-tier Australian financial institutions. It provides specialist AI agents that handle customer queries, loan processing, and proactive notifications — all with strict tenant isolation and compliance controls.

Key Concepts

Quick Start

Get the Akrion One chat widget running on your test environment in three steps:

HTML<!-- Akrion One Chat Widget -->
<script
  src="https://cdn.akrion.one/widget/v1/akrion-widget.js"
  data-tenant-id="YOUR_TENANT_ID"
  data-api-key="YOUR_API_KEY"
  data-position="bottom-right"
  data-theme="auto"
></script>

JSON{
  "tenant_id": "coastal",
  "branding": {
    "primary_color": "#0891b2",
    "logo_url": "https://coastalcu.akrion.one/logo.svg",
    "welcome_message": "G'day! How can I help you today?",
    "agent_name": "Coastal Assistant"
  }
}

Architecture

Akrion One follows a PaaS-first, event-driven architecture on Microsoft Azure:

Chat Widget Integration (JS — Phase 1)

The Akrion One JS chat widget embeds directly into your existing web or mobile banking interface. It provides a fully branded AI assistant experience with minimal integration effort — a single <script> tag.

Script Tag (Simplest)

Drop a single script tag into your HTML. The widget auto-initialises with your tenant configuration:

HTML<!-- Place before </body> -->
<script
  src="https://cdn.akrion.one/widget/v1/akrion-widget.js"
  data-tenant-id="acme"
  data-api-key="ak_live_xxxxxxxxxxxx"
  data-position="bottom-right"
  data-theme="auto"
  data-lang="en-AU"
></script>

JavaScript SDK (Advanced)

For more control, use the JavaScript SDK to programmatically initialise and control the widget:

JavaScriptimport { AkrionWidget } from '@akrion-one/widget';

const widget = new AkrionWidget({
  tenantId: 'acme',
  apiKey: 'ak_live_xxxxxxxxxxxx',
  position: 'bottom-right',
  theme: 'dark',
  language: 'en-AU',
  customerContext: {
    customerId: 'CUST-001',
    segment: 'premium',
    authenticated: true
  },
  onReady: () => console.log('Akrion widget ready'),
  onMessage: (msg) => console.log('Agent response:', msg),
  onEscalation: (ticket) => {
    // Handle escalation — e.g., open your CRM
    console.log('Escalation raised:', ticket.id);
  }
});

// Programmatic control
widget.open();
widget.sendMessage('What is my account balance?');
widget.close();

React Component

React / TypeScriptimport { AkrionChat } from '@akrion-one/react';

export default function BankingApp() {
  return (
    <div className="app">
      {/* Your banking app content */}
      <AkrionChat
        tenantId="coastal"
        apiKey={process.env.REACT_APP_AKRION_KEY}
        position="bottom-right"
        theme="auto"
        welcomeMessage="G'day! How can I help you today?"
        onEscalation={(ticket) => {
          // Route to your escalation handler
          handleEscalation(ticket);
        }}
      />
    </div>
  );
}

Configuration Options

Web Component (<akrion-chat> — Phase 1.5)

The <akrion-chat> Web Component is the recommended integration for production banking portals, single-page apps, and any site with its own design system. It ships as a native HTML Custom Element with Shadow DOM encapsulation — the bank's CSS cannot break the widget, and the widget's CSS cannot affect the bank's page.

Quick Start

Load the ES module and drop the custom element into your page:

HTML<!-- Load the component definition -->
<script
  type="module"
  src="https://cdn.akrion.one/widget/v1.5/akrion-chat.js"
></script>

<!-- Place anywhere in your page -->
<akrion-chat
  tenant-id="coastal"
  api-url="https://akrion-apim.azure-api.net"
  position="bottom-right"
  theme="auto"
  locale="en-AU"
></akrion-chat>

Observed Attributes

All configuration is declarative via HTML attributes. Changes are applied reactively at runtime.

Event API (Custom Events)

The component emits CustomEvents that cross the Shadow DOM boundary (bubbles: true, composed: true). Listen to them on the element or any ancestor:

JavaScriptconst chat = document.querySelector('akrion-chat');

// Fired once the component has loaded tenant branding and is ready
chat.addEventListener('akrion:ready', () => {
  console.log('Akrion widget ready');
});

// Fired when the agent sends a message
chat.addEventListener('akrion:message', (e) => {
  console.log('Agent:', e.detail.text, 'from', e.detail.agent);
  analytics.track('ai_response', { agent: e.detail.agent });
});

// Fired when the agent escalates to a human
chat.addEventListener('akrion:escalation', (e) => {
  openSupportTicket({
    reason: e.detail.reason,
    priority: e.detail.priority
  });
});

// Fired on unrecoverable errors (network, backend, etc.)
chat.addEventListener('akrion:error', (e) => {
  errorReporting.log(e.detail);
});

Theming with CSS Custom Properties

Theme the widget purely from CSS — no JavaScript config required. Great fit for design-token systems.

CSS/* Bank's stylesheet — overrides widget appearance */
akrion-chat {
  --akrion-primary: #0891b2;
  --akrion-secondary: #6366f1;
  --akrion-accent: #f59e0b;
  --akrion-font: 'Inter', sans-serif;
  --akrion-bubble-size: 56px;
  --akrion-panel-width: 380px;
  --akrion-panel-height: 520px;
  --akrion-border-radius: 16px;
}

Advanced Styling with ::part()

For deeper customisation, the component exposes named parts that can be styled from outside the Shadow DOM:

CSSakrion-chat::part(bubble) {
  box-shadow: 0 8px 32px rgba(8, 145, 178, 0.4);
}

akrion-chat::part(panel) {
  border: 2px solid var(--brand-primary);
}

akrion-chat::part(header) {
  background: var(--brand-primary);
}

akrion-chat::part(send-button) {
  background: var(--brand-accent);
}

Content Projection via Slots

Banks can inject custom HTML into designated regions of the widget using named <slot> elements:

HTML<akrion-chat tenant-id="coastal" api-url="https://akrion-apim.azure-api.net">
  <!-- Replace default "Powered by Akrion One" footer -->
  <div slot="custom-footer">
    <img src="/coastal-logo.png" alt="Coastal CU" style="height: 20px;" />
    <span>Powered by Coastal CU AI</span>
  </div>

  <!-- Custom welcome message -->
  <div slot="welcome">
    <h3>G'day! 👋</h3>
    <p>I'm your Coastal CU assistant. Ask me about accounts, loans, or rates.</p>
  </div>
</akrion-chat>

Programmatic API

The Web Component exposes public methods and reactive properties on the element itself:

JavaScriptconst chat = document.querySelector('akrion-chat');

// Methods
chat.open();                              // Open the chat panel
chat.close();                             // Close the chat panel
chat.toggle();                            // Toggle open/close
chat.sendMessage('What is my balance?');  // Send message programmatically
chat.clearConversation();                 // Clear and start a new session
chat.setCustomer('coastal-cust-001');     // Set authenticated customer context

// Reactive properties (reflected to attributes)
chat.tenantId;       // 'coastal'
chat.apiUrl;         // 'https://akrion-apim.azure-api.net'
chat.isOpen;         // true / false
chat.isExpanded;     // true / false
chat.messageCount;   // 5

Using the Web Component in React

The Web Component works natively in React — just use the custom element tag. For idiomatic React usage, the Phase 2 @akrion-one/react package ships a thin wrapper that forwards refs and typed props:

React / TypeScript// Option 1 — direct custom element (works today)
export default function BankingApp() {
  return (
    <akrion-chat
      tenant-id="coastal"
      api-url={process.env.REACT_APP_AKRION_URL}
      position="bottom-right"
      theme="auto"
    />
  );
}

// Option 2 — React wrapper (Phase 2)
import { AkrionChat } from '@akrion-one/react';

export default function BankingApp() {
  const chatRef = useRef<HTMLElement>(null);

  useEffect(() => {
    chatRef.current?.addEventListener('akrion:escalation', handleEscalation);
  }, []);

  return (
    <AkrionChat
      ref={chatRef}
      tenantId="coastal"
      apiUrl={process.env.REACT_APP_AKRION_URL}
      theme="auto"
    />
  );
}

Migration from JS Widget

Banks already using the Phase 1 JS Widget can migrate incrementally — there's no breaking change. Both methods use the same backend APIs and tenant configuration.

HTML — Before (Phase 1 JS Widget)<script
  src="https://cdn.akrion.one/widget/v1/akrion-widget.js"
  data-tenant-id="coastal"
  data-api-url="https://akrion-apim.azure-api.net"
></script>

HTML — After (Phase 1.5 Web Component)<script
  type="module"
  src="https://cdn.akrion.one/widget/v1.5/akrion-chat.js"
></script>
<akrion-chat
  tenant-id="coastal"
  api-url="https://akrion-apim.azure-api.net"
></akrion-chat>

When to Choose Web Component vs JS Widget

See also: full Web Component technical design doc with reference implementation (~200 LOC), Shadow DOM structure, and comparison matrix.

Admin & Escalation Widget

The Akrion One Admin Widget provides bank staff with a dashboard for reviewing AI-assisted conversations, managing escalations, and monitoring agent performance. This is the future path to a fully embeddable admin widget that can be integrated into your existing back-office tools.

Admin Dashboard Features

• Conversation Review: View all AI-customer conversations with full audit trail and correlation IDs
• Escalation Queue: Human review queue for high-value transactions, edge cases, and customer complaints
• Agent Analytics: Resolution rates, response times, CSAT scores, and usage metrics per agent type
• Knowledge Base Management: Upload, update, and preview tenant knowledge documents
• Guardrail Configuration: Adjust agent confidence thresholds, escalation rules, and content safety settings

Embedding the Admin Widget (Phase 2)

When available, the admin widget will be embeddable via a similar script-tag approach:

HTML<!-- Akrion One Admin Widget (Phase 2) -->
<div id="akrion-admin"></div>
<script
  src="https://cdn.akrion.one/admin/v1/akrion-admin.js"
  data-tenant-id="YOUR_TENANT_ID"
  data-admin-token="YOUR_ADMIN_TOKEN"
  data-target="#akrion-admin"
  data-view="escalations"
></script>

Admin API Endpoints

API Reference

The Akrion One REST API is the foundation for all integrations. All requests require the X-Tenant-Id header and a valid API key.

Authentication

HTTPGET /api/v1/conversations
Host: api.akrion.one
Authorization: Bearer ak_live_xxxxxxxxxxxx
X-Tenant-Id: acme
Content-Type: application/json

Conversations

Knowledge Base

Agent Status

Tenant Setup

Onboarding a new bank or credit union to Akrion One involves four key steps:

Pythonfrom akrion.admin import TenantManager

manager = TenantManager(admin_key="ak_admin_xxx")
tenant = manager.create_tenant(
    tenant_id="newbank",
    display_name="New Bank Australia",
    region="australiaeast",
    core_banking_url="https://newbank-opentransact.akrion.one",
    branding={
        "primary_color": "#1a5276",
        "logo_url": "https://newbank.com.au/logo.svg"
    }
)

JSON{
  "tenant_id": "newbank",
  "core_banking": {
    "adapter": "opentransact",
    "base_url": "https://newbank-opentransact.akrion.one/api/v1",
    "auth": {
      "type": "managed_identity",
      "resource": "api://opentransact-newbank"
    }
  }
}

Bash# Upload all knowledge documents for a tenant
akrion-cli knowledge upload \
  --tenant-id newbank \
  --source ./content/newbank/ \
  --format markdown

Knowledge Base

Each tenant's knowledge base is a collection of Markdown documents indexed in Azure AI Search. Agents use RAG (Retrieval-Augmented Generation) to provide accurate, contextual answers grounded in the tenant's actual product and policy data.

Document Types

Escalation Workflows

Akrion One automatically escalates to human review when:

• A loan application exceeds $200,000 (configurable per tenant)
• Agent confidence score drops below the configured threshold (default: 70%)
• Customer explicitly requests to speak with a human
• Sensitive topics are detected (complaints, hardship, regulatory queries)
• Content safety guardrails are triggered

Escalation Flow

SequenceCustomer → Agent → Confidence check → Below threshold?
  ├── Yes → Create escalation ticket → Notify admin → Queue for human review
  └── No  → Deliver response to customer

Escalation Ticket includes:
  • Full conversation history
  • Agent reasoning trace
  • Confidence scores per turn
  • Suggested resolution (agent's best-effort response)
  • Customer context (ID, segment, risk profile)

Webhook Integration

Receive real-time escalation notifications via webhook to route into your existing CRM or ticketing system:

JSON{
  "event": "escalation.created",
  "tenant_id": "coastal",
  "escalation_id": "esc_20260415_001",
  "conversation_id": "conv_abc123",
  "reason": "loan_amount_exceeds_threshold",
  "priority": "high",
  "customer_id": "CUST-BH-001",
  "agent_type": "loan-processing",
  "suggested_action": "Review home loan application for $450,000",
  "created_at": "2026-04-15T14:30:00Z"
}

Security & Compliance

Security and compliance are foundational to Akrion One, not afterthoughts. Every design decision considers APRA CPS 234 requirements.

Agent Types

Akrion One ships with specialist agents across three phases:

MVP Agents (Available Now)

Phase 2 (Roadmap)

Configuration

Tenant configuration is managed via environment variables and the admin API:

Environment Variables# Required
AKRION_TENANT_ID=coastal
AKRION_API_KEY=ak_live_xxxxxxxxxxxx
CORE_BANKING_URL=https://coastal-opentransact.akrion.one/api/v1

# AI Configuration
FOUNDRY_PROJECT_ID=akrion-one-prod
FOUNDRY_AGENT_MODE=foundry_agent_service
AI_MODEL=gpt-5.1
EMBEDDING_MODEL=text-embedding-3-large
SEARCH_INDEX_PREFIX=knowledge

# Escalation Thresholds
ESCALATION_LOAN_THRESHOLD=200000
ESCALATION_CONFIDENCE_THRESHOLD=0.7

# Feature Flags
ENABLE_PROACTIVE_NOTIFICATIONS=true
ENABLE_INVESTMENT_ADVICE=false

Code Samples

Python — Send a Message

Pythonimport httpx

AKRION_API = "https://api.akrion.one/api/v1"
TENANT_ID = "acme"
API_KEY = "ak_live_xxxxxxxxxxxx"

# Start a conversation
resp = httpx.post(
    f"{AKRION_API}/conversations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "X-Tenant-Id": TENANT_ID,
    },
    json={"customer_id": "CUST-SC-001"}
)
conversation_id = resp.json()["conversation_id"]

# Send a message
resp = httpx.post(
    f"{AKRION_API}/conversations/{conversation_id}/messages",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "X-Tenant-Id": TENANT_ID,
    },
    json={"message": "What's my everyday account balance?"}
)

print(resp.json()["response"])
# → "Your Everyday Account (****4521) balance is $12,450.30 as of today."

JavaScript — Widget Events

JavaScript// Listen for widget events
window.addEventListener('akrion:ready', () => {
  console.log('Akrion One widget loaded');
});

window.addEventListener('akrion:message', (event) => {
  const { role, content, agentType } = event.detail;
  console.log(`[${agentType}] ${role}: ${content}`);
});

window.addEventListener('akrion:escalation', (event) => {
  const { escalationId, reason, priority } = event.detail;
  // Route to your CRM/ticketing system
  createSupportTicket({
    externalId: escalationId,
    reason: reason,
    priority: priority
  });
});

cURL — API Quick Test

Bash# Health check
curl -s https://api.akrion.one/api/v1/agents/health \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxx" \
  -H "X-Tenant-Id: acme" | jq .

# Start conversation and send message
CONV_ID=$(curl -s -X POST https://api.akrion.one/api/v1/conversations \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxx" \
  -H "X-Tenant-Id: acme" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "CUST-SC-001"}' | jq -r .conversation_id)

curl -s -X POST "https://api.akrion.one/api/v1/conversations/$CONV_ID/messages" \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxx" \
  -H "X-Tenant-Id: acme" \
  -H "Content-Type: application/json" \
  -d '{"message": "Show me my last 5 transactions"}' | jq .

LOS Gateway — Bank Integration

The Akrion LOS Gateway is the REST contract that a tenant bank exposes so that the Akrion One Loan Processing Agent can perform end-to-end loan origination on the bank's behalf — discovering products, running serviceability under the bank's own credit policy, creating applications, attaching documents, and capturing officer decisions.

What you'll build

A thin adapter (FastAPI / .NET / Spring) that terminates the Akrion contract, validates the Microsoft Entra-issued JWT, and translates each call into your existing LOS:

Federated identity at a glance

Each pilot bank gets its own Microsoft Entra app registration; a token minted for one bank cannot be replayed against another (HTTP 403 audience mismatch). This is the cryptographic tenant boundary required by APRA CPS 234 §35–36.

Bash# 1. Create your bank's app registration (one-off)
BANK="acme"
az ad app create \
  --display-name "OpenTransact (${BANK})" \
  --sign-in-audience AzureADMyOrg \
  --identifier-uris "api://opentransact-${BANK}"

# 2. Configure your gateway (env vars)
export AKRION_TENANT_ID="<Akrion's Entra tenant id>"
export OPENTRANSACT_EXPECTED_AUDIENCE="api://opentransact-${BANK}"
# Production must NEVER set OPENTRANSACT_AUTH_BYPASS

The 8 endpoints

Webhook callbacks (Phase 4)

Banks push application status changes back to Akrion (rather than Akrion polling). Mutual JWT auth (the bank's app calls Akrion's api://akrion-platform), HMAC-SHA256 body signature, idempotency key, 5-minute clock-skew tolerance. The full contract is in Developer Guide §5.

Need help onboarding (app registrations, role assignments, audience values)? Email contact@akrion.one.