# AI client O módulo `azion/ai` do pacote `azion` é o client da Azion Lib para a Azion AI API, um assistente que responde a perguntas sobre os produtos e serviços da Azion. Você envia uma conversa, e ele retorna a resposta inteira com `chat` ou em chunks, à medida que o modelo a escreve, com `streamChat`. Instale o pacote: ```bash npm install azion ``` O pacote `azion` recebe apenas correções de bugs, e a manutenção dele termina em dezembro de 2026. Todos os exemplos desta página são módulos ES em TypeScript que rodam no Node.js e usam `await` de nível superior. Os tipos entram por `import type`, então os exemplos ainda carregam quando uma ferramenta remove as anotações de tipo antes de executá-los. --- ## Autenticação As funções `chat` e `streamChat` leem seu [personal token](/pt-br/documentacao/fundamentos/personal-tokens/) da variável de ambiente `AZION_TOKEN`. Um client criado com [createClient](#createclient) guarda o próprio token, passado no campo `token`. Um arquivo `.env` com as duas variáveis fica assim: ```bash AZION_TOKEN=[TOKEN VALUE] AZION_DEBUG=true ``` | Variável | Descrição | | ------------- | ----------------------------------------------------------------------------------------------------------------------- | | `AZION_TOKEN` | Seu personal token da Azion. | | `AZION_DEBUG` | Com `true`, `chat` imprime o objeto de resposta inteiro antes da resposta, e `streamChat` imprime cada objeto de chunk. | Para saber como os pacotes da Azion Lib resolvem o token e a configuração de debug, consulte [Como a Azion Lib funciona](/pt-br/documentacao/devtools/azion-lib/como-funciona/). --- ## Envelope de resposta Toda chamada retorna um objeto [AzionAIResult](#azionairesult), `{ data, error }`. Em caso de sucesso, `data` contém a resposta e `error` é `null`. Em caso de falha, `data` é `null` e `error` é um `Error` do JavaScript. Uma chamada recusada não lança exceção. Leia a falha em `error.message`. A propriedade `message` de um `Error` não é enumerável, então `JSON.stringify(error)` imprime `{}` e esconde o motivo. --- ## createClient Cria um client que guarda um token e as opções de requisição e expõe `chat` e `streamChat` como métodos. `createClient` também é o export padrão de `azion/ai`. ```typescript function createClient(config?: Partial<{ token: string; options?: AzionClientOptions; }>): AzionAIClient; ``` | Parâmetro | Tipo | Obrigatório | Descrição | | --------- | ------------------------------------------- | ----------- | ------------------------------------------------------------- | | `token` | `string` | Não | Seu personal token da Azion. | | `options` | [`AzionClientOptions`](#azionclientoptions) | Não | Opções de requisição para todas as chamadas que o client faz. | Retorna um [AzionAIClient](#azionaiclient). Seus métodos recebem os mesmos argumentos que as funções [chat](#chat) e [streamChat](#streamchat). Este exemplo cria um client e faz uma pergunta a ele: ```typescript import { createClient } from 'azion/ai'; import type { AzionAIClient } from 'azion/ai'; const client: AzionAIClient = createClient({ token: process.env.AZION_TOKEN, // Replace with your actual token options: { // Add any additional options here }, }); const { data, error } = await client.chat({ messages: [{ role: 'user', content: 'What is Azion Object Storage? One sentence.' }] }); console.log(data ? data.choices[0].message.content : error); ``` O modelo escreve uma resposta diferente a cada execução. Esta saída está cortada depois da resposta, antes da lista de páginas da documentação: ```text Azion 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. … ``` --- ## chat Envia uma conversa para a Azion AI API e retorna a resposta inteira quando o modelo termina de escrevê-la. A função recebe dois argumentos posicionais, não um objeto. ```typescript function chat( request: AzionAIRequest, options?: AzionClientOptions, ): Promise>; ``` | Parâmetro | Tipo | Obrigatório | Descrição | | --------- | ------------------------------------------- | ----------- | --------------------- | | `request` | [`AzionAIRequest`](#azionairequest) | Sim | A conversa a enviar. | | `options` | [`AzionClientOptions`](#azionclientoptions) | Não | Opções de requisição. | Retorna `data` como um [AzionAIResponse](#azionairesponse). A resposta está em `choices[0].message.content`. ```typescript import { chat } from 'azion/ai'; import type { AzionAIRequest, AzionAIResponse, AzionAIResult } from 'azion/ai'; const request: AzionAIRequest = { messages: [{ role: 'user', content: 'Explain what the Azion Web Platform is.' }], }; const { data: response, error }: AzionAIResult = await chat(request, { debug: false }); if (response) { console.log('AI response:', response.choices[0].message.content); } else { console.error('Chat failed', error); } ``` Em caso de sucesso, o exemplo imprime `AI response:` seguido da resposta. --- ## streamChat Envia uma conversa para a Azion AI API e entrega a resposta em chunks enquanto o modelo a escreve. Use para mostrar a resposta à medida que ela chega. ```typescript function streamChat( request: AzionAIRequest, options?: AzionClientOptions, ): AsyncGenerator>; ``` | Parâmetro | Tipo | Obrigatório | Descrição | | --------- | ------------------------------------------- | ----------- | --------------------- | | `request` | [`AzionAIRequest`](#azionairequest) | Sim | A conversa a enviar. | | `options` | [`AzionClientOptions`](#azionclientoptions) | Não | Opções de requisição. | Retorna um gerador assíncrono, não uma promise: leia-o com `for await`. Cada chunk é um envelope próprio, com `data` como um [AzionAIStreamResponse](#azionaistreamresponse). O texto do chunk está em `choices[0].delta.content`, que um chunk pode omitir. ```typescript import { streamChat } from 'azion/ai'; import type { AzionAIRequest, AzionAIStreamResponse, AzionAIResult } from 'azion/ai'; const request: AzionAIRequest = { messages: [{ role: 'user', content: 'List 5 use cases for Azion Functions.' }], }; const stream: AsyncGenerator> = streamChat(request, { debug: false }); for await (const chunk of stream) { if (chunk.data) { process.stdout.write(chunk.data.choices[0]?.delta.content || ''); } else { console.error('Error:', chunk.error); } } process.stdout.write('\n'); ``` O modelo escreve uma resposta diferente a cada execução. Esta saída está cortada depois do primeiro caso de uso: ```text Sure, let me look into the documentation for use cases related to Azion Functions. I'll find some relevant examples for you... Here are 5 use cases for Azion Functions: 1. **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. … ``` --- ## Erros Uma chamada que falha retorna um `Error` em `error`. Leia o texto dele em `error.message`. | Mensagem | Causa | O que fazer | | ------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `HTTP error! status: 403` | A Azion AI API recusou o token. | Use um [personal token](/pt-br/documentacao/fundamentos/personal-tokens/) válido em `AZION_TOKEN` ou no `token` do client. | --- ## Tipos O módulo exporta estes tipos. Importe-os com `import type`. ### AzionAIClient O client que [createClient](#createclient) retorna. | Método | Argumentos | Retorno | | ------------ | --------------------------------------------------------- | ------------------------------------------------------ | | `chat` | `request: AzionAIRequest`, `options?: AzionClientOptions` | `Promise>` | | `streamChat` | `request: AzionAIRequest`, `options?: AzionClientOptions` | `AsyncGenerator>` | ### AzionClientOptions Opções de requisição que `chat` e `streamChat` recebem em `options`, e que [createClient](#createclient) recebe para todas as chamadas dele. | Propriedade | Tipo | Obrigatório | Descrição | | ----------- | --------- | ----------- | ---------------------------------------------------------------------------------------------- | | `debug` | `boolean` | Não | Imprime o objeto de resposta inteiro, ou cada objeto de chunk de um stream, antes da resposta. | | `force` | `boolean` | Não | — | ### AzionAIRequest A conversa que `chat` e `streamChat` enviam. | Propriedade | Tipo | Obrigatório | Descrição | | ----------- | ------------------------------------- | ----------- | ----------------------------------- | | `messages` | [`AzionAIMessage[]`](#azionaimessage) | Sim | As mensagens da conversa, em ordem. | | `azion` | [`AzionAIConfig`](#azionaiconfig) | Não | — | | `stream` | `boolean` | Não | — | ### AzionAIMessage Uma mensagem da conversa. | Propriedade | Tipo | Obrigatório | Descrição | | ----------- | ----------------------------------- | ----------- | -------------------- | | `role` | `'system' \| 'user' \| 'assistant'` | Sim | O autor da mensagem. | | `content` | `string` | Sim | O texto da mensagem. | ### AzionAIConfig As configurações que uma requisição carrega em `azion`. Todo campo é uma string opcional. ```typescript interface AzionAIConfig { session_id?: string; url?: string; app?: string; user_name?: string; client_id?: string; system_prompt?: string; user_prompt?: string; } ``` ### AzionAIResult O envelope que toda chamada retorna, assim como cada chunk de um stream. Para saber como lê-lo, consulte [Envelope de resposta](#envelope-de-resposta). | Propriedade | Tipo | Obrigatório | Descrição | | ----------- | --------------- | ----------- | ----------------------------------------------- | | `data` | `T \| null` | Sim | A resposta, ou `null` quando a chamada falha. | | `error` | `Error \| null` | Sim | O erro, ou `null` quando a chamada tem sucesso. | ### AzionAIResponse O retorno de [chat](#chat). A resposta está em `choices[0].message.content`. ```typescript interface AzionAIResponse { choices: { finish_reason: string; index: number; message: { content: string; role: string; }; logprobs: null; }[]; created: number; id: string; model: string; object: string; usage: { completion_tokens: number; prompt_tokens: number; total_tokens: number; completion_tokens_details: { reasoning_tokens: number; }; }; } ``` ### AzionAIStreamResponse Um chunk de [streamChat](#streamchat). O texto do chunk está em `choices[0].delta.content`. ```typescript interface AzionAIStreamResponse { choices: { delta: { content?: string; }; finish_reason: string | null; index: number; logprobs: null; }[]; created: number; id: string; model: string; object: string; system_fingerprint: string; } ``` --- ## Recursos relacionados - [Azion Lib](/pt-br/documentacao/devtools/azion-lib.md): As bibliotecas que a Azion Lib oferece e o pacote de onde cada uma vem. - [Client](/pt-br/documentacao/devtools/azion-lib/client.md): Um único client que alcança as funções de AI junto com Storage, SQL, Purge, Domains e Applications. - [Como a Azion Lib funciona](/pt-br/documentacao/devtools/azion-lib/como-funciona.md): Como os pacotes encontram seu token, ativam a saída de debug e retornam os envelopes. - [Tokens pessoais](/pt-br/documentacao/fundamentos/personal-tokens.md): Crie o token que as funções de AI enviam em cada requisição.