AI client

Azion Lib functions of the azion/ai module that send questions about Azion to the Azion AI API and return the answer whole or as a stream.

Last updated

View as Markdown Agent setup

The azion/ai module of the azion package is the Azion Lib client for the Azion AI API, an assistant that answers questions about Azion products and services. You send it a conversation, and it returns the answer in one piece with chat or in chunks, as the model writes it, with streamChat.

Install the package:

npm install azion

The azion package receives bug fixes only, and its maintenance ends in December 2026.

Every sample on this page is a TypeScript ES module that runs in Node.js and uses top-level await. Types come in through import type, so the samples still load when a tool strips the type annotations before running them.

Authentication

The chat and streamChat functions take your personal token from the AZION_TOKEN environment variable. A client from createClient holds its own token, passed in the token field.

A .env file with both variables looks like this:

Shell
01AZION_TOKEN=[TOKEN VALUE]
02AZION_DEBUG=true
VariableDescription
AZION_TOKENYour Azion personal token.
AZION_DEBUGWith true, chat prints the whole response object before the answer, and streamChat prints every chunk object.

For how the Azion Lib packages resolve the token and the debug setting, refer to How Azion Lib works.

Response envelope

Every call returns an AzionAIResult object, { data, error }. On success, data holds the response and error is null. On failure, data is null and error is a JavaScript Error. A refused call does not throw.

Read the failure from error.message. The message property of an Error is not enumerable, so JSON.stringify(error) prints {} and hides the reason.

createClient

Creates a client that holds a token and request options and exposes chat and streamChat as methods. createClient is also the default export of azion/ai.

TypeScript
01function createClient(config?: Partial<{
02 token: string;
03 options?: AzionClientOptions;
04}>): AzionAIClient;
ParameterTypeRequiredDescription
tokenstringNoYour Azion personal token.
optionsAzionClientOptionsNoRequest options for every call the client makes.

Returns an AzionAIClient. Its methods take the same arguments as the chat and streamChat functions.

This sample creates a client and asks it one question:

TypeScript
01import { createClient } from 'azion/ai';
02import type { AzionAIClient } from 'azion/ai';
03
04const client: AzionAIClient = createClient({
05 token: process.env.AZION_TOKEN, // Replace with your actual token
06 options: {
07 // Add any additional options here
08 },
09});
10
11const { data, error } = await client.chat({ messages: [{ role: 'user', content: 'What is Azion Object Storage? One sentence.' }] });
12console.log(data ? data.choices[0].message.content : error);

The model writes a different answer on every run. This output is cut after the answer, before the list of documentation pages:

Text
01Azion Object Storage is a globally distributed, S3-compatible storage solution that organizes data into buckets, supports granular permissions, and integrates seamlessly with Azion's Edge Network for efficient data management and processing.
02…

chat

Sends a conversation to the Azion AI API and returns the whole answer when the model finishes it. The function takes two positional arguments, not one object.

TypeScript
01function chat(
02 request: AzionAIRequest,
03 options?: AzionClientOptions,
04): Promise<AzionAIResult<AzionAIResponse>>;
ParameterTypeRequiredDescription
requestAzionAIRequestYesThe conversation to send.
optionsAzionClientOptionsNoRequest options.

Returns data as an AzionAIResponse. The answer is in choices[0].message.content.

TypeScript
01import { chat } from 'azion/ai';
02import type { AzionAIRequest, AzionAIResponse, AzionAIResult } from 'azion/ai';
03
04const request: AzionAIRequest = {
05 messages: [{ role: 'user', content: 'Explain what the Azion Web Platform is.' }],
06};
07const { data: response, error }: AzionAIResult<AzionAIResponse> = await chat(request, { debug: false });
08if (response) {
09 console.log('AI response:', response.choices[0].message.content);
10} else {
11 console.error('Chat failed', error);
12}

On success, the sample prints AI response: followed by the answer.

streamChat

Sends a conversation to the Azion AI API and yields the answer in chunks while the model writes it. Use it to show the answer as it arrives.

TypeScript
01function streamChat(
02 request: AzionAIRequest,
03 options?: AzionClientOptions,
04): AsyncGenerator<AzionAIResult<AzionAIStreamResponse>>;
ParameterTypeRequiredDescription
requestAzionAIRequestYesThe conversation to send.
optionsAzionClientOptionsNoRequest options.

Returns an async generator, not a promise: read it with for await. Each chunk is its own envelope, with data as an AzionAIStreamResponse. The text of the chunk is in choices[0].delta.content, which a chunk can leave out.

TypeScript
01import { streamChat } from 'azion/ai';
02import type { AzionAIRequest, AzionAIStreamResponse, AzionAIResult } from 'azion/ai';
03
04const request: AzionAIRequest = {
05 messages: [{ role: 'user', content: 'List 5 use cases for Azion Functions.' }],
06};
07const stream: AsyncGenerator<AzionAIResult<AzionAIStreamResponse>> = streamChat(request, { debug: false });
08for await (const chunk of stream) {
09 if (chunk.data) {
10 process.stdout.write(chunk.data.choices[0]?.delta.content || '');
11 } else {
12 console.error('Error:', chunk.error);
13 }
14}
15process.stdout.write('\n');

The model writes a different answer on every run. This output is cut after the first use case:

Text
01Sure, let me look into the documentation for use cases related to Azion Functions. I'll find some relevant examples for you...
02
03
04
05
06
07
08
09
10
11 Here are 5 use cases for Azion Functions:
12
131. **Event-Driven Applications**: Create serverless applications that respond to events in real time, enabling ultra-low latency and high scalability. Functions can be reused across different applications and configured with environment variables.
14…

Errors

A failed call returns an Error in error. Read its text from error.message.

MessageCauseWhat to do
HTTP error! status: 403The Azion AI API refused the token.Use a valid personal token in AZION_TOKEN or in the client token.

Types

The module exports these types. Import them with import type.

AzionAIClient

The client that createClient returns.

MethodArgumentsReturns
chatrequest: AzionAIRequest, options?: AzionClientOptionsPromise<AzionAIResult<AzionAIResponse>>
streamChatrequest: AzionAIRequest, options?: AzionClientOptionsAsyncGenerator<AzionAIResult<AzionAIStreamResponse>>

AzionClientOptions

Request options that chat and streamChat take in options, and createClient takes for all its calls.

PropertyTypeRequiredDescription
debugbooleanNoPrints the whole response object, or every chunk object of a stream, before the answer.
forcebooleanNo—

AzionAIRequest

The conversation that chat and streamChat send.

PropertyTypeRequiredDescription
messagesAzionAIMessage[]YesThe messages of the conversation, in order.
azionAzionAIConfigNo—
streambooleanNo—

AzionAIMessage

One message of the conversation.

PropertyTypeRequiredDescription
role'system' | 'user' | 'assistant'YesThe author of the message.
contentstringYesThe text of the message.

AzionAIConfig

The settings a request carries in azion. Every field is an optional string.

TypeScript
01interface AzionAIConfig {
02 session_id?: string;
03 url?: string;
04 app?: string;
05 user_name?: string;
06 client_id?: string;
07 system_prompt?: string;
08 user_prompt?: string;
09}

AzionAIResult

The envelope every call returns, and every chunk of a stream. For how to read it, refer to Response envelope.

PropertyTypeRequiredDescription
dataT | nullYesThe response, or null when the call fails.
errorError | nullYesThe error, or null when the call succeeds.

AzionAIResponse

The response of chat. The answer is in choices[0].message.content.

TypeScript
01interface AzionAIResponse {
02 choices: {
03 finish_reason: string;
04 index: number;
05 message: {
06 content: string;
07 role: string;
08 };
09 logprobs: null;
10 }[];
11 created: number;
12 id: string;
13 model: string;
14 object: string;
15 usage: {
16 completion_tokens: number;
17 prompt_tokens: number;
18 total_tokens: number;
19 completion_tokens_details: {
20 reasoning_tokens: number;
21 };
22 };
23}

AzionAIStreamResponse

One chunk of streamChat. The text of the chunk is in choices[0].delta.content.

TypeScript
01interface AzionAIStreamResponse {
02 choices: {
03 delta: {
04 content?: string;
05 };
06 finish_reason: string | null;
07 index: number;
08 logprobs: null;
09 }[];
10 created: number;
11 id: string;
12 model: string;
13 object: string;
14 system_fingerprint: string;
15}
Azion Lib

The libraries Azion Lib ships and the package each one comes from.

Client

One client that reaches the AI functions next to Storage, SQL, Purge, Domains, and Applications.

How Azion Lib works

How the packages find your token, switch on debug output, and return their envelopes.

Personal tokens

Create the token that the AI functions send with each request.