# AIVAX Documentation > Build, operate, and evaluate AI applications with AIVAX. Language: Português. Embedded API references are linked, not fetched. --- Source: https://docs.aivax.net/pt-br/docs/overview.html # Visão geral AIVAX é uma plataforma de orquestração de IA para servir assistentes de IA através de uma única conta, superfície de API e carteira de faturamento. Combina inferência compatível com OpenAI, gateways de IA, coleções RAG, ferramentas, habilidades, clientes de chat, workers e processamento em lote. A maioria das integrações de aplicativos começa com um **Gateway de IA**. Um gateway escolhe o modelo, instruções do sistema, coleções RAG, ferramentas, comportamento de saída estruturada, configurações de moderação, workers e comportamento do canal de chat usados para uma solicitação. ## Serviços principais ### Inferência compatível com OpenAI AIVAX expõe listagem de modelos compatível com OpenAI e endpoints de conclusão de chat. Você pode chamar modelos hospedados da AIVAX diretamente ou chamar um Gateway de IA pelo seu identificador de modelo. A URL base de produção principal é: ```text https://inference.aivax.net ``` Use `/v1` como caminho base do SDK OpenAI: ```text https://inference.aivax.net/v1 ``` Referência: [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Inference%20(chat%20completions)) ### Gateways de IA Um Gateway de IA é o runtime configurado para um assistente. No modelo fonte ele armazena: - Seleção de provedor ou modelo integrado. - Instrução do sistema e modelos de prompt opcionais. - Links de coleções RAG e estratégia de consulta. - Ferramentas integradas, funções de protocolo, fontes MCP e opções Bash. - Configurações de esquema JSON e JSON Healing. - Fonte do script do worker e configurações de moderação. - Limites de contexto, comportamento de truncamento, esforço de raciocínio, verbosidade e configurações de roteamento. Slugs de gateway são convenientes para chaves privadas. Compleções de chat com chave pública devem usar o UUID completo do gateway e não podem chamar modelos integrados diretamente. ### Coleções RAG Coleções armazenam documentos que são indexados com embeddings e pesquisados durante a inferência ou através de endpoints de coleção. Limites do plano controlam a contagem de coleções, taxa de pesquisa, taxa de inserção e tamanho de importação JSONL. AIVAX também expõe coleções como ferramentas MCP através de `/v1/mcp/collections`. O endpoint MCP de coleção lê a configuração dos cabeçalhos, como IDs de coleção, nome da ferramenta, top-k, pontuação mínima, reranker e se ferramentas de escrita são permitidas. ### Ferramentas Gateways podem habilitar ferramentas que permitem ao modelo chamar serviços da plataforma ou sistemas externos. Funções integradas cobrem busca na web, busca avançada na web, busca no X/Twitter, geração de imagens, geração de documentos ou páginas, execução de código, memória, calendário e ativações agendadas. Chaves privadas podem usar a configuração completa da ferramenta do gateway. Chamadas de conclusão de chat com chave pública removem superfícies de ferramentas do lado do servidor, como fontes MCP, funções de protocolo, ferramentas integradas, Bash, habilidades e opções de sentinela. ### Habilidades Habilidades são pacotes de instruções reutilizáveis anexados a um gateway. Elas são carregadas no contexto do modelo quando selecionadas pelo assistente e podem restringir ou expor o comportamento da ferramenta. ### Saída estruturada AIVAX suporta dois caminhos de saída estruturada: - `response_schema`: AIVAX valida o JSON gerado contra o esquema e habilita JSON Healing. - `response_format` com `json_schema`: caminho de esquema compatível com provedor; AIVAX também pode aplicar JSON Healing quando as configurações da conta permitirem. Use `json_only` somente quando o chamador espera o JSON bruto gerado em vez do envelope normal de conclusão de chat. ### Clientes de chat e integrações Clientes de chat conectam um gateway a usuários finais através de sessões públicas de web-chat ou integrações para Telegram, Z-API WhatsApp, Evolution API e Kapso. Clientes de chat têm seus próprios limites por sessão e por hora, além de verificações de saldo da conta. ### Workers e hooks Workers são hooks de propriedade da conta que podem interromper ou modificar eventos do gateway. Solicitações da AIVAX ao seu serviço podem incluir `X-Request-Nonce`, um hash BCrypt derivado da chave do hook da conta. Valide-o antes de confiar na solicitação. ### Processamento em lote Fluxos de trabalho em lote processam itens independentes de forma assíncrona com uma instrução de fluxo, modelo, esquema e ferramentas opcionais. O plano controla quantos itens de fluxo em lote podem ser processados por dia. ## Como as solicitações são verificadas Solicitações de API autenticadas passam pelo middleware de chave de conta. O middleware resolve a conta e a chave, armazena ambas no contexto da solicitação e adiciona cabeçalhos da conta à resposta. Endpoints que gastam dinheiro ou requerem armazenamento também verificam saldo e cota de armazenamento antes de continuar. Para conclusões de chat, o runtime então verifica: 1. Se o modelo selecionado está disponível no plano da conta. 2. Limites de taxa de solicitação de modelo integrado e token de entrada, ou limites de solicitação BYOK. 3. O limite de contexto do plano Free. 4. Requisitos de ferramenta e modalidade. 5. Requisitos de saldo e armazenamento, incluindo verificações de saldo mínimo adicionais para entradas de imagem/áudio/arquivo/vídeo. ## Próximos passos - [Começando](https://docs.aivax.net/pt-br/docs/getting-started.md) - [Autenticação](https://docs.aivax.net/pt-br/docs/authentication.md) - [Precificação](https://docs.aivax.net/pt-br/docs/pricing.md) - [Planos e limites](https://docs.aivax.net/pt-br/docs/limits.md) --- Source: https://docs.aivax.net/pt-br/docs/getting-started.html # Começando Este guia leva você de uma conta AIVAX a uma conclusão de chat compatível com OpenAI verificada. O exemplo usa Python e uma chave de API privada de um ambiente do lado do servidor. Até o final, você terá confirmado que sua chave e o modelo ou AI Gateway selecionado podem concluir uma solicitação. ## Antes de começar Você precisa: - Uma conta AIVAX com acesso ao painel e permissão para criar uma chave de API privada. - Python 3.8 ou superior com `pip` disponível. Para preços e limites operacionais, veja [Preços](https://docs.aivax.net/pt-br/docs/pricing.md) e [Planos e limites](https://docs.aivax.net/pt-br/docs/limits.md). Production API base URL: ```text https://inference.aivax.net ``` OpenAI-compatible SDK base URL: ```text https://inference.aivax.net/v1 ``` ## 1. Crie uma chave de API privada Crie uma chave **privada** a partir da área de Chaves de API do painel AIVAX. Copie a chave quando ela for exibida e armazene-a como um segredo; não cole o valor real no código abaixo. Chaves privadas são destinadas a aplicações confiáveis do lado do servidor. Chaves públicas são credenciais restritas para rotas do lado do cliente intencionalmente expostas e não são substitutas de uma chave de backend. Se você estiver construindo um widget web público ou experiência de mensagens, revise [Chat clients](https://docs.aivax.net/pt-br/docs/features/chat-clients.md) antes de expor qualquer credencial. As sessões de chat fornecem um limite mais claro para a identidade do usuário, histórico de conversas e anexos. Veja [Authentication](https://docs.aivax.net/pt-br/docs/authentication.md) para esquemas de autenticação suportados, comportamento de chaves privadas e públicas, e orientações sobre manipulação de segredos. ## 2. Instale o SDK OpenAI Instale o SDK no ambiente Python que você usará para este exemplo: ```bash python -m pip install openai ``` Mantenha a chave fora do seu arquivo fonte. Por exemplo, defina uma variável de ambiente chamada `AIVAX_API_KEY` usando o método de gerenciamento de segredos adequado ao seu shell ou plataforma de implantação. ## 3. Escolha um modelo ou AI Gateway O campo `model` pode identificar: - Um modelo hospedado retornado pelo endpoint de listagem de modelos. - Um AI Gateway disponível na sua conta. Use um **modelo hospedado** para uma chamada direta, única ou experimento inicial. Use um **AI Gateway** quando quiser reutilizar o mesmo modelo, instruções, coleções RAG, habilidades, ferramentas, moderação e configurações de saída em várias solicitações ou usuários. Slugs de gateway são suportados com chaves privadas. Compleções de chat com chave pública devem usar o UUID completo do gateway e não podem chamar modelos integrados diretamente. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Model%20listing) Copie um nome de modelo ou identificador de gateway que esteja disponível na sua conta. Você o usará como `` na próxima etapa. ## 4. Faça a primeira solicitação Crie um arquivo chamado `quickstart.py` com o seguinte código: ```python import os from openai import OpenAI client = OpenAI( base_url="https://inference.aivax.net/v1", api_key=os.environ["AIVAX_API_KEY"], ) response = client.chat.completions.create( model="", messages=[ {"role": "user", "content": "Write a one-sentence welcome message."} ], ) print(response.choices[0].message.content) ``` Substitua `` pelo nome exato do modelo hospedado ou identificador de gateway selecionado na etapa anterior. Não substitua `AIVAX_API_KEY` pela própria chave; o código lê o segredo do ambiente. Execute o arquivo: ```bash python quickstart.py ``` Uma solicitação bem-sucedida imprime uma frase gerada e sai sem erro de API. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Inference%20(chat%20completions)) ## 5. Confirme a integração Confirme que a resposta gerada corresponde ao prompt e vem do modelo ou AI Gateway selecionado na etapa anterior. Isso verifica o endpoint, credencial e seleção de modelo usados pela sua aplicação. Antes de aumentar o tráfego ou processar entradas grandes, revise [Preços](https://docs.aivax.net/pt-br/docs/pricing.md) e [Planos e limites](https://docs.aivax.net/pt-br/docs/limits.md). ## Solucionar problemas da primeira solicitação AIVAX usa dois estilos de resposta: - Endpoints compatíveis com OpenAI retornam um objeto `error` no estilo OpenAI. - Endpoints de conta e administrativos retornam um envelope de resposta AIVAX com um erro ou um valor `data` bem-sucedido. | Status | O que verificar | | --- | --- | | `400 Bad Request` | Confirme o identificador do modelo ou gateway e remova parâmetros não suportados da solicitação. | | `401 Unauthorized` | Confirme que a chave privada está presente, completa, ativa e enviada através da configuração do SDK. | | `402 Payment Required` | Revise [Preços](https://docs.aivax.net/pt-br/docs/pricing.md) e confirme que a conta está pronta para uma solicitação paga. | | `403 Forbidden` | Confirme que o tipo de chave, modelo ou recurso selecionado permite esta operação. | | `429 Too Many Requests` | Tente novamente mais tarde e revise [Planos e limites](https://docs.aivax.net/pt-br/docs/limits.md) antes de aumentar o volume de solicitações. | Se a solicitação ainda falhar, verifique nesta ordem: 1. `base_url` é `https://inference.aivax.net/v1`. 2. `AIVAX_API_KEY` está disponível para o processo Python e contém uma chave privada. 3. O modelo ou gateway selecionado existe e está disponível para a conta. 4. Para um gateway, teste um prompt simples antes de adicionar RAG, ferramentas, mídia ou saída estruturada, para que você possa isolar problemas de configuração. ## Inferência de longa duração A maioria das aplicações deve usar a URL base padrão do SDK, `https://inference.aivax.net/v1`. Contudo, uma solicitação que realiza raciocínio extendido, usa várias ferramentas, processa um contexto grande ou aguarda um modelo upstream lento pode permanecer aberta mais tempo que o proxy padrão permite. Se essa solicitação terminar com HTTP `524` enquanto a AIVAX ainda a processa, use o host de inferência direta: ```text https://direct.inference.aivax.net/v1 ``` O host direto contorna o caminho padrão do proxy enquanto preserva o mesmo contrato de solicitação e resposta síncrona compatível com OpenAI. Ele não transforma a solicitação em um trabalho em segundo plano: mantenha a conexão do cliente aberta até que a conclusão termine e configure um timeout do cliente que cubra o tempo de processamento esperado. Use a mesma chave de API privada, identificador de modelo ou AI Gateway, mensagens e parâmetros de solicitação. Altere a URL base do SDK e o timeout: ```python import os from openai import OpenAI client = OpenAI( base_url="https://direct.inference.aivax.net/v1", api_key=os.environ["AIVAX_API_KEY"], timeout=300.0, ) response = client.chat.completions.create( model="", messages=[ { "role": "user", "content": "Analyze this case carefully and provide a detailed recommendation.", } ], ) print(response.choices[0].message.content) ``` O host direto suporta listagem de modelos e completações de chat compatíveis com OpenAI em `/v1/models` e `/v1/chat/completions`, incluindo seus aliases `/api/v1`. Ele também suporta rotas de geração, consulta, resposta e classificação da AIVAX. O gerenciamento de contas, gerenciamento de AI Gateway e outras APIs administrativas não são expostas por este host; continue usando `https://inference.aivax.net` para elas. Use o host direto especificamente para inferência que pode durar mais que o proxy padrão. Ele não é um fallback para respostas `400`, `401`, `402`, `403` ou `429`, e mudar de host não altera autenticação, faturamento, disponibilidade de modelo ou limites da conta. Para cargas de trabalho que não precisam de uma conexão síncrona aberta, considere [Batch](https://docs.aivax.net/pt-br/docs/features/batch.md) em vez disso. ## Escolha o próximo produto Depois que a solicitação mínima funcionar, adicione uma capacidade de cada vez: - [AI Gateways](https://docs.aivax.net/pt-br/docs/inference/ai-gateway.md) — torne a configuração do assistente reutilizável em solicitações e usuários. - [Structured responses](https://docs.aivax.net/pt-br/docs/inference/structured-responses.md) — exija que o JSON gerado siga um esquema de aplicação. - [RAG collections](https://docs.aivax.net/pt-br/docs/rag/collections.md) — indexe seus documentos, teste a recuperação e anexe conhecimento fundamentado a um gateway. - [Built-in tools](https://docs.aivax.net/pt-br/docs/tools/builtin-tools.md), [MCP](https://docs.aivax.net/pt-br/docs/tools/mcp.md) ou [Protocol functions](https://docs.aivax.net/pt-br/docs/tools/protocol-functions.md) — permita que o assistente recupere informações ao vivo ou execute ações. - [Chat clients](https://docs.aivax.net/pt-br/docs/features/chat-clients.md) — entregue um gateway via chat web ou canais de mensagem suportados. - [Text and media products](https://docs.aivax.net/pt-br/docs/overview.md#process-text-documents-and-media) — classifique ou segmente documentos, gere imagens ou fala, transcreva áudio e descreva mídia. - [Batch](https://docs.aivax.net/pt-br/docs/features/batch.md) — aplique o mesmo fluxo de trabalho a muitos registros independentes de forma assíncrona. - [Agentic Tests](https://docs.aivax.net/pt-br/docs/inference/agentic-tests.md) — avalie uma conversa completa de gateway antes e depois de mudanças de configuração. Antes de aumentar o tráfego ou processar entradas grandes, revise [Preços](https://docs.aivax.net/pt-br/docs/pricing.md) e [Planos e limites](https://docs.aivax.net/pt-br/docs/limits.md). --- Source: https://docs.aivax.net/pt-br/docs/authentication.html # Autenticação AIVAX autentica solicitações de API com chaves de API da conta. AIVAX aceita chaves de API via: - `Authorization: Bearer ` - `Authorization: Basic ` - `?api-key=` Prefira o cabeçalho `Authorization` para chamadas servidor‑para‑servidor. Use o parâmetro de consulta apenas quando um cliente ou integração não puder enviar cabeçalhos, pois URLs podem ser registradas por proxies, navegadores e ferramentas de monitoramento. ## Tipos de chave de API AIVAX tem duas famílias de chaves porque casos de uso de navegador e de servidor têm perfis de risco diferentes. Se o seu código roda no seu servidor, use uma chave privada e mantenha‑a fora de bundles de cliente, logs e repositórios públicos. Se o seu código roda em um navegador ou outro ambiente onde a chave pode ser inspecionada pelo usuário final, use uma chave pública e limite o fluxo a rotas projetadas para acesso público. | Tipo | Prefixo | Uso pretendido | Acesso | | --- | --- | --- | --- | | Chave privada | `sk-aiv-acc` | Integrações do lado do servidor e chamadas de API administrativas. | APIs de conta autenticadas e inferência compatível com OpenAI. | | Chave pública | `pk-aiv-` | Chamadas restritas do lado do cliente para rotas explicitamente públicas. | Rotas públicas de consulta/resposta RAG e chamadas de conclusão de chat restritas. | Chaves públicas podem ser usadas para busca semântica RAG, geração de respostas RAG, geração de fala, descrições de mídia, geração de imagens e conclusões de chat. Quando uma chave pública chama conclusões de chat: - O `model` deve ser um UUID completo do AI Gateway; chamadas diretas de modelo integrado e busca de slug de gateway são desativadas. - A busca de slug de gateway está desativada. - Fontes MCP, funções de protocolo, ferramentas embutidas, Bash, habilidades e opções de sentinel são removidas da solicitação. - Apenas esses parâmetros de solicitação são aceitos: `model`, `messages`, `prompt`, `temperature`, `top_p`, `top_k`, `seed`, `tools`, `reasoning_effort`, `max_completion_tokens`, `idempotency_key` e `stream`. - Limites de taxa de solicitação e de token são aplicados tanto globalmente por chave quanto por endereço remoto. Use chaves privadas para serviços de backend, gerenciamento de conta, listagem de modelos, gerenciamento de coleções, operações em lote e qualquer fluxo que precise da superfície completa de ferramentas do gateway. Para a primeira solicitação do lado do servidor, continue com [Getting Started](https://docs.aivax.net/pt-br/docs/getting-started.md). Se você está expondo uma experiência de navegador ou widget para usuários finais, revise [Chat Clients](https://docs.aivax.net/pt-br/docs/features/chat-clients.md) antes de decidir se uma chave pública é o limite correto. ## Criar e listar chaves Chaves de API pertencem a uma conta e podem ter um rótulo, expiração e tipo. Uma chave com duração negativa não expira; chaves expiradas são rejeitadas pela autenticação e removidas posteriormente por jobs de limpeza. Crie chaves separadas para aplicações separadas. Isso torna a rotação mais segura: se uma integração for comprometida, você pode revogar apenas essa chave em vez de quebrar todos os serviços vinculados à conta. Rótulos e datas de expiração são ferramentas operacionais, não decoração; use-os para identificar quem é o proprietário da chave e quando ela deve ser revisada. Referência: [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Create%20API%20Key) [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=List%20API%20Keys) ## Enviar uma chave com autenticação Bearer Para SDKs compatíveis com OpenAI, passe a chave AIVAX como a chave de API do SDK e defina a URL base para `https://inference.aivax.net/v1`. ```python from openai import OpenAI client = OpenAI( base_url="https://inference.aivax.net/v1", api_key="" ) ``` ## Autenticação de hook AIVAX pode autenticar solicitações outbound para seus serviços, como workers do AI Gateway e funções de protocolo do lado do servidor. Esta é a direção inversa da autenticação normal de API. Em uma chamada de API normal, sua aplicação prova que tem permissão para chamar AIVAX enviando uma chave de API. Em um callback de worker ou função de protocolo, AIVAX está chamando seu serviço, então seu serviço precisa de uma forma de verificar que a solicitação realmente veio da configuração de conta que você controla. É para isso que serve o `X-Request-Nonce`. Se sua conta tem uma chave de hook, AIVAX envia: ```text X-Request-Nonce: ``` O nonce é um hash BCrypt derivado da chave de hook da conta. Valide o cabeçalho verificando a chave de hook em texto plano armazenada contra o hash. Se a conta não tem chave de hook, o cabeçalho não é enviado. Rotacionar a chave de hook invalida os segredos de validação existentes de workers e integrações. ### Exemplo em C# ```csharp using BCrypt.Net; var nonce = request.Headers["X-Request-Nonce"]; var hookKey = Environment.GetEnvironmentVariable("AIVAX_HOOK_SECRET"); if (nonce is null || hookKey is null) { return Results.Unauthorized(); } if (!BCrypt.Net.BCrypt.Verify(hookKey, nonce, enhancedEntropy: false)) { return Results.Forbid(); } ``` ### Exemplo em Python ```python import os import bcrypt from flask import abort, request nonce = request.headers.get("X-Request-Nonce") hook_key = os.getenv("AIVAX_HOOK_SECRET") if nonce is None or hook_key is None: abort(401) if not bcrypt.checkpw(hook_key.encode("utf-8"), nonce.encode("utf-8")): abort(403) ``` ### Exemplo em JavaScript ```javascript import bcrypt from "bcrypt"; const nonce = req.header("X-Request-Nonce"); const hookKey = process.env.AIVAX_HOOK_SECRET; if (!nonce || !hookKey) { return res.sendStatus(401); } if (!(await bcrypt.compare(hookKey, nonce))) { return res.sendStatus(403); } ``` --- Source: https://docs.aivax.net/pt-br/docs/pricing.html # Preços Os preços de uso do serviço são listados abaixo em USD. **M** significa um milhão de tokens; **1k** significa mil unidades. Preços aproximados (`~`) variam conforme o modelo usado e o trabalho realizado. Veja [preços de assinatura](https://aivax.net/pricing) para preços mensais dos planos e [Planos e limites](https://docs.aivax.net/pt-br/docs/limits.md) para cotas. As taxas de uso estão sujeitas ao multiplicador do plano: - Free: **+25%** nos impostos de inferência; - Pro: **+5%** nos impostos de inferência; - Max: **0%** nos impostos de inferência. BYOK não são afetados pelos impostos de inferência. Free, Pro e Max incluem cotas diárias separadas para embeddings RAG elegíveis, reranking Reflex, decisões semânticas Julia-1 e extração Fetch/OCR. As taxas abaixo se aplicam quando um item medido não está coberto. A cobertura é tudo ou nada por item, não necessariamente por requisição completa: um item que não cabe na cota restante e sua margem permitida é cobrado integralmente. Compare as cotas e verifique exclusões em [Planos e limites](https://docs.aivax.net/pt-br/docs/limits.md#included-daily-subscription-allowances). A cobertura de assinatura LLM está atualmente desativada. ## Inferência e Moderação As taxas de inferência dependem do modelo selecionado, provedor, tamanho da entrada e tipo de mídia. A moderação é cobrada separadamente em Unidades de Processamento (PUs), cobrindo uso de entrada, entrada em cache e saída; seu preço por PU varia conforme o modelo e provedor usados. | Descrição | Preço | | --- | ---: | | Inferência de modelo de IA e gateway de IA | Selected model and provider rates | | Moderação de entrada | Variable price per PU; separate from the main inference charge | ## Testes de Agente Cada teste inclui as cobranças de inferência do modelo selecionado ou do gateway de IA, além do uso de usuário simulado e juiz nas taxas do perfil selecionado. | Descrição | Preço | | --- | ---: | | Modelo ou gateway de IA em teste | Regular inference rates | | Perfil baixo - usuário simulado | Input **$0.25/M tokens**; cache **$0.025/M tokens**; output **$1.50/M tokens** | | Perfil baixo - juiz | Input **$0.30/M tokens**; cache **$0.03/M tokens**; output **$2.50/M tokens** | | Perfil médio - usuário simulado | Input **$0.75/M tokens**; cache **$0.075/M tokens**; output **$3.75/M tokens** | | Perfil médio - juiz | Input **$0.75/M tokens**; cache **$0.075/M tokens**; output **$3.75/M tokens** | | Perfil alto - usuário simulado | Input **$0.75/M tokens**; cache **$0.075/M tokens**; output **$3.75/M tokens** | | Perfil alto - juiz | Input **$1.25/M tokens**; cache **$0.15/M tokens**; output **$4.25/M tokens** | ## RAG e Coleções Indexação e busca são cobradas por uso de tokens. Respostas RAG geradas são cobradas separadamente da incorporação de consulta, e seu preço varia com o modelo de sumarização. | Descrição | Preço | | --- | ---: | | Incorporação de texto da coleção | **$0.10/M tokens** | | Busca semântica - falha no cache de consulta | **$0.10/M tokens** | | Busca semântica - acerto no cache de consulta | Zero | | Geração de resposta RAG | **~$0.50/M tokens**, excluding query rates | | Reflex - falha no cache | **$0.015/M tokens** | | Reflex - acerto no cache | **$0.003/M tokens** | ## Injetor de Mídia Converter mídia em documentos RAG é cobrado por entrada, entrada em cache, saída e uso de mídia. O arquivo fonte, contexto opcional e conteúdo gerado afetam o total. As taxas dependem do tipo de mídia e volume de tokens de entrada. | Descrição | Preço | | --- | ---: | | PDFs e imagens - até 272K tokens de entrada | Input **$0.30/M tokens**; cache **$0.03/M tokens**; output **$1.80/M tokens** | | PDFs e imagens - acima de 272K tokens de entrada | Input **$0.60/M tokens**; cache **$0.06/M tokens**; output **$3.60/M tokens** | | Áudio - até 256K tokens de entrada | Input/media **$0.60/M tokens**; cache **$0.12/M tokens**; output **$3.00/M tokens** | | Áudio - acima de 256K tokens de entrada | Input/media **$1.20/M tokens**; cache **$0.24/M tokens**; output **$6.00/M tokens** | | Vídeo | Input/media **$0.45/M tokens**; cache **$0.045/M tokens**; output **$3.75/M tokens** | ## Ferramentas de Texto Segmentação e classificação de texto são cobradas por uso de tokens. | Descrição | Preço | | --- | ---: | | Segmentação de texto | **$0.30/M tokens** | | Classificação de texto | **$0.10/M tokens** | ## Voz e Mídia As taxas de geração e transcrição dependem do modelo selecionado. O preço da descrição de mídia é aproximado e depende do modelo de processamento disponível. | Descrição | Preço | | --- | ---: | | Sessões de voz | Selected realtime model rates | | Fala para texto | Varies by model | | Texto para fala | Varies by model | | Geração de imagem | Fixed output and reference-image tariffs by model | | Descrições de mídia | **~$1.50/M tokens** | A geração de imagem cobra cada saída entregue ao preço fixo de saída do modelo selecionado, mais seu preço por referência para cada referência enviada com essa saída. O processamento do prompt está incluído. Provedores com preços por token e megapixel usam estimativas arredondadas, não repasse exato de custo do provedor. Nenhuma marcação adicional de geração de imagem AIVAX ou multiplicador de conta e plano se aplica. As tarifas atuais estão listadas no catálogo de Modelos; veja [Geração de imagem](https://docs.aivax.net/pt-br/docs/generations/images.md). ## Busca na Web, OCR e Fetch Buscas na Web e X são cobradas por busca. Busca avançada na web é cobrada por uso de tokens e varia conforme o modelo e número de interações. Extração Fetch e OCR usam Unidades de Processamento (PUs), com uma cota diária gratuita por plano. Conversão JSON guiada por esquema opcional é cobrada separadamente. As cotas de extração e taxas de PU não se aplicam à conversão JSON ou moderação. | Descrição | Preço | | --- | ---: | | Busca na Web | **$5/1k searches** | | Busca X (Twitter) | **$5/1k searches** | | Busca avançada na web | **~$0.75/M tokens** | | Extração Fetch e OCR - Gratuita | Base daily allowance; uncovered items **$0.15/1k PUs** | | Extração Fetch e OCR - Pro | **10× Free** daily allowance; uncovered items **$0.05/1k PUs** | | Extração Fetch e OCR - Max | **5× Pro** daily allowance; uncovered items **$0.02/1k PUs** | | Conversão JSON Fetch (`responseSchema`) | Variable inference-based price per PU; charged separately, with no daily extraction allowance | Para a [API Fetch](https://docs.aivax.net/pt-br/docs/web-foundation/fetch-and-ocr.md), `processingUnits` relata o uso de extração de texto/OCR e `jsonProcessingUnits` relata o uso adicional de conversão JSON guiada por esquema. As PUs JSON contabilizam uso de tokens de entrada, entrada em cache e saída nas taxas do modelo e provedor de processamento; elas não são precificadas à taxa OCR do plano. O multiplicador de inferência do plano se aplica à conversão JSON. Omitir `responseSchema` ou defini‑lo como `null` desativa a conversão, relata `jsonProcessingUnits: 0` e não gera cobrança de conversão JSON. ## Armazenamento Cada plano inclui armazenamento. Excedentes de Pro e Max são cobrados por hora nas taxas mensais abaixo; o armazenamento gratuito não pode ser expandido. | Descrição | Preço | | --- | ---: | | Armazenamento gratuito | **30 MB included**; no expansion | | Armazenamento Pro | **2 GB included**; excess **$0.50/GB/month** | | Armazenamento Max | **20 GB included**; excess **$0.20/GB/month** | ## Outras Ferramentas As ferramentas a seguir não têm cobrança separada. A inferência do modelo usada para acioná‑las ainda é cobrada à sua taxa regular. | Descrição | Preço | | --- | ---: | | Memória e calendário | No separate charge | | Solicitações avançadas | No separate charge | | Geração de documento | No separate charge | | Geração de página web | No separate charge | --- Source: https://docs.aivax.net/pt-br/docs/limits.html # Planos e Limites AIVAX tem três planos de conta: **Free**, **Pro** e **Max**. O plano atual é armazenado na conta e controla o acesso ao modelo, comissões, limites de taxa, cotas de RAG, limites de ferramentas, cota de armazenamento, retenção de conversas e permissões diárias incluídas. Para preços de assinatura comercial e empacotamento de planos, use a [AIVAX pricing page](https://aivax.net/pricing). Esta página documenta os limites técnicos da API. ## Como os limites são aplicados Os limites são aplicados em diferentes camadas: - A autenticação rejeita chaves de API ausentes, expiradas ou desconhecidas. - Chaves de API públicas são restritas a rotas públicas e têm limites de requisição e token por chave e por IP. - O middleware de saldo rejeita requisições pagas quando o saldo da conta está abaixo do mínimo exigido. - O middleware de armazenamento rejeita requisições quando o armazenamento da conta excede a cota do plano. - As verificações de inferência avaliam acesso ao modelo, taxa de requisição, taxa de tokens de entrada, taxa BYOK e tamanho de contexto do plano Free. - As verificações de RAG avaliam contagem de coleções, taxa de busca, taxa de inserção e tamanho de importação JSONL. - Ferramentas integradas verificam limites de serviço diário. - O processamento em lote verifica quantos itens de fluxo de trabalho podem ser processados por dia. Referência: [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Get%20Account%20Balance) ## Limites do plano Um travessão longo (`—`) indica que o plano não impõe limite. Limites específicos de modelo, gateway, provedor ou endpoint ainda podem ser aplicados. | Recurso | Free | Pro | Max | | --- | --- | --- | --- | | **Inferência** | | | | | Acesso ao modelo | Modelos de baixo preço/básicos | Modelos avançados | Todos os modelos | | Multiplicador de comissão de inferência | 1.25x | 1.05x | 1.00x | | Solicitações de modelo integrado | 20/min e 500/dia | 200/min | — | | Tokens de entrada de modelo integrado | 1.000.000/min | 20.000.000/min | — | | Solicitações BYOK | 30/min | 200/min | — | | Contexto máximo | 65.536 tokens de entrada | — | — | | Cobertura de assinatura LLM | Atualmente desativada | Atualmente desativada | Atualmente desativada | | Solicitações autônomas de texto para fala | 3/min e 40/hora | 30/min | 300/min | | Solicitações autônomas de transcrição de áudio | 3/min e 40/hora | 30/min | 300/min | | Solicitações de decisão semântica | 10/min | 50/min | — | | **RAG e coleções** | | | | | Coleções | 5 | — | — | | Pesquisas semânticas | 20/min | 500/min | 3.000/min | | Documentos de classificação de texto | 30/min e 300/dia | 1.000/min | 10.000/min | | Documentos de segmentação de texto | 10/min e 100/dia | 300/min | 2.500/min | | Reordenação de buscas | 30/min | 1.000/min | — | | Tempo de processamento Reflex | 30 minutos/dia | 6 horas/dia | — | | Inserções de documentos | 500/dia | 10.000/dia | — | | Documentos JSONL por solicitação de importação | 1.000 | 10.000 | 1.000.000 | | Injetor de mídia | 2 arquivos/dia | 30 arquivos/dia | 1.000 arquivos/dia | | **Ferramentas integradas** | | | | | Pesquisa na web | 15/dia | 1.000/dia | 10.000/dia | | Pesquisa X/Twitter | Não disponível | 1.000/dia | 10.000/dia | | Pesquisa avançada na web | Não disponível | 100/dia | 1.000/dia | | Geração de documentos e páginas da web | 5/dia | 1.000/dia | 50.000/dia | | Geração e edição de imagens | 5/dia | 500/dia | 5.000/dia | | Ações gerais de serviço | 30/dia | 5.000/dia | 100.000/dia | | Comandos Bash | 300/hora | 30.000/hora | — | | **Testes agentes** | | | | | Novas execuções por conta | 5/min | 30/min | — | | Execuções simultâneas por conta | 1 | 4 | 8 | | **Processamento em lote** | | | | | Itens de fluxo de trabalho processados | 500/dia | 100.000/dia | — | | Arquivos por solicitação de importação | 1.000 | 1.000 | 1.000 | | Tamanho total de importação | 100 MiB/solicitação | 100 MiB/solicitação | 100 MiB/solicitação | | Tamanho de arquivo importado único | 10 MiB | 10 MiB | 10 MiB | | **Conta e suporte** | | | | | Cota de armazenamento | 30 MB | 2 GB | 20 GB | | Custo por GB excedente | — | $0.50/GB/mês | $0.20/GB/mês | | Retenção de conversas | 2 horas | 2 dias | 30 dias | | Nível de suporte | Email | Prioridade | Dedicado | ### Limites de taxa de decisão semântica e teste agente Esses limites por minuto são compartilhados entre chaves de API pertencentes à mesma conta. Eles são independentes das permissões de assinatura e faturamento: o uso incluído ainda consome a cota de requisição ou execução aplicável. - **Decisões semânticas:** cada requisição consome uma unidade, independentemente de quantas perguntas contém ou qual modelo de decisão é selecionado. Uma requisição que excede o limite da conta retorna `429 Too Many Requests` antes da avaliação. Veja [Decisões semânticas](https://docs.aivax.net/pt-br/docs/generations/decisions.md). - **Testes agentes:** execuções manuais, agendadas e avaliações diretas compartilham uma cota de novas execuções. Uma execução persistente consome sua unidade quando é enfileirada, não novamente quando a execução começa; turnos individuais de conversa não consomem unidades adicionais. Requisições manuais excedentes e avaliações diretas retornam `429 Too Many Requests`. Um teste agendado sem cota disponível aguarda a próxima verificação de agendamento em vez de criar uma execução extra. Execuções existentes permanecem sujeitas aos seus limites de simultaneidade e inferência separados. Veja [Testes agentes](https://docs.aivax.net/pt-br/docs/inference/agentic-tests.md). Distribua as requisições pela conta e use tentativas limitadas com backoff após um 429. Uma tentativa imediata ainda encontra a janela de limite de taxa ativa. Max não tem limite imposto pelo plano para essas duas cotas, mas outros limites aplicáveis permanecem em vigor. ### Cotas diárias incluídas na assinatura Free, Pro e Max incluem cotas diárias separadas para os serviços abaixo. Cada comparação refere‑se ao mesmo serviço no plano nomeado, não a um saldo de crédito compartilhado ou a um número garantido de requisições. Cota não utilizada de um serviço não pode cobrir outro. Contas revendedoras não recebem cotas de assinatura. | Serviço incluído | Free | Pro | Max | | --- | --- | --- | --- | | Incorporação de busca e inserção RAG | Cota base | 25× Free | 4× Pro | | Reordenação com Reflex | Cota base | 5× Free | 10× Pro | | Decisões semânticas com Julia-1 | Cota base | 2.5× Free | 2× Pro | | Busca e extração OCR | Cota base | 10× Free | 5× Pro | Pesquisas RAG e inserções de documentos compartilham a cota de incorporação. Ela não cobre geração de respostas, processamento de mídia, classificação ou segmentação de texto. Uma incorporação de consulta atendida a partir do cache não a consome. Reflex usa uma cota de reordenação separada que inclui entradas em cache e sem cache. Julia-1 é atualmente o único modelo de decisão coberto pela cota de decisão semântica; outros modelos de decisão são cobrados normalmente. A conversão opcional de JSON Fetch é separada da cota de extração. A cobertura é avaliada para cada item de serviço medido: a incorporação de um documento, a incorporação de um termo de consulta individual, uma chamada de reordenação, o uso de entrada de uma chamada de decisão ou uma operação de extração. Cada item é totalmente incluído ou cobrado integralmente nas tarifas normais. Itens incluídos são rastreados no consumo da assinatura, não como entradas de custo zero no histórico de faturamento. As cotas atuais permitem uma margem de 10 % acima da capacidade base. Um item que excederia essa margem deixa a cota inalterada e é cobrado normalmente. Uma requisição pode conter vários itens, de modo que alguns podem ser incluídos enquanto outros são cobrados. As cotas diárias são redefinidas à meia‑noite no horário local do servidor. Verifique os indicadores de uso da assinatura da conta para consumo e status de redefinição; o uso pode exceder 100 % dentro da margem. A cobertura de assinatura LLM está atualmente desativada, portanto a inferência de texto‑modelo e a geração de respostas RAG permanecem medidas separadamente. As cotas não contornam requisitos de saldo, limites de taxa ou o teto de tempo de processamento separado de Reflex. Consulte [Pricing](https://docs.aivax.net/pt-br/docs/pricing.md) para cobranças quando um item não está coberto. Contas revendedoras suportam 8 execuções de teste agente simultâneas por conta. Solicitações de modelo integrado são limitadas tanto por contagem de requisições quanto por tokens de entrada. Grupos de limite de taxa de modelo ajustam os limites de contagem de requisições: | Grupo de limite de taxa | Multiplicador de limite | | --- | --- | | Comum | 1.0x | | Descontado | 0.5x | | Baixo | 0.3x | | Free | 0.1x | Por exemplo, uma conta Pro normalmente tem 200 solicitações de modelo integrado por minuto. Com um grupo de modelo `Discounted`, o limite ajustado é 100 solicitações por minuto. BYOK usa uma chave de provedor configurada no gateway em vez de um modelo AIVAX integrado, mas as requisições ainda passam pela infraestrutura AIVAX e utilizam o limite BYOK do plano. As cotas de classificação de texto e segmentação de texto contam cada item no array `documents` da requisição, não cada requisição HTTP. Uma requisição que excederia qualquer janela ativa retorna `429 Too Many Requests`. A classificação de texto usa o modelo de incorporação padrão e é cobrada pelo trabalho de incorporação realizado. Solicitações autônomas de texto para fala e transcrição de áudio usam suas próprias cotas de requisição do plano. Sessões de voz utilizam o modelo em tempo real selecionado e estão sujeitas aos limites de acesso ao modelo, saldo e inferência aplicáveis, em vez dessas cotas de requisição autônomas. A transcrição de entrada não é suportada atualmente dentro de Sessões de voz. O endpoint de importação JSONL rejeita uma requisição quando atinge o limite de documentos por requisição do plano. O limite de reordenação aplica‑se ao endpoint autônomo de reordenação e às buscas RAG que utilizam um reordenador, incluindo buscas realizadas através de AI Gateways e ferramentas MCP. O limite de Reflex conta o tempo gasto processando requisições Reflex. Ele aplica‑se ao endpoint autônomo de reordenação e às buscas RAG que utilizam Reflex; entrada em cache não consome a cota separadamente. Requisições que excedem o limite do plano retornam `429 Too Many Requests`. Veja [Reflex](https://docs.aivax.net/pt-br/docs/rag/reflex.md) para limites de requisição, comportamento de cache e preços. Ações gerais de serviço compartilham a cota de ação de serviço mostrada acima. O processamento em lote é assíncrono; se o processamento for pausado ou falhar por causa de cota, tente novamente após a janela de cota ser redefinida ou faça upgrade da conta. ## Chaves de API públicas Chaves públicas têm limites adicionais independentes do plano da conta. | Escopo | Limites de requisição | | --- | --- | | Por endereço remoto | 3/5s, 20/min, 300/hora, 1.000/dia | | Global por chave | 10/5s, 60/min, 1.500/hora, 10.000/dia | | Escopo | Limites de token | | --- | --- | | Por endereço remoto | 100.000/5min, 500.000/30min, 2.000.000/6h, 5.000.000/dia | | Global por chave | 500.000/5min, 2.000.000/30min, 10.000.000/6h, 25.000.000/dia | Chaves públicas podem ser usadas para busca semântica RAG, geração de respostas RAG, geração de fala, descrições de mídia, geração de imagens e complementos de chat. Para complementos de chat, chaves públicas também exigem um UUID completo de AI Gateway, restringem parâmetros de requisição e omitam superfícies de ferramentas no lado do servidor. Consulte [Authentication](https://docs.aivax.net/pt-br/docs/authentication.md). --- Source: https://docs.aivax.net/pt-br/docs/data-collecting.html # Coleta de Dados AIVAX oferece um programa opcional de coleta de dados semânticos para contas que optam por contribuir com dados elegíveis de RAG e reclassificação para o desenvolvimento do modelo. Indexação e armazenamento de documentos estão fora deste programa. Todos os registros de RAG e reclassificação coletados são anonimados antes de serem gravados no conjunto de dados de treinamento. A configuração está desativada por padrão e deve ser ativada por um Gerente de Conta autorizado. ## O que muda quando a coleta está ativada Enquanto a configuração está ativada: - o uso elegível de incorporação de consulta RAG recebe um desconto de 10 %; - as operações elegíveis de reclassificação recebem um desconto de 10 %; e - a indexação de documentos, armazenamento, inferência não relacionada, ferramentas e outros serviços mantêm seus preços normais. O desconto se aplica apenas às operações elegíveis realizadas enquanto a coleta está ativada. Desativar a coleta remove o desconto das operações futuras. ## Dados incluídos Dependendo da operação, a AIVAX pode coletar: | Operação | Dados coletados | | --- | --- | | Busca semântica RAG | Termos de consulta, reclassificador selecionado e o conteúdo e as pontuações de relevância dos documentos retornados. | | Reclassificação | Consulta, documentos submetidos, reclassificador selecionado e resultados de classificação. Metadados de resposta desconhecidos e informações de uso ou faturamento não são incluídos. | O conjunto de dados anonimizado não armazena o ID da conta, chave de API, ID da solicitação, IDs de coleção ou documento, nomes de documentos, dados de faturamento ou marca temporal da coleta. A conta é consultada de forma transitória apenas para verificar se a coleta está ativada e aplicar o desconto da operação elegível. A indexação de documentos e as coleções armazenadas nunca são copiadas para o conjunto de dados de treinamento por este programa; o conteúdo do documento é incluído apenas quando submetido para reclassificação ou retornado por uma busca RAG. Habilitar esta configuração não inclui, por si só, respostas de chat não relacionadas, conversas, chamadas de ferramentas ou outros recursos da conta no conjunto de dados de treinamento. ## Propósito e uso A AIVAX pode usar os dados coletados para desenvolver, treinar, ajustar, avaliar, testar e melhorar modelos e sistemas relacionados a incorporações, recuperação, classificação, reclassificação e outro processamento semântico. Isso pode incluir a preparação de conjuntos de dados, anotação ou transformação de registros, medição de qualidade e produção de artefatos agregados ou derivados. O acesso é limitado a pessoal autorizado e provedores de serviço que suportam esses fins sob obrigações aplicáveis de confidencialidade e proteção de dados. A AIVAX não vende dados semânticos coletados nem mantém um mapeamento conta‑para‑registro para este conjunto de dados. ## Responsabilidades do Gerente de Conta Antes de habilitar a coleta, o Gerente de Conta deve: - ter autoridade para aceitar estas condições para a conta; - possuir uma base legal adequada para que a AIVAX use os dados submetidos para os fins acima; - fornecer quaisquer avisos e obter as permissões ou consentimentos necessários dos usuários finais ou de outros titulares de dados; e - evitar submeter credenciais, segredos, dados regulados ou dados pessoais sensíveis, a menos que sua coleta e uso sejam legalmente permitidos e necessários. ## Habilitar, desativar e excluir O Gerente de Conta pode controlar a coleta em **Dashboard > My account > Semantic data collection**. - A configuração está desativada por padrão. - Habilitá‑la autoriza a coleta anonimizada de futuras operações elegíveis de RAG e reclassificação. - Desativá‑la interrompe a coleta nova e encerra o desconto para operações futuras. - Desativá‑la não exclui automaticamente os registros coletados enquanto o consentimento estava ativo nem reverte o treinamento já concluído. Como identificadores de conta e mapeamentos conta‑para‑registro não são armazenados, a AIVAX não pode recuperar ou excluir registros de treinamento apenas a partir de um ID de conta. Solicitações referentes a dados pessoais presentes em conteúdo semântico submetido podem ser enviadas para **privacy@aivax.net** ou **wm@aivax.net** e devem incluir informações suficientes para localizar o conteúdo, quando aplicável. Registros de origem são mantidos apenas pelo tempo razoavelmente necessário para os fins documentados, obrigações legais, segurança e requisitos de auditoria, e podem ser excluídos posteriormente. A exclusão de registros de origem não exige que a AIVAX re‑treine ou destrua modelos ou artefatos agregados que não identifiquem mais uma pessoa, exceto quando exigido por lei aplicável. Consulte a [Política de Privacidade](https://docs.aivax.net/pt-br/docs/legal/privacy-policy.md) e os [Termos de Uso](https://docs.aivax.net/pt-br/docs/legal/terms-of-service.md) para os termos legais vigentes. --- Source: https://docs.aivax.net/pt-br/docs/changelogs.html # Registros de alterações Alterações técnicas que afetam produtos, serviços ou a API pública da AIVAX. As datas identificam quando as entradas foram adicionadas ou atualizadas, não as datas confirmadas de implantação em produção. Cada item identifica o produto ou serviço afetado; manutenção sem efeito visível ao usuário é omitida. ## Segunda-feira, 28 de setembro de 2026 ### Correções: - **Gateways — Ajuda da ferramenta Bash aceita parâmetros anuláveis.** Solicitar ajuda para ferramentas cujos parâmetros aceitam múltiplos tipos, incluindo `null`, não falha mais ao listar seus argumentos. A ajuda preserva os tipos aceitos e os caminhos de parâmetros aninhados. Nenhuma mudança no esquema da ferramenta é necessária. - **Integrações de chat — Notificações de falha restauradas.** Conversas em streaming e não streaming novamente tentam enviar “System: something went wrong. Please, try again later.” após uma falha de geração irrecuperável, tentativas de recuperação esgotadas ou um turno que não envia mensagem. Uma falha final é relatada mesmo se uma resposta parcial anterior foi entregue. A entrega de notificações ainda depende da disponibilidade do serviço de mensagens. ### Alterações: - **Gateways — Seleção de fuso horário.** A configuração de data e hora atual agora oferece um menu suspenso de fusos horários agrupados por região, incluindo UTC. Os fusos horários salvos existentes são preservados ao reabrir a configuração. - **Modelos — Sete novos modelos de texto.** Adiciona `@cohere/command-a-plus`, `@upstage/solar-mini4`, `@aion-labs/aion-3.5`, `@aion-labs/aion-3.5-mini`, `@qwen/qwen3.8-max-prime`, `@z-ai/glm-5.3-prime` e `@fireworks/ember-1` como modelos de texto selecionáveis, cobrados por provedor nas taxas de token publicadas com ajustes de conta e plano existentes ainda aplicados. Modelos Upstage e Fireworks agora exibem seus ícones de provedor ao invés do genérico. Identificadores de modelo existentes permanecem inalterados. ## Domingo, 27 de setembro de 2026 ### Alterações: - **Telegram — Progresso de ferramenta compacto.** Respostas em streaming mostram apenas o último preâmbulo da ferramenta no indicador de pensamento quando a visibilidade de chamada de ferramenta está habilitada, em vez de acumular blocos de nomes de ferramentas na resposta. A resposta final não contém blocos de progresso de ferramenta. Outros canais de mensagem e respostas não em streaming permanecem inalterados. - **Gateways — Seleção de ferramenta Bash.** A lista de ferramentas Bash agora inclui um atalho para `get_date_time` (Data e hora atuais). Listas de inclusão e exclusão aceitam padrões curinga sem distinção de maiúsculas/minúsculas: `*` corresponde a qualquer número de caracteres, como em `something_*`, e `?` corresponde a um caractere. Nomes de ferramentas exatos permanecem suportados. - **Decisões semânticas e Testes Agentes — Limites de taxa da conta.** Decisões semânticas permitem 10 solicitações por minuto no Free e 50 no Pro. Testes Agentes permitem 5 novas execuções por minuto no Free e 30 no Pro, compartilhadas entre execuções manuais, programadas e avaliações diretas. Max não tem limite imposto por plano para nenhuma operação. Solicitações diretas acima desses limites retornam HTTP 429; testes programados aguardam uma verificação de agendamento posterior. Clientes devem espaçar solicitações e tentar novamente após o término da janela de limite de taxa. Limites de inferência existentes ainda se aplicam. Consulte [Planos e Limites](https://docs.aivax.net/pt-br/docs/limits.md#semantic-decision-and-agentic-test-rate-limits), [Decisões semânticas](https://docs.aivax.net/pt-br/docs/generations/decisions.md#account-rate-limits) e [Testes Agentes](https://docs.aivax.net/pt-br/docs/inference/agentic-tests.md#run-and-inspect-a-test). - **Modelos — Preços consistentes de síntese de fala.** Os preços do catálogo de texto-para-fala agora derivam das mesmas taxas por caractere usadas para calcular o uso de síntese, exibidos por 1.000 caracteres. Identificadores de modelo existentes e taxas de faturamento permanecem inalterados. - **Modelos — Preços comparáveis de transcrição.** Os preços dos modelos de fala-para-texto são exibidos consistentemente em USD por minuto, convertendo taxas horárias e por segundo para comparação sem alterar as taxas de faturamento ou a medição de duração. - **Geração de imagem — Preços fixos de saída e referência.** A geração de imagem usa um preço fixo por saída entregue mais um preço por referência para cada saída. Modelos cujos provedores cobram tokens ou megapixels agora usam estimativas arredondadas para cima ao invés de cobranças de token medidos. O processamento do prompt está incluído na estimativa de saída; modelos sem taxa de referência separada listam taxa de referência zero. Estes são tarifas fixas, não recibos do consumo real do provedor. As cobranças de imagem não incluem mais a marcação de geração de imagem da AIVAX nem os multiplicadores de preço de conta e plano. Consulte [Geração de imagem](https://docs.aivax.net/pt-br/docs/generations/images.md). - **Modelos — Cobertura de assinatura.** A página de Modelos agora inclui uma coluna “Uso da Assinatura” para rerankers e modelos de decisão semântica. “Incluído” identifica modelos elegíveis para as cotas diárias do plano; “Excluído” identifica modelos sem cobertura. Elegibilidade não indica a cota restante da conta. Ambos os catálogos de serviço expõem essa elegibilidade como `subscriptionUsage`. - **Assinaturas — Cotas diárias incluídas.** As assinaturas Free, Pro e Max incluem cotas diárias para buscas RAG e embeddings de inserção, tokens de entrada Reflex (incluindo tokens de entrada em cache) e tokens de entrada de Decisores Semânticos usando apenas Julia-1. Cada item de serviço medido é totalmente incluído se seu consumo cabe na cota mais uma margem de 10%; caso contrário, o item inteiro é cobrado nas taxas normais sem consumir a cota. Uma solicitação pode conter múltiplos itens, como embeddings de termos de consulta separados, e pode combinar uso incluído e pago. Essa regra tudo-ou-nada também se aplica à extração OCR, substituindo cobertura parcial. Itens de serviço cobertos aparecem no consumo da assinatura, sem criar entradas de histórico de faturamento de custo zero; itens não cobertos mantêm registros de faturamento normais. A cota Julia-1 do plano Free é aumentada quatro vezes; o Pro agora inclui 2,5× a cota de decisão Free, e o Max inclui 2× Pro. O uso pode mostrar mais de 100% dentro da margem permitida. As informações de faturamento da conta agora derivam `includesSubscriptionModels` das cotas de inferência ativas, portanto é falso enquanto as assinaturas de inferência estão desativadas. O limite diário de tempo de processamento do Reflex permanece um limite técnico separado; contas de revendedores não recebem cotas de assinatura. Comparações de planos na documentação e na página de preços pública mostram capacidade de cota relativa ao invés de unidades absolutas. A cobertura de assinatura LLM permanece desativada. Consulte [Planos e Limites](https://docs.aivax.net/pt-br/docs/limits.md). ## Sábado, 26 de setembro de 2026 ### Alterações críticas: - **Geração de imagem — Modelos obsoletos removidos.** Remove `majicMIX-realistic`, `AbsoluteReality`, `CyberRealistic`, `CyberRealistic-Pony`, `RealCartoon-Realistic`, `Hassaku-XL` e `Meina-Mix` dos modelos disponíveis. Solicitações de API diretas usando esses identificadores agora falham; selecione um modelo ativo. A geração de imagem embutida usa `flux-schnell` quando nenhum modelo válido está configurado, substituindo o padrão obsoleto `AbsoluteReality`. Revise as configurações salvas; estilo de saída e preços diferem. ### Alterações: - **Geração de imagem — Modelos adicionais Pollinations.** Adiciona 16 modelos oficiais de imagem raster, incluindo variantes FLUX 1.1 Pro e FLUX 2, variantes MAI Image, GPT Image 2.5 Flare e Sunburst, Qwen Image 2.1 e 3, Grok Imagine Image 2.0, Recraft V4.1 Flash, Krea 2 Medium, DreamShaper 8 LCM e Seedream 5 Pro, com pré-visualizações geradas pelo modelo no seletor de imagens. Modelos da comunidade e SVG são excluídos. O catálogo exibe as unidades de faturamento. Consulte a entrada de 27 de setembro para a mudança subsequente de faturamento de preço fixo. Gerações falhas não são contadas como imagens entregues. Consulte [Geração de imagem](https://docs.aivax.net/pt-br/docs/generations/images.md). - **Modelos — Catálogos de modelos de serviço.** A página de Modelos agora inclui tabelas para geração de imagem, fala-para-texto, texto-para-fala, reranking e decisões semânticas, com descrições fornecidas pelo backend, datas de lançamento, preços base em USD com unidades de faturamento e um menu suspenso de Ações em cada tabela de modelo de serviço para copiar nomes de modelo e abrir documentação de integração. Nomes de modelo exibem um rótulo amigável quando disponível ao copiar o identificador aceito pela API. O preço usa unidades de entrada compacta, entrada em cache, saída, imagem, caractere e duração separados por setas quando aplicável, com taxas completas e unidades disponíveis na dica de ferramenta. Os catálogos são ordenados do mais recente ao mais antigo. Datas e nomes amigáveis do catálogo OpenRouter complementam metadados de lançamento ausentes; datas de catálogo são rotuladas explicitamente ao invés de apresentadas como datas de lançamento do fabricante. Modelos sem nenhuma data permanecem últimos. Solicitações de catálogo falhas podem ser repetidas independentemente. Os catálogos de informações públicas expõem esses detalhes, incluindo o novo catálogo `GET /api/v1/information/speech-models.json`. Ajustes de preço de conta e plano ainda se aplicam. Consulte [Preços](https://docs.aivax.net/pt-br/docs/pricing.md) e [Decisões semânticas](https://docs.aivax.net/pt-br/docs/generations/decisions.md). - **Privacidade — Divulgação judicial e retenção esclarecidas.** A [Política de Privacidade](https://docs.aivax.net/pt-br/docs/legal/privacy-policy.md) e os [Termos de Uso](https://docs.aivax.net/pt-br/docs/legal/terms-of-service.md) especificam ordens judiciais brasileiras para divulgação, solicitações estrangeiras para preservar logs existentes por até 1 ano, e até 1 ano de logs técnicos e metadados. Elas esclarecem que o conteúdo da conversa é coletado somente quando Conversas está habilitado para a solicitação ou conta, e que recursos de conta disponíveis e backups de até 3 meses podem ser divulgados sob ordem judicial brasileira. A licença de conteúdo nos Termos está expressamente sujeita a esses limites. - **Gerações — Modelos de decisão adicionais.** O novo [guia de decisões semânticas](https://docs.aivax.net/pt-br/docs/generations/decisions.md) explica tipos de perguntas, interpretação de respostas, preços de modelo e limites Julia-1. O ponto de extremidade público `GET /api/v1/information/decisions-models.json` lista nomes canônicos, aliases, tipos de perguntas suportados, comprimentos de contexto, datas de lançamento e preços base de tokens. Adiciona `@respan/span-01`, `@respan/span-01-lite`, `@jaredpalmer/kev-4b` e `@supersonic-labs/julia-1` como opções de modelo para decisões semânticas. Julia-1 suporta `choice`, `score` e `noul`, com um contexto combinado de 1.024 tokens por pergunta e 2–20 opções ou níveis de pontuação. Seu preço base é $0,008 por milhão de tokens de entrada, sem cobrança de token de saída; ajustes de preço de conta e plano existentes ainda se aplicam. O uso de entrada inclui o estado repetido para cada pergunta. Identificadores de modelo existentes e formatos de solicitação permanecem inalterados. ## Terça-feira, 22 de setembro de 2026 ### Alterações: - **Modelos — GPT-6 Sol e Luna adicionados.** Adiciona `@openai/gpt-6-sol` e `@openai/gpt-6-luna`, incluindo suas variantes de raciocínio `:pro`. Os aliases `@model-router/openai:mid` e `@model-router/openai:budget` agora selecionam GPT-6 Sol e GPT-6 Luna, respectivamente. Aplicações que usam esses aliases podem observar mudanças na qualidade da resposta, latência e custo. Identificadores de modelo explícitos existentes permanecem inalterados. ## Segunda-feira, 21 de setembro de 2026 ### Alterações críticas: - **Gateways — Moderação fora de tópico está sendo removida.** O limite dedicado fora de tópico não bloqueará mais solicitações que se desviem do propósito da conversa. Se sua aplicação depende dessa verificação, revise suas restrições de tópico antes de adotar esta mudança; as categorias de moderação restantes não são um substituto equivalente. - **Ferramentas embutidas — Pesquisa avançada na web está sendo desativada.** A ferramenta `AdvancedWebUsage` retornará uma resposta indisponível ao invés de realizar pesquisa. Remova a dependência desta ferramenta das instruções e fluxos de gateway. A [Busca na Web](https://docs.aivax.net/pt-br/docs/web-foundation/web-search.md) padrão e a extração de URL permanecem alternativas separadas, não substitutos equivalentes para pesquisa em múltiplas etapas. - **Modelos — Identificador do modelo Mercury 2.5 alterado.** Substitua `@inception/mercury-2.5-preview` por `@inception/mercury-2.5` nas solicitações e configurações de gateway. O identificador de pré-visualização não está mais listado, e o substituto não está mais marcado como pré-visualização. - **Gateways / MCP — Nomes de ferramentas MCP são qualificados pela fonte.** Ferramentas de diferentes fontes MCP não compartilham mais um nome não qualificado no gateway. Revise as instruções de gateway, regras de seleção de ferramentas e workers que correspondem a nomes de ferramentas exatos. O nome original da ferramenta no servidor MCP conectado permanece inalterado. Consulte [funções MCP](https://docs.aivax.net/pt-br/docs/tools/mcp.md). ### Correções: - **Coleções, Gateways e Gerações — Disponibilidade de modelo de serviço.** Geração de respostas de coleção, roteamento de gateway, utilidades de chat e serviços de processamento de mídia evitam selecionar modelos temporariamente indisponíveis. Teach Skill e pré-processamento multimodal podem tentar outro modelo disponível após uma falha recuperável; o sucesso ainda depende da disponibilidade do serviço. - **Teach Skill — Cálculo de uso.** As cobranças de processamento do Teach Skill usam o preço do modelo associado à solicitação concluída, inclusive quando uma tentativa altera o modelo usado. Consulte [Teach Skill](https://docs.aivax.net/pt-br/docs/generations/teach-skill.md) e [Preços](https://docs.aivax.net/pt-br/docs/pricing.md). - **Fetch and OCR — Extração de página mais confiável.** Solicitações de conteúdo de página canceladas ou com tempo esgotado não deixam mais a extração de página em execução indefinidamente. Isso resolve casos em que a extração de conteúdo da web poderia travar. - **Clientes de chat — Resposta final e histórico de mensagens.** `completionText` agora seleciona a resposta final gerada pelo assistente ao invés de combiná-la com texto anterior do assistente durante o uso da ferramenta. O campo de resposta `createdMessages` adicionado preserva as mensagens recém-geradas em ordem, incluindo interações de ferramenta; mensagens enviadas não são repetidas. Use este campo quando precisar da rodada completa gerada. - **Gateways / MCP — Resultados estruturados MCP são mantidos.** Assistentes recebem conteúdo de resultado estruturado além dos blocos de conteúdo suportados, evitando informações ausentes quando uma ferramenta MCP retorna saída estruturada. - **Fetch and OCR — Extração de post X.** Extração de texto legível aprimorada de links públicos de post X. Disponibilidade de conteúdo e restrições de acesso ainda se aplicam. - **Fetch and OCR — Normalização de texto simples alterada.** A conversão para texto simples não colapsa mais espaços internos nem normaliza caracteres Unicode. Espaços ao redor ainda podem ser removidos nos resultados de extração. Aplicações que comparam texto extraído exatamente ou requerem espaçamento normalizado devem realizar essa normalização por conta própria. ### Alterações: - **Fetch and OCR — Extração estruturada opcional.** Forneça `responseSchema` para converter o conteúdo extraído em JSON. Os resultados adicionam `extractedObject` e `jsonProcessingUnits` enquanto retêm `extractedText` em caso de sucesso. Sem um esquema, os novos campos são nulos e zero respectivamente. A conversão JSON é cobrada separadamente da extração e não está coberta pela cota diária de extração. Consulte [Fetch and OCR](https://docs.aivax.net/pt-br/docs/web-foundation/fetch-and-ocr.md). - **Gerações — Decisões semânticas.** Avalie múltiplas perguntas nomeadas contra um estado JSON compartilhado usando `noul` (critério verdadeiro/falso), `choice` ou `score`. As respostas incluem respostas nomeadas, uso de tokens e custo. O serviço requer saldo positivo, e seu uso de tokens contribui para os totais de uso da conta. - **Ferramentas embutidas — Data e hora atuais.** A opção `DateTime` permite que assistentes solicitem a data, hora, dia da semana, fuso horário e deslocamento UTC atuais. Defina `dateTimeTimeZone` para o fuso horário desejado; o padrão é `America/Los_Angeles`, com ajustes de horário de verão, independente do fuso horário do navegador. Fusos horários inválidos são rejeitados. - **Modelos — Opções de modelo adicionais.** Adiciona GLM-5.3-FlashX, Fugu Max, Pareto, Ling 3.0 Flash VL, MiMo-V2.6-Pro, MiMo-V2.6-Flash, MiMo-V2.6-Pro-UltraSpeed e Grok 4.7 ao catálogo de inferência. Os aliases Xiaomi frontier, mid e budget agora selecionam modelos MiMo V2.6, enquanto `@model-router/grok:latest` seleciona Grok 4.7. Usuários de alias podem observar diferentes qualidade de resposta, latência e custo; disponibilidade e capacidades suportadas dependem do modelo selecionado e do plano da conta. - **Inferência — Recuperação de falhas transitórias.** Solicitações de inferência podem fazer tentativas de recuperação adicionais quando um provedor está temporariamente indisponível. Isso pode evitar algumas solicitações falhas, mas também pode aumentar o tempo de resposta antes que um erro seja retornado. - **Assistente Avi — Modelo padrão atualizado.** O assistente do console AIVAX altera seu modelo padrão, o que pode mudar o estilo de resposta, latência e custo de uso. Isso não altera o modelo selecionado em seus próprios gateways. - **Documentação — Orientação de serviço atualizada.** A visão geral da documentação da API e a orientação do Assistente Avi cobrem sessões de voz, testes agentes, classificação, segmentação, reranking e extração web, com links de documentação atuais e orientação de faturamento específica por serviço. Esta é uma atualização de orientação, não a introdução desses serviços. - **Modelos — DeepSeek V4.1 Flash adicionado.** O catálogo de inferência inclui `@deepseek/deepseek-v4.1-flash` com suporte a chamadas de ferramenta. Verifique a disponibilidade do modelo e elegibilidade do plano antes de selecioná-lo. - **Modelos — Seleções de roteador atualizadas.** `@model-router/deepseek:latest` e `@model-router/deepseek:budget` agora selecionam DeepSeek V4.1 Flash. Aplicações que usam esses aliases podem observar diferentes qualidade de resposta, latência e custo sem mudar o alias. Adiciona `@model-router/claude:frontier-mythos` e `@model-router/mercury:latest` como opções adicionais. - **Clientes de chat — Entrada de prompt estruturada.** Prompts síncronos de cliente de chat aceitam texto simples, uma única mensagem ou um array ordenado de mensagens, incluindo chamadas de ferramenta do assistente e resultados de ferramenta correspondentes. A entrada de mensagem única existente permanece suportada. `instructions` opcional adiciona contexto para aquela solicitação sem substituir o contexto de sessão salvo. Consulte [Clientes de chat](https://docs.aivax.net/pt-br/docs/features/chat-clients.md). - **Clientes de chat — Turnos sem persistência de sessão.** Defina `commit` como false para gerar uma resposta sem salvar as mensagens enviadas e geradas no histórico da sessão. O padrão permanece true. Isso não é uma prévia gratuita: inferência e ações de ferramenta ainda são executadas. Para continuar uma interação de ferramenta não confirmada, envie a mensagem de chamada de ferramenta do assistente junto com seus resultados de ferramenta. - **Testes Agentes — Notificações de teste opcionais.** As preferências de notificação da conta podem habilitar resumos semanais de teste e alertas quando um teste atinge três falhas consecutivas. Isso complementa as notificações de falha e recuperação existentes. Consulte [Testes Agentes](https://docs.aivax.net/pt-br/docs/inference/agentic-tests.md). - **Fetch and OCR — Conteúdo web renderizado.** A extração de HTML suporta conteúdo de página renderizado, melhorando a cobertura de páginas cujo texto legível depende de scripts. A renderização é medida em unidades de processamento; isso não garante acesso a todos os sites ou páginas restritas. Consulte [Fetch and OCR](https://docs.aivax.net/pt-br/docs/web-foundation/fetch-and-ocr.md). --- Source: https://docs.aivax.net/pt-br/docs/rag/collections.html # Coleções e Documentos AIVAX fornece um serviço RAG (Retrieval-Augmented Generation) para armazenar documentos e recuperá-los posteriormente através de busca semântica. Uma coleção é um grupo de documentos pertencente a uma conta. Cada documento armazena texto, tags opcionais, uma referência opcional, metadados opcionais e os vetores gerados pelo trabalho de indexação. Coleções podem ser pesquisadas diretamente através da API RAG ou anexadas a um AI Gateway para que os documentos recuperados sejam injetados no contexto do modelo. ## Coleções Use coleções para agrupar documentos que pertencem à mesma base de conhecimento, produto, locatário, idioma ou propósito operacional. Uma coleção é o contêiner que você cria antes de adicionar conhecimento pesquisável. Pense nela como o limite de uma base de conhecimento: uma coleção de suporte pode conter respostas do centro de ajuda, uma coleção jurídica pode conter cláusulas de contrato e uma coleção de produto pode conter descrições, políticas e notas de solução de problemas. Mais tarde, você pode pesquisar a coleção diretamente com a API de [Busca Semântica](https://docs.aivax.net/pt-br/docs/rag/semantic-search.md), expô-la através de [Collections MCP](https://docs.aivax.net/pt-br/docs/mcp-utilities/collections-mcp.md) ou anexá-la a um [AI Gateway](https://docs.aivax.net/pt-br/docs/inference/ai-gateway.md) para que os documentos recuperados sejam inseridos automaticamente no contexto do modelo. Cada coleção tem: - Um ID de coleção exclusivo. - Um nome. - Contexto opcional e tags contextuais. - Um conjunto de documentos. - Estatísticas de uso baseadas em transações RAG. A disponibilidade da coleção e os limites da conta dependem da configuração atual da conta. Consulte [Planos e limites](https://docs.aivax.net/pt-br/docs/limits.md) antes de criar coleções para uso em produção. ## Documentos Um documento é a unidade que é indexada e recuperada. Ele deve ser pequeno o suficiente para corresponder a uma pergunta específica e completo o suficiente para ser útil por si só. Esta é a parte que mais afeta a qualidade do RAG. Um documento não deve ser "tudo que você sabe" sobre uma fonte; deve ser um pedaço de conhecimento que pode ficar sozinho quando o modelo o lê posteriormente. Se um usuário perguntar sobre taxas de cancelamento, o documento recuperado já deve conter a regra, o produto, a condição e a exceção relevantes. Se a resposta só fizer sentido quando o modelo também vir a página anterior, o documento provavelmente depende demais do contexto ao redor. Um bom documento geralmente tem: - Um nome estável. - Texto focado. - Tags opcionais para filtragem ou manutenção. - Metadados opcionais para dados específicos da aplicação. - Um ID de referência opcional quando o documento é um fragmento de um item lógico maior. Por exemplo, um manual de carro não deve ser indexado como um único documento. Indexe documentos separados para tópicos como iniciar o veículo, verificar a pressão dos pneus, emparelhar Bluetooth e substituir um farol. Cada documento deve incluir contexto suficiente para ser lido de forma independente. Para orientações mais amplas sobre fragmentação, consulte [Melhores Práticas para RAG](https://docs.aivax.net/pt-br/docs/rag/best-practices.md); para comportamento de consulta após indexação, veja [Busca Semântica](https://docs.aivax.net/pt-br/docs/rag/semantic-search.md). ## Campos do Documento Ao importar documentos em JSONL, cada linha representa um documento que pode ser criado ou atualizado. O campo importante é `docid`: é o nome estável que a AIVAX usa para reconhecer o mesmo documento em importações futuras. Se você enviar o mesmo `docid` novamente com texto diferente, o documento existente será atualizado e reindexado. Se você precisar apenas preservar dados adicionais da aplicação, use `__meta` em vez de misturar esses dados no texto pesquisável. O endpoint de importação JSONL aceita um objeto JSON por linha: | Propriedade | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `docid` | `string` | Yes | Nome de documento estável. Documentos existentes são correspondidos por este valor. | | `text` | `string` | Yes | Conteúdo de texto para indexação semântica. | | `__ref` | `string` | No | ID de referência usado para agrupar fragmentos relacionados. Comprimento máximo armazenado é 64 caracteres. | | `__tags` | `string[]` | No | Tags para filtragem, navegação e manutenção. | | `__meta` | `object` | No | Metadados retornados com detalhes do documento e resultados de busca. Metadados não são o texto semântico usado para embeddings. | O nome do documento deve ser não vazio e está limitado pela API a 256 caracteres. O conteúdo armazenado do documento é obrigatório e não pode estar vazio. ## Inserções e Reindexação Documentos são correspondidos pelo nome (`docid` em JSONL, `Name` na API de documento único). Quando um documento é criado, ele é colocado na fila para indexação. Quando o texto de um documento existente muda, o documento é colocado novamente na fila e seus vetores são regenerados pelo indexador em segundo plano. Quando apenas `__meta` muda, os metadados são atualizados sem reindexar o texto do documento. Os valores de referência e tags são armazenados com o documento. Na API de documento único, referência, tags ou metadados alterados podem atualizar um documento existente sem reindexar quando o texto permanece inalterado. No endpoint de importação JSONL, texto alterado coloca na fila a reindexação, alterações apenas de metadados atualizam os metadados sem reindexar, e texto alterado também pode atualizar referência, tags e metadados. ## Referências Use `__ref` quando múltiplos documentos representam partes da mesma fonte lógica, como por exemplo: - Seções do mesmo contrato. - Cláusulas da mesma política. - Fragmentos do mesmo PDF. - Fragmentos de produto que devem ser mostrados juntos. Quando a expansão de referência de busca está habilitada, se um fragmento corresponder, outros documentos na mesma coleção com a mesma referência podem ser incluídos na resposta. ## Importação de Arquivo de Mídia O painel da AIVAX pode fazer upload de um arquivo de origem e processá-lo em documentos RAG com [Media Injector](https://docs.aivax.net/pt-br/docs/rag/media-injector.md). Use-o quando você tem um arquivo de origem mas ainda não tem texto de documento focado e autocontido preparado para importação direta ou JSONL. O nome original do arquivo é normalizado para Unicode NFC e preservado durante o upload, incluindo letras acentuadas, scripts não latinos, pontuação tipográfica e outros caracteres Unicode. Você não precisa renomear um arquivo para um nome apenas ASCII antes de importá-lo. Um trabalho do Media Injector é criado somente depois que cada fragmento do arquivo foi carregado e o painel conclui o upload com sucesso. Você pode então acompanhá-lo em **Batch > Media Processing**. Se nenhum trabalho aparecer, o upload não chegou à etapa de conclusão; tente novamente o upload e verifique o erro exibido pelo painel. ## Limites de Importação em Lote A importação em lote é enviada como um arquivo JSONL no campo multipart `documents`. Use a importação em lote quando você já tem muitos documentos preparados fora da AIVAX, como fragmentos gerados a partir de PDFs, catálogos de produtos, políticas ou artigos do centro de ajuda. Se você está criando ou atualizando um documento a partir de um fluxo de aplicação, o endpoint de documento único abaixo costuma ser mais fácil. Se você está preparando uma grande base de conhecimento, importe em lotes, aguarde a indexação e então teste a recuperação através da [Busca Semântica](https://docs.aivax.net/pt-br/docs/rag/semantic-search.md) antes de anexar a coleção a um gateway de produção. Os limites atuais eficazes de linhas JSONL por requisição são: | Plano | Máximo de linhas JSONL por requisição | | --- | --- | | Free | 999 | | Pro | 9,999 | | Max | 999,999 | Os limites diários de inserção RAG são separados do limite de linhas por requisição: | Plano | Inserções RAG por dia | | --- | --- | | Free | 500 | | Pro | 10,000 | | Max | Não limitado pela configuração atual do plano | Se sua importação exceder o limite de requisição, divida-a em múltiplos arquivos. Se sua conta atingir o limite diário de inserção, aguarde o reset da janela de taxa ou faça upgrade do plano. > [!WARNING] > A indexação gera custo com base nos tokens de texto do documento quando documentos são criados ou quando seu texto muda. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Index%20Documents%20(JSONL)) ## Gerenciamento de Documentos ### Criar ou atualizar documento Este endpoint é útil quando sua aplicação gerencia documentos um de cada vez. Por exemplo, uma tela de administrador pode salvar uma entrada de FAQ, uma cláusula de política ou uma nota de produto diretamente em uma coleção. A AIVAX corresponde o documento pelo nome: texto alterado coloca na fila a reindexação, enquanto alterações apenas de metadados atualizam os metadados sem reindexar o conteúdo. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Create%20or%20Update%20Document) ### Listar documentos O endpoint de navegação ajuda você a inspecionar o que já está dentro de uma coleção. Use-o quando precisar verificar uma importação, encontrar um documento pelo nome, revisar documentos na fila versus indexados, ou filtrar conteúdo antes de decidir atualizar, excluir ou reimportar parte da base de conhecimento. Supported filters: - `-t "tag"`: documentos contendo a tag. - `-r "reference"`: documentos com o ID de referência exato. - `-c "content"`: documentos cujo conteúdo contém o trecho de texto. - `-n "name"`: documentos cujo nome contém o trecho de texto. - `-i "id"`: documentos cujo ID contém o texto fornecido. Supported states: - `queued`: documentos aguardando indexação. - `indexed`: documentos já indexados. Supported sort values: - `created_at_asce` - `created_at_desc` - `updated_at_asce` - `updated_at_desc` - `indexed_at_asce` - `indexed_at_desc` [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Browse%20Documents) --- Source: https://docs.aivax.net/pt-br/docs/rag/media-injector.html # Injetor de Mídia O Injetor de Mídia transforma um arquivo de origem em documentos focados e autônomos dentro de uma coleção RAG da AIVAX. Ele examina a origem, identifica conhecimento materialmente útil, redige documentos factuais concisos no idioma predominante da origem e coloca esses documentos em fila para indexação semântica. Use o Injetor de Mídia quando você tem um arquivo cujo conhecimento útil ainda não foi dividido em texto pronto para recuperação. Se já possuir strings de documento limpas, use [Create or Update Document or JSONL import](https://docs.aivax.net/pt-br/docs/rag/collections.md#document-fields) em vez disso; esses caminhos são mais previsíveis e evitam o processamento adicional necessário para interpretar um arquivo de origem. ## Quando usar O Injetor de Mídia é útil para: - PDFs como relatórios, manuais e políticas que contêm vários tópicos independentes. - Imagens ou páginas digitalizadas cujo conteúdo visível deve se tornar conhecimento pesquisável. - Áudio e vídeo cujos fatos materiais devem estar disponíveis via RAG. Não é um recurso geral de armazenamento de arquivos e não preserva a origem como um único documento pesquisável. A saída é um conjunto de documentos RAG gerados. Revise esses documentos após o processamento quando a formulação, cobertura, fidelidade legal ou o tratamento de dados sensíveis for importante. Use a importação direta de documentos quando precisar da formulação exata da origem, limites determinísticos, nomes de documentos estáveis ou metadados controlados pela aplicação. Use [Text Segmentation](https://docs.aivax.net/pt-br/docs/rag/text-segmentation.md) quando precisar apenas de segmentos coesos de texto‑origem retornados à sua aplicação sem criar documentos de coleção. ## Como funciona a ingestão No painel da AIVAX: 1. Abra a coleção alvo e escolha **Import from files**. 2. Selecione um ou mais arquivos de origem. 3. Opcionalmente, forneça contexto de processamento. O mesmo contexto é aplicado a cada arquivo selecionado. 4. Confirme a importação. O painel carrega os arquivos sequencialmente e um trabalho separado é criado para cada arquivo após todos os seus blocos chegarem à AIVAX. 5. Acompanhe os trabalhos em **Batch > Media Processing**. 6. Após a conclusão de cada trabalho, revise os documentos gerados e aguarde seu estado de indexação antes de testar [Semantic Search](https://docs.aivax.net/pt-br/docs/rag/semantic-search.md). Um trabalho pode estar `queued`, `processing`, `completed`, `failed` ou `cancelled`. O painel relata o arquivo de origem, tempo decorrido, número de documentos produzidos e custo atual. Trabalhos falhados ou cancelados podem ser reexecutados quando seus dados enviados recuperáveis ainda estiverem disponíveis. Áudio e vídeo podem ser divididos em segmentos baseados no tempo para processamento. A segmentação é automática e não altera o nome original do arquivo exibido para o trabalho. Consulte [Plans and limits](https://docs.aivax.net/pt-br/docs/limits.md) para limites de upload atuais. ## Definir contexto de processamento O contexto de processamento é uma instrução opcional que ajuda o Injetor de Mídia a decidir quais fatos são mais valiosos para sua base de conhecimento. Ele é considerado juntamente com a origem, mas não é tratado como uma fonte factual e não pode acrescentar fatos que estejam ausentes no arquivo. Um bom contexto descreve: - A identidade e o propósito da origem. - O público que buscará a coleção. - Os tópicos, produtos, jurisdições, períodos ou áreas que são relevantes. - Rótulos ambíguos ou terminologia interna que a própria origem estabelece. - Conteúdo que deve ser despriorizado, como cabeçalhos repetidos ou textos administrativos padrão. ```text Esta é a política de suporte de 2026 para clientes da Acme Cloud no Brasil. Priorize regras de elegibilidade, prazos, diferenças de plano, exceções e os passos que um agente de suporte deve comunicar. Ignore cabeçalhos de página repetidos e blocos de assinatura. ``` Evite solicitar ao mecanismo que inferira conclusões, forneça informações ausentes ou use conhecimento externo. Por exemplo, não instrua‑o a decidir se um contrato é legalmente executável ou a calcular valores que a origem não relata. O contexto de processamento difere do contexto de uma coleção. O contexto de processamento orienta apenas esta importação. O contexto da coleção descreve a base de conhecimento para um AI Gateway quando a coleção é usada posteriormente. Coloque aqui orientações de ingestão específicas da origem; mantenha orientações duráveis de toda a coleção nas configurações da coleção. ## Tipos de origem aceitos O painel aceita quatro grupos de origem para o Injetor de Mídia: | Grupo de origem | Comportamento de processamento | | --- | --- | | Documentos PDF | Lê a estrutura do documento, texto e conteúdo visual relevante. | | Imagens | Interpreta texto visível e conteúdo para produzir documentos RAG textuais. | | Áudio | Interpreta fala e outros conteúdos auditivos relevantes; arquivos grandes são segmentados automaticamente. | | Vídeo | Interpreta conteúdo visual e auditivo relevante; arquivos grandes são segmentados automaticamente. | Use a extensão de arquivo original e precisa porque a AIVAX a utiliza para identificar o tipo de mídia. Uma extensão rotulada incorretamente pode selecionar o caminho de processamento errado ou fazer o trabalho falhar. O suporte a contêineres e codecs pode variar; se um arquivo de áudio ou vídeo falhar, converta‑o para um formato comum e tente novamente. ## Documentos gerados Cada item gerado foi projetado para ser uma unidade de conhecimento útil, em vez de uma transcrição página por página. O Injetor de Mídia: - Prioriza a identidade da origem, escopo, fatos principais, relacionamentos, exceções e distinções materiais. - Combina fatos estreitamente relacionados em vez de criar um documento por rótulo, célula de tabela ou valor repetido. - Ignora texto decorativo, paginação, resumos repetidos e metadados incidentais, a menos que alterem o significado. - Preserva o idioma, terminologia, datas exibidas e formatos numéricos da origem. - Para quando a origem não tem conhecimento materialmente novo para adicionar. Os documentos gerados são marcados para que possam ser identificados como conteúdo produzido automaticamente. Eles são então indexados como outros documentos da coleção e incidem no custo normal de incorporação de texto da coleção, além do processamento do Injetor de Mídia. Para orientações de qualidade de recuperação após a ingestão, veja [Best Practices for RAG](https://docs.aivax.net/pt-br/docs/rag/best-practices.md). Em particular, inspecione documentos gerados a partir de tabelas, digitalizações e fontes com layouts repetidos antes de confiar neles em produção. ## Uso, preços e limites O uso do Injetor de Mídia depende da origem, contexto opcional, perguntas e respostas geradas, reutilização de cache e tokens de mídia quando aplicável. A cobrança agrega entrada, entrada em cache, saída e uso de mídia para o trabalho de processamento sem expor o modelo de processamento subjacente. Consulte [Pricing](https://docs.aivax.net/pt-br/docs/pricing.md#media-injector) para as tarifas finais. A disponibilidade e os limites operacionais do Injetor de Mídia dependem da configuração da conta. Consulte [Pricing](https://docs.aivax.net/pt-br/docs/pricing.md) e [Plans and limits](https://docs.aivax.net/pt-br/docs/limits.md) antes de fazer upload de arquivos em produção. --- Source: https://docs.aivax.net/pt-br/docs/rag/semantic-search.html # Busca Semântica A API de busca semântica pesquisa uma ou mais coleções e retorna os documentos indexados mais relevantes para os termos de busca fornecidos. Se sua aplicação já possui as strings dos documentos candidatos, considere [Reflex](https://docs.aivax.net/pt-br/docs/rag/reflex.md): uma busca RAG sem coleção que classifica os documentos fornecidos sem indexação ou armazenamento. Use a busca semântica gerenciada quando a AIVAX precisar armazenar e pesquisar um corpus persistente ou quando o corpus for grande demais para ser enviado como candidatos em cada requisição. Após criar uma coleção, pesquise-a com termos completos que reflitam a pergunta que o usuário faria. A resposta pode incluir os documentos correspondentes e seus dados de coleção associados para uso em sua aplicação ou fluxo do AI Gateway. Para o contrato de requisição, resposta, autenticação e erro suportados, use a Referência da API: [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Semantic%20search) ## Reordenação Um reordenador pode ajustar a ordem dos candidatos retornados pela busca semântica. Ele não pesquisa documentos adicionais nem recupera texto que a fase de recuperação não selecionou. Consulte [Rerankers](https://docs.aivax.net/pt-br/docs/rag/reranking.md) para orientações de seleção. ## Múltiplos Termos Múltiplos termos cobrem caminhos de recuperação alternativos em vez de exigir que cada termo corresponda ao mesmo documento. Use-os para sinônimos, formulações alternativas ou várias maneiras aceitáveis de encontrar uma resposta. Se a intenção do usuário for uma ideia composta, envie essa ideia como um termo completo. Por exemplo, prefira: ```text How do I cancel an annual subscription without a penalty? ``` Em vez de palavras‑chave desconexas: ```text cancellation annual subscription penalty ``` ## Qualidade da Busca Uma consulta completa geralmente tem desempenho melhor do que uma lista de palavras‑chave desconexas porque preserva a relação entre os conceitos. Se a busca retornar resultados ruins: 1. Confirme que os documentos estão indexados. 2. Consulte a coleção diretamente antes de testar através de um AI Gateway. 3. Compare perguntas completas com formulações alternativas. 4. Verifique se o documento relevante é muito curto, muito longo ou não está autocontido. 5. Verifique se o idioma da consulta corresponde ao idioma do documento. 6. Se o gateway reescrever perguntas antes da busca, teste com o caminho de consulta simples para isolar problemas de reescrita. ## Collections MCP Para expor as coleções da AIVAX como ferramentas para um cliente MCP externo, veja [Collections MCP](https://docs.aivax.net/pt-br/docs/mcp-utilities/collections-mcp.md). Para a disponibilidade atual do serviço e limites de conta, veja [Plans and Limits](https://docs.aivax.net/pt-br/docs/limits.md). --- Source: https://docs.aivax.net/pt-br/docs/rag/text-segmentation.html # Segmentação de Texto A segmentação de texto divide documentos de origem em sequências semanticamente coesas que podem ser incorporadas ou indexadas em uma coleção RAG. Ela devolve segmentos para sua aplicação; não cria embeddings nem armazena documentos enviados. Use-a quando um documento de origem precisa de limites revisáveis e prontos para recuperação antes de criar ou atualizar documentos da coleção. Se você já tem texto focado e autocontido, pode importá-lo diretamente. Se quiser que o AIVAX processe arquivos de origem em documentos da coleção, veja [Media Injector](https://docs.aivax.net/pt-br/docs/rag/media-injector.md). ## Prepare o texto de origem Forneça o texto de origem completo sempre que possível. Os segmentos são mais úteis quando a origem tem títulos claros, parágrafos e declarações completas. Revise os resultados de tabelas, OCR, transcrições ou documentos com cabeçalhos repetidos antes de indexá-los. Use a sanitização apenas quando o conteúdo omitido for realmente irrelevante para a recuperação. Quando a redação exata da origem, a fidelidade legal ou a rastreabilidade completa forem importantes, mantenha e revise o texto de origem. Para a solicitação, resposta, autenticação e contrato de erro suportados, use a Referência da API: [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Segment%20text) Para disponibilidade atual do serviço e limites de conta, veja [Planos e Limites](https://docs.aivax.net/pt-br/docs/limits.md). --- Source: https://docs.aivax.net/pt-br/docs/rag/classification.html # Classificação de Texto Use a classificação de texto para classificar um conjunto fixo de rótulos para um ou mais documentos sem treinar um classificador personalizado. AIVAX incorpora cada documento e rótulo com o modelo de incorporação padrão, compara seus vetores usando similaridade do cosseno e devolve cada rótulo do mais similar ao menos similar para cada documento. Antes de chamar este endpoint, [crie uma chave de API](https://docs.aivax.net/pt-br/docs/authentication.md) e certifique-se de que a conta tem saldo positivo. ## Endpoint
POST /api/v1/generations/classify
## Comportamento da solicitação | Propriedade | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `documents` | `string[]` | Yes | Um ou mais documentos não vazios para classificar. Os resultados preservam esta ordem e o índice zero‑based de cada documento. | | `labels` | `string[]` | Yes | Um ou mais rótulos não vazios. Cada rótulo recebe uma pontuação para cada documento. | Documentos e rótulos duplicados são preservados. O endpoint sempre usa o modelo de incorporação padrão atual e não aceita um parâmetro de modelo, limiar de pontuação ou limite de resultados. Exemplo de solicitação: ```json { "documents": [ "Calculate the compound interest on a principal of $10,000 invested for 5 years at an annual rate of 5%, compounded quarterly", "Erklären Sie die Unterschiede zwischen Merge-Sort und Quicksort-Algorithmen in Bezug auf Zeitkomplexität, Platzkomplexität und Leistung in der Praxis.", "Write a poem about the beauty of nature and its healing power on the human soul" ], "labels": [ "Creative writing", "Complex problem", "Simple task" ] } ``` ## Ler a resposta `results` contém um item para cada documento de entrada. Cada array `scores` contém todos os rótulos fornecidos, ordenados por similaridade do cosseno decrescente. Rótulos com pontuações iguais preservam sua ordem original. ```json { "results": [ { "index": 0, "document": "Calculate the compound interest on a principal of $10,000 invested for 5 years at an annual rate of 5%, compounded quarterly", "scores": [ { "label": "Complex problem", "score": 0.98828 }, { "label": "Simple task", "score": 0.45272 }, { "label": "Creative writing", "score": 0.06823 } ] } ] } ``` Uma pontuação mede a similaridade de vetores, não uma probabilidade calibrada. Compare pontuações dentro da mesma solicitação e modelo de incorporação em vez de interpretar um valor como confiança percentual. Pontuações negativas são válidas e permanecem na resposta porque o endpoint não filtra rótulos. O uso de incorporação é cobrado para texto que requer inferência e está associado à chave de API autenticada. Texto repetido pode ser servido a partir de um cache interno, reduzindo latência e custos. Como o endpoint retorna cada par documento‑rótulo, o tamanho da resposta e o trabalho de comparação aumentam com `documents × labels`. A referência de API incorporada contém a solicitação, resposta, autenticação e detalhes de erro mantidos pelo servidor: [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Classify%20documents) --- Source: https://docs.aivax.net/pt-br/docs/rag/reranking.html # Reordenadores Os reordenadores reorganizam um conjunto existente de documentos candidatos para uma consulta. Eles não pesquisam uma coleção nem recuperam texto que está ausente da entrada. Use a API de reordenação autônoma quando sua aplicação já possui os candidatos ou use [Semantic Search](https://docs.aivax.net/pt-br/docs/rag/semantic-search.md) para recuperar candidatos de uma coleção AIVAX antes de reordená-los. ## Reordenar documentos diretamente Autentique-se com uma chave de API AIVAX e envie uma consulta com as strings dos documentos candidatos. A API devolve os candidatos em ordem de relevância, com a posição de entrada necessária para associar cada resultado aos dados da sua aplicação. Use a reordenação direta quando os candidatos são dinâmicos, vêm de outro sistema de busca ou não precisam ser armazenados em uma coleção AIVAX. Use a busca semântica gerenciada quando a AIVAX deve recuperar candidatos de um corpus persistente. Para a solicitação, resposta, autenticação e contrato de erro suportados, consulte a Referência da API: [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Rerank%20documents) ## Escolhendo um reordenador Comece com o reordenador padrão, a menos que você tenha um motivo mensurado para selecionar outra opção disponível. Avalie mudanças usando consultas representativas, idiomas, comprimentos de documentos e julgamentos de relevância do seu próprio workload. A reordenação melhora a ordem apenas entre os candidatos fornecidos a ela. Se o documento relevante estiver ausente, melhore a recuperação de candidatos, segmentação, formulação da consulta ou a quantidade de candidatos antes de comparar os reordenadores. Para a disponibilidade atual, opções suportadas e limites de conta, consulte a Referência da API e [Plans and Limits](https://docs.aivax.net/pt-br/docs/limits.md). --- Source: https://docs.aivax.net/pt-br/docs/rag/reflex.html # Reflex Reflex é a busca sem coleção da AIVAX para RAG. Envie uma consulta junto com strings de documentos candidatos e receba os itens mais relevantes em ordem classificada — sem indexação, armazenamento ou manutenção de uma coleção RAG primeiro. Reflex é o ranqueador padrão do [endpoint de reranking](https://docs.aivax.net/pt-br/docs/rag/reranking.md) autônomo: chamar esse endpoint sem um `model` seleciona o Reflex. Esta página cobre quando usar o Reflex; aquela página cobre a preparação de candidatos e a comparação de ranqueadores em profundidade. Use o Reflex quando sua aplicação já possui os documentos candidatos, o conjunto de candidatos muda com frequência ou você deseja uma etapa de recuperação sem indexação e armazenamento de coleção. Use a [Busca Semântica](https://docs.aivax.net/pt-br/docs/rag/semantic-search.md) quando a AIVAX deve armazenar, indexar e buscar uma base de conhecimento persistente ou restringir um corpus que é grande demais para ser submetido como candidatos em cada requisição. ## Reflex ou Busca Semântica? | Escolha Reflex quando... | Escolha Busca Semântica quando... | | --- | --- | | Sua aplicação já possui as strings de documentos candidatos. | Os documentos devem estar em coleções AIVAX gerenciadas. | | Você precisa de recuperação imediatamente, sem uma etapa de indexação. | A base de conhecimento é persistente e pesquisada repetidamente. | | O conjunto de candidatos é dinâmico ou específico da requisição. | O corpus é grande demais para ser submetido como candidatos em cada requisição. | | Você quer ranqueamento sem coleção. | Você quer filtragem de coleção, metadados armazenados, referências de documentos e recuperação gerenciada. | Reflex devolve candidatos de texto classificados; ele não gera uma resposta. Passe os documentos selecionados para o modelo de linguagem ou AI Gateway como contexto RAG. ## Usar Reflex Chame a API de reranking com uma consulta e os documentos candidatos que sua aplicação deseja comparar. Os resultados são retornados em ordem de relevância e mantêm a posição de entrada necessária para associá-los aos dados da sua aplicação. Use documentos candidatos concisos e focados. O reranking pode melhorar a ordem deles, mas não pode recuperar informações que não foram incluídas nos candidatos. Se o documento esperado estiver consistentemente ausente, melhore a seleção de candidatos, a segmentação ou a formulação da consulta antes de ajustar o ranqueador. Reflex aceita até 10.000 documentos candidatos por requisição e devolve no máximo 200 resultados classificados. Se o seu pool de candidatos exceder 10.000 documentos, reduza‑o primeiro — com pré‑filtragem lexical, um ranqueamento de primeira passagem barato ou recuperação de coleção — e deixe o Reflex ordenar a lista curta. Para a solicitação, resposta, autenticação e contrato de erro suportados, use a Referência da API: [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Rerank%20documents) ## Usar Reflex com RAG Reflex também é o reranker padrão após a AIVAX recuperar candidatos de coleções RAG. Neste fluxo, ele pode melhorar a ordem dos candidatos recuperados, mas não pode recuperar um documento que a etapa de recuperação não selecionou. Se documentos relevantes estiverem consistentemente ausentes, ajuste a recuperação, a segmentação, a formulação da consulta ou a quantidade de candidatos antes de ajustar o reranking. Free, Pro e Max incluem uma cota diária de reranking para o Reflex, compartilhada entre chamadas autônomas e reranking RAG. Entradas em cache e não em cache consomem essa cota. É separado da cota de embeddings RAG e do limite de tempo de processamento; outros rerankers são cobrados normalmente. Para capacidade relativa do plano e regras de cobertura, veja [Planos e Limites](https://docs.aivax.net/pt-br/docs/limits.md#included-daily-subscription-allowances). --- Source: https://docs.aivax.net/pt-br/docs/rag/best-practices.html # Boas Práticas de RAG Para obter os melhores resultados com a indexação e busca semântica, a qualidade dos seus documentos é fundamental. A forma como você estrutura e escreve seus documentos impacta diretamente na capacidade do modelo de recuperar a informação correta. ## Estrutura e Tamanho Um documento deve representar um trecho limitado e autossuficiente de conhecimento. - **Tamanho ideal**: Mantenha documentos entre 20 e 700 palavras. - **Muito curto (< 20 palavras)**: Pode não ter contexto suficiente para ser encontrado semanticamente. - **Muito longo (> 700 palavras)**: Pode ter seu conteúdo truncado, afetando a qualidade da indexação, ou misturar muitos tópicos diferentes, confundindo a busca. ## O que Fazer e O que Evitar ### ❌ Não faça - **Documentos muito curtos ou vazios**: Evite criar documentos com 10 ou menos palavras. - **Documentos gigantes**: Não envie documentos com milhares de palavras; quebre-os em partes menores. - **Mistura de assuntos**: Não fale sobre múltiplas coisas desconexas em um mesmo documento (ex: "Como ligar o carro" e "Preço da gasolina" no mesmo texto). - **Mistura de idiomas**: Mantenha o documento em uma única língua para melhor performance do embedding. - **Linguagem implícita**: Evite textos onde o sujeito ou contexto não está claro (ex: "Ele é azul" - quem é ele?). - **Linguagem excessivamente técnica**: Evite indexar JSONs puros ou logs de código sem explicação textual. ### ✅ Faça - **Seja explícito**: O documento deve fazer sentido sozinho. - **Foco único**: Cada documento deve cobrir um único tópico ou conceito. - **Repetição de palavras-chave**: Use termos importantes explicitamente. - *Exemplo*: Prefira "A cor do Honda Civic 2015 é amarela" ao invés de "a cor do carro é amarelo". - **Linguagem natural**: Escreva como um humano falaria ou explicaria o assunto. - **Use Tags**: Utilize tags para categorizar seus documentos e facilitar filtros. ## Dicas Adicionais - **Independência de Contexto**: Imagine que o documento será lido fora de ordem. Ele ainda faz sentido? Se a resposta for não, reescreva-o para ser independente. - **Metadados**: Use o campo de metadados para armazenar informações estruturadas (fonte, autor, data) que não precisam ser pesquisadas semanticamente mas são úteis para referência. - **Chunks**: Se você tem um PDF grande, faça o "chunking" (divisão) dele em parágrafos ou seções lógicas antes de indexar. Seguir essas diretrizes garantirá que o sistema RAG recupere as informações mais relevantes para seus usuários. --- Source: https://docs.aivax.net/pt-br/docs/inference/ai-gateway.html # AI Gateway Um AI Gateway é uma configuração de inferência persistente. Ele permite que você chame um gateway pelo nome do modelo enquanto o AIVAX aplica as configurações do modelo do gateway, instruções, coleções RAG, ferramentas, habilidades, workers, moderação e controles de contexto. Use um gateway quando o mesmo comportamento precisar ser reutilizado por vários clientes ou alterado sem reimplantar a aplicação chamadora. ## Como pensar em um gateway Uma chamada direta para `/v1/chat/completions` pode chamar um modelo AIVAX integrado diretamente, por exemplo `@openai/gpt-5-mini`. Um gateway armazena as decisões que você não quer repetir a cada solicitação: - Provedor e nome do modelo. - Instruções do sistema, fontes de instruções remotas, modelo de prompt do usuário e pré-preenchimento do assistente. - Coleções RAG, limites de resultados, limiar de pontuação, reranker, comportamento de referência e estratégia de consulta. - Ferramentas compatíveis com OpenAI, ferramentas internas do AIVAX, ferramentas MCP, funções de protocolo, habilidades e o ambiente bash opcional. - Comportamento da janela de contexto, truncamento de mensagens de ferramenta, moderação, workers, roteamento de modelo e tratamento de chamadas de ferramenta. Isso cria um limite de responsabilidade. O aplicativo cliente envia mensagens e substituições de solicitação opcionais. O administrador do gateway controla a política operacional. Na produção, comece com uma configuração conservadora: instruções claras do sistema, um modelo que suporte as modalidades e ferramentas necessárias, uma coleção RAG bem preparada e apenas as ferramentas realmente necessárias. Adicionar muitas ferramentas, habilidades ou coleções aumenta tokens de entrada, custo e a chance de o modelo escolher o caminho errado. ## Modelos e nomes de gateway Existem três maneiras comuns de escolher o que `/v1/chat/completions` usa: - Use uma tag de modelo integrado AIVAX, geralmente começando com `@`. - Use um ID completo de gateway. - Use um slug de gateway no formato `nome:id-final`, como `support:50c3`. Chaves de API privadas podem resolver um gateway pelo ID completo ou pelo slug. Chaves de API públicas são mais restritas: elas podem usar gateways de IA apenas pelo ID completo, e apenas um conjunto limitado de parâmetros de solicitação de conclusão de chat é aceito. Ao escolher um modelo, valide três pontos antes de colocá‑lo em produção: - O modelo suporta as modalidades de entrada que você pretende enviar, como imagem, áudio, vídeo ou arquivo. - O modelo suporta chamada de função se o gateway usar ferramentas, RAG através de `QueryFunction`, MCP, funções de protocolo, habilidades ou funções internas. - O modelo aceita os parâmetros que você configura. Alguns modelos integrados rejeitam pré‑preenchimento do assistente, temperatura, sequências de parada ou esforço de raciocínio. Gateways também podem usar roteamento de modelo. Para o roteador de complexidade, o AIVAX classifica a última solicitação do usuário como baixa, média ou alta complexidade, seleciona o modelo configurado para esse nível e emite `X-Model-Routed-Complexity` na resposta HTTP quando disponível. ## Usando um AI Gateway O AIVAX fornece um ponto de extremidade de conclusão de chat compatível com OpenAI: [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Inference%20(chat%20completions)) Os valores do gateway podem ser sobrescritos pela solicitação para parâmetros suportados, como `temperature`, `top_p`, `seed`, `reasoning_effort`, `max_completion_tokens`, `stop`, `tools`, `response_schema`, `response_format`, `builtin_tools`, `multimodal_preprocess` e `tool_invocation_explanations`. Para comportamento de inferência direta, incluindo opções de renderização de resposta, veja [Inference](https://docs.aivax.net/pt-br/docs/inference/inference.md). ## Usando SDKs Como o ponto de extremidade segue o formato de conclusão de chat OpenAI, você pode usar SDKs compatíveis com OpenAI existentes. ```python from openai import OpenAI client = OpenAI( base_url="https://inference.aivax.net/v1", api_key="" ) response = client.chat.completions.create( model="my-gateway:50c3", messages=[ {"role": "user", "content": "Explain why AI gateways are useful."} ] ) print(response.choices[0].message.content) ``` A inferência compatível com OpenAI usa `/v1/chat/completions`. O ponto de extremidade `/v1/responses` não é suportado. ## Configuração recomendada para produção Escreva as instruções do sistema para que o modelo entenda seu papel, público, fontes de verdade e limites. Inclua quando usar RAG, quando usar ferramentas e como responder quando a informação não estiver disponível. Evite repetir configurações operacionais que já existem no gateway, como limites de truncamento ou listas de ferramentas. Para RAG, vincule coleções com documentos curtos, autônomos e bem nomeados. Escolha a estratégia de consulta com base no tipo de conversa: - `Plain`: Usa a última mensagem do usuário como termo de busca. - `Concatenate`: Junta o número configurado de últimas mensagens do usuário linha a linha. - `UserRewrite`: Reescreve mensagens recentes do usuário em uma ou mais consultas de busca usando um modelo resolvedor. - `FullRewrite`: Reescreve mensagens recentes do usuário e do assistente usando um modelo resolvedor. - `QueryFunction`: Exponha uma função de busca ao modelo em vez de injetar um resultado de busca antes da inferência. Para ferramentas, habilite apenas aquelas com um papel claro. Ferramentas internas cobrem capacidades comuns como data e hora atuais, busca na web, abertura de URLs, execução de código, geração de imagens, geração de documentos, geração de páginas, ações de calendário, memória, requisições HTTP e busca X post. MCP externo é melhor quando você já tem um servidor MCP com ferramentas de negócios. Funções de protocolo são úteis quando você deseja expor callbacks HTTP específicos ao modelo sem instalar um servidor MCP completo. Use um manipulador de ferramenta apenas quando o modelo selecionado precisar de ajuda para produzir chamadas de ferramenta. O manipulador disponível é `react.v1.selfcall`; `native` ou nenhum valor usa a chamada de ferramenta nativa do modelo. Use workers quando um sistema externo precisar decidir algo durante o fluxo de inferência. Um worker pode bloquear uma mensagem, reescrever o contexto, adicionar ferramentas ou substituir um resultado de ferramenta do lado do servidor. Como o worker é chamado no caminho crítico, mantenha‑o rápido e determinístico. ## Inference MCP Para expor um modelo integrado ou AI Gateway como ferramenta para um cliente MCP externo, veja [Inference MCP](https://docs.aivax.net/pt-br/docs/mcp-utilities/inference-mcp.md). --- Source: https://docs.aivax.net/pt-br/docs/inference/inference.html # Inferência AIVAX expõe uma API `chat/completions` compatível com OpenAI com parâmetros adicionais da AIVAX. As adições são opcionais e foram projetadas para suportar gateways, RAG, ferramentas integradas, respostas estruturadas, pré-processamento multimodal, roteamento de modelo e metadados de faturamento. Use esta página para chamadas diretas de inferência. Use [AI Gateway](https://docs.aivax.net/pt-br/docs/inference/ai-gateway.md) quando a mesma configuração precisar ser reutilizada ou gerenciada centralmente. ## Endpoint
POST /v1/chat/completions
O endpoint também tem o alias de API `/api/v1/chat/completions`. ## Roteamento de provedor Alguns modelos integrados estão disponíveis por mais de um provedor. O roteamento de provedor permite que a AIVAX escolha entre esses provedores sem alterar o modelo solicitado pela sua aplicação. Isso difere do roteamento de modelo, que pode selecionar um modelo diferente com base na complexidade da requisição. A AIVAX considera provedores que estão atualmente disponíveis e compatíveis com a requisição. Se apenas um provedor for elegível, a preferência de roteamento não altera o resultado. O roteamento de provedor aplica‑se apenas a modelos integrados da AIVAX; um gateway “traga‑seu‑próprio‑chave” usa o endpoint do provedor configurado nesse gateway. Preferências de roteamento disponíveis: | Preferência | Comportamento | |---|---| | `Balanced` | Equilibra preço, velocidade e qualidade. Este é o padrão. | | `Cheapest` | Seleciona o provedor com o menor preço de token de entrada e saída aplicável. | | `Fastest` | Prioriza o provedor com a maior taxa de transferência disponível. | | `Quality` | Seleciona o provedor que a AIVAX classifica como o de maior qualidade, sem otimizar por preço ou velocidade. | ### Configurar roteamento em um AI Gateway Use um AI Gateway quando a mesma preferência de roteamento deve ser aplicada a cada requisição. No editor do gateway, selecione um modelo integrado, abra **Routing preference**, escolha a estratégia preferida e salve o gateway. A configuração equivalente do gateway usa `parameters.routingOption`: ```json { "name": "Cost-optimized assistant", "parameters": { "baseAddress": "@integrated", "modelName": "YOUR_INTEGRATED_MODEL", "routingOption": "Cheapest" } } ``` Depois de salvar, chame o gateway normalmente usando seu ID ou slug como `model`. A AIVAX aplica a preferência de roteamento armazenada preservando as instruções, ferramentas, configuração RAG e outras definições do gateway. Consulte [AI Gateway](https://docs.aivax.net/pt-br/docs/inference/ai-gateway.md) para o fluxo completo do gateway. ### Substituir roteamento em `chat/completions` Use `routing_preset` para escolher uma estratégia de provedor para uma única requisição. A sobrescrita funciona com um modelo integrado direto ou um AI Gateway que usa um modelo integrado: ```json { "model": "YOUR_INTEGRATED_MODEL_OR_GATEWAY_ID", "messages": [ { "role": "user", "content": "Summarize this incident report." } ], "routing_preset": "Fastest" } ``` Os valores aceitos são `Balanced`, `Cheapest`, `Fastest` e `Quality`. O valor da requisição sobrescreve o `routingOption` salvo no gateway apenas para essa requisição; não atualiza o gateway. Como `routing_preset` é uma extensão da AIVAX, envie‑o como um campo extra no corpo da requisição ao usar um SDK compatível com OpenAI. Sobrescritas de roteamento ao nível da requisição exigem uma chave de API privada. ## Entrada e multimodalidade A AIVAX aceita partes de conteúdo de mensagem compatíveis com OpenAI para texto, imagens, áudio, vídeos e arquivos. O modelo selecionado deve suportar a modalidade a menos que você peça à AIVAX para pré‑processar a mídia em texto. ```json { "model": "@google/gemini-3-flash", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe these inputs briefly." }, { "type": "image_url", "image_url": { "url": "data:image/png;base64,", "detail": "auto" } }, { "type": "input_audio", "input_audio": { "data": "base64-encoded-audio", "format": "wav" } }, { "type": "file", "file": { "filename": "document.pdf", "file_data": "data:application/pdf;base64," } } ] } ] } ``` Mapeamentos de partes de conteúdo suportadas: - `text`: Texto simples. - `image_url`: Conteúdo de imagem. `image_url.url` pode ser uma URL externa ou uma URL de dados base64. `image_url.detail` pode ser `low`, `high` ou `auto` quando o modelo suporta. - `video_url`: Conteúdo de vídeo. `video_url.url` pode ser uma URL externa ou uma URL de dados base64. Prefira URLs para vídeos grandes. - `input_audio`: Conteúdo de áudio. `input_audio.data` é áudio em base64, e `input_audio.format` indica o formato. - `file`: Conteúdo de arquivo. `file.filename` nomeia o arquivo, e `file.file_data` pode ser uma URL externa ou uma URL de dados base64. Para entrada de vídeo, envie uma parte de conteúdo `video_url`. O exemplo a usa uma Data URL em base64; prefira uma URL publicamente acessível para vídeos grandes: ```json { "model": "@google/gemini-3-flash", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Summarize the main actions in this video and identify any visible safety risks." }, { "type": "video_url", "video_url": { "url": "data:video/mp4;base64," } } ] } ] } ``` Links externos devem ser acessíveis à AIVAX sem autenticação, restrições de firewall ou renderização apenas em JavaScript. Falhas ao baixar, redirecionamentos, URLs bloqueadas, formatos não suportados ou limites de tamanho específicos do provedor podem causar falha na inferência. Você também pode enviar uma requisição simples de texto com `prompt`: ```json { "model": "@google/gemini-3-flash", "prompt": "Say hello" } ``` ## Idempotência da requisição Defina `idempotency_key` quando sua integração precisar de chamadas repetidas para atualizar o mesmo registro de conversa armazenado em vez de criar um novo token de conversa. A AIVAX usa esse valor para correlacionar o contexto do AI Gateway e o registro da conversa. ```json { "model": "your-model-or-gateway-id", "messages": [ { "role": "user", "content": "Summarize order 123." } ], "idempotency_key": "order-123-summary" } ``` O valor deve ser uma string não vazia com no máximo 128 caracteres. Quando omitido, a AIVAX gera automaticamente um token de conversa. ## Metadados da requisição Defina `metadata` para anexar informações de chave/valor em forma de string à requisição de inferência. A AIVAX armazena esse objeto com a conversa registrada e o expõe aos eventos do gateway, sendo útil para correlação operacional como ID de pedido, locatário, fluxo de trabalho ou chave de rastreamento interno. ```json { "model": "your-model-or-gateway-id", "messages": [ { "role": "user", "content": "Summarize this support ticket." } ], "metadata": { "ticket_id": "SUP-1042", "workflow": "support-triage" } } ``` `metadata` deve ser um objeto JSON cujas propriedades e valores são strings. Não coloque segredos, credenciais, dados de pagamento ou cargas úteis grandes neste campo. ## Pré‑processamento multimodal Use `multimodal_preprocess` quando o modelo principal deve receber uma descrição textual da mídia em vez do objeto de mídia original. Isso é útil para modelos orientados a texto ou quando você deseja que a AIVAX normalize arquivos antes da inferência principal. ```json { "model": "@meta/llama-3.3-70b", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this file briefly." }, { "type": "file", "file": { "filename": "document.pdf", "file_data": "data:application/pdf;base64,BASE64_PDF_CONTENT" } } ] } ], "multimodal_preprocess": "File" } ``` Flags de pré‑processamento disponíveis: - `Image` - `Audio` - `Video` - `File` - `OtherFiles` - `All` O resolvedor armazena em cache descrições de mídia por hash de conteúdo para reutilização. O pré‑processamento de `Image`, `Audio`, `Video` e PDF `File` usa inferência multimodal auxiliar. Arquivos não PDF suportados utilizam extração local de texto. Entradas multimodais podem ter requisitos de conta. Revise [Pricing](https://docs.aivax.net/pt-br/docs/pricing.md) e [Plans and limits](https://docs.aivax.net/pt-br/docs/limits.md) antes de usá‑las em produção. Quando uma inferência multimodal falha, estreite o problema: 1. Teste uma mensagem de texto simples com o mesmo modelo. 2. Teste um anexo pequeno. 3. Teste o mesmo anexo com `multimodal_preprocess`. 4. Revise a URL, formato, tamanho e suporte de modalidade do modelo. ## Respostas estruturadas A AIVAX oferece suporte a respostas estruturadas por meio de `response_schema`, `response_format` e `json_only`. ```json { "model": "@google/gemini-2.5-flash", "prompt": "Search for recent news about electric vehicles.", "stream": true, "builtin_tools": { "tools": [ "WebSearch" ], "options": { "web_search_mode": "full" } }, "response_schema": { "type": "object", "properties": { "news": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "News title" }, "summary": { "type": "string", "description": "News summary" } }, "required": ["title", "summary"] } } }, "required": ["news"] } } ``` `response_schema` habilita JSON Healing. A AIVAX solicita JSON ao modelo, extrai JSON do texto ou blocos markdown gerados, valida contra o esquema e tenta novamente com feedback de validação até que a saída seja válida ou o limite de tentativas seja alcançado. Saiba mais em [Structured responses](https://docs.aivax.net/pt-br/docs/inference/structured-responses.md). ## Funções sob demanda Use `builtin_tools` para habilitar ferramentas internas da AIVAX em uma requisição direta sem criar um gateway: ```json { "model": "@google/gemini-2.5-flash", "prompt": "Search for recent news about electric vehicles.", "stream": true, "builtin_tools": { "tools": [ "WebSearch" ], "options": { "web_search_mode": "full", "web_search_max_results": 5 } } } ``` Ferramentas internas incluem `WebSearch`, `AdvancedWebUsage`, `OpenUrl`, `Code`, `Request`, `Calendar`, `Remember`, `GenerateWebPage`, `GenerateDocument`, `XPostsSearch` e `ImageGeneration`. Ferramentas sob demanda são adequadas para chamadas ocasionais, protótipos e integrações que não precisam de um gateway persistente. Se a mesma aplicação sempre usar as mesmas ferramentas, prefira configurá‑las em um AI Gateway para que a política seja centralizada. ## Corpo da requisição de provedor personalizado Quando um gateway usa uma chave de API fornecida e um endpoint de provedor compatível com OpenAI, `extra_body` pode mesclar JSON customizado ao corpo da requisição do provedor: ```json { "model": "my-custom-model:abc4", "messages": [ { "role": "user", "content": "Explain the tradeoff." } ], "extra_body": { "reasoning": { "enabled": true } } } ``` `extra_body` não é permitido com modelos integrados da AIVAX. ## Explicações de ferramentas Defina `tool_invocation_explanations: true` para pedir à AIVAX que inclua campos de explicação nos argumentos de ferramentas do lado do servidor. Quando o modelo fornece `_tool_reason` e `_tool_goal`, `servertool.explanation` contém uma cópia amigável ao cliente: ```json { "model": "@x-ai/grok-4.3", "messages": [ { "role": "user", "content": "What's the weather forecast for today?" } ], "stream": true, "builtin_tools": { "tools": ["WebSearch"] }, "tool_invocation_explanations": true } ``` Exemplo de evento de stream: ```json { "choices": [], "servertool": { "name": "web_search", "id": "call-example-id-0", "contents": "{\"query\":\"weather forecast today\",\"_tool_reason\":\"Searching for today's weather forecast online\",\"_tool_goal\":\"I need current weather information to answer accurately.\"}", "state": "Created", "explanation": { "reason": "Searching for today's weather forecast online", "goal": "I need current weather information to answer accurately." } }, "usage": null } ``` ## Modo de renderização da resposta Defina `rendering_mode: "textual_blocks"` quando seu cliente quiser que a AIVAX coloque raciocínio e atividade de ferramentas do lado do servidor no mesmo fluxo textual de resposta que a UI de chat já renderiza. Isso é útil para clientes que constroem uma linha do tempo única de resposta e desejam transformar raciocínio e atividade de ferramentas em componentes visíveis sem manter caminhos de tratamento de eventos separados para cada tipo de marcador. ```json { "model": "@openai/gpt-5-mini", "messages": [ { "role": "user", "content": "Search for recent product updates and summarize the important changes." } ], "stream": true, "builtin_tools": { "tools": ["WebSearch"] }, "rendering_mode": "textual_blocks" } ``` Neste modo, o raciocínio pode ser emitido como blocos `` e ``, o texto voltado ao assistente pode ser emitido como blocos `` e marcadores de ferramentas do lado do servidor podem aparecer como elementos de resultado de ferramenta, como `
`. Trate esses blocos como marcadores de apresentação dentro do fluxo de resposta: analise‑os em componentes da linha do tempo de chat, seções colapsáveis de raciocínio, fragmentos de resposta do assistente ou linhas de status de ferramenta, mas não concatene cegamente cada marcador na resposta final do assistente. Clientes que não entendem essa marcação devem manter o modo de renderização padrão e lidar diretamente com os eventos estruturados do stream. No modo padrão, o raciocínio chega via `delta.reasoning` e a atividade de ferramentas do lado do servidor chega via eventos `servertool`. Preserve a ordem em que os eventos do stream chegam para que o raciocínio, a atividade de ferramentas, o conteúdo parcial e a resposta final permaneçam na mesma linha do tempo de resposta. ### Exemplo bruto de múltiplas turnos O exemplo abaixo mostra a forma de uma resposta em stream quando o raciocínio do lado do servidor está visível ao cliente, `tool_invocation_explanations` está habilitado e `textual_blocks` é usado para manter a linha do tempo textual. Os atributos exatos do resultado da ferramenta podem variar conforme o renderizador, mas o comportamento importante é a ordenação: raciocínio, fragmentos de resposta do assistente, atividade de ferramentas, mais raciocínio e a resposta final podem pertencer ao mesmo turno do assistente. ```json { "model": "my-custom-model:abc4", "messages": [ { "role": "user", "content": "Which cheap and fast multimodal models should I use for security camera analysis?" } ], "stream": true, "builtin_tools": { "tools": ["WebSearch"] }, "tool_invocation_explanations": true, "rendering_mode": "textual_blocks", "extra_body": { "reasoning": { "enabled": true } } } ``` Linha do tempo do assistente em stream: ```text The user is asking for cheap, fast multimodal models for security camera analysis. I should list available AIVAX models and search the documentation before recommending options. I will check the available multimodal models and identify the best options for security camera analysis.
aivax_list_modelsListing the available models in AIVAX
aivax_search_contextSearching documentation about multimodal models and image analysis in AIVAX
The relevant models should support VideoInput or ImageInput, have low input cost, and be fast enough for camera workflows. I found several candidates and should rank them by cost, speed, and modality support. For security camera analysis, prioritize models with VideoInput, low input pricing, and high speed. Top picks: 1. @google/gemini-2.5-flash-lite: fast, inexpensive, and supports video. 2. @qwen/qwen3.5-9b: the lowest input cost with video support. 3. @amazon/nova-lite: low input cost and a large context window. Use VideoInput for clips when possible. If a model only supports ImageInput, extract frames from the camera stream before sending them. ``` Quando o usuário responde, mantenha o histórico da conversa focado no resultado visível do assistente. Armazene o raciocínio e os detalhes da ferramenta como metadados de linha do tempo ou auditoria se seu produto precisar disso, mas não os converta em uma nova mensagem de usuário. A mensagem do assistente deve usar o conteúdo do bloco `` final, não a transcrição completa do raciocínio. ```json { "model": "my-custom-model:abc4", "messages": [ { "role": "user", "content": "Which cheap and fast multimodal models should I use for security camera analysis?" }, { "role": "assistant", "content": "For security camera analysis, prioritize models with VideoInput, low input pricing, and high speed.\n\nTop picks:\n\n1. @google/gemini-2.5-flash-lite: fast, inexpensive, and supports video.\n2. @qwen/qwen3.5-9b: the lowest input cost with video support.\n3. @amazon/nova-lite: low input cost and a large context window.\n\nUse VideoInput for clips when possible. If a model only supports ImageInput, extract frames from the camera stream before sending them." }, { "role": "user", "content": "Now recommend one model for real-time alerts and one for deeper review." } ], "stream": true, "builtin_tools": { "tools": ["WebSearch"] }, "tool_invocation_explanations": true, "rendering_mode": "textual_blocks", "extra_body": { "reasoning": { "enabled": true } } } ``` ### Orientação de apresentação Durante a geração, o raciocínio é útil porque permite que o usuário acompanhe o que o modelo está fazendo antes que a resposta final exista. O assistente pode “falar” enquanto raciocina emitindo atualizações de processo voltadas ao usuário ou fragmentos de resposta provisórios. Essas atualizações podem ser intercaladas com blocos de raciocínio, chamadas de ferramentas e conteúdo de resposta parcial à medida que a resposta se desenvolve. Uma vez que a resposta final do assistente é gerada, essa resposta se torna o principal produto da inferência. O raciocínio intermediário ainda é útil para auditoria, orientação e depuração, mas costuma deixar de ser o objetivo principal do usuário. Colapse ou minimize o raciocínio por padrão após a conclusão, de modo que a resposta final receba a ênfase visual mais forte, mantendo o processo disponível para usuários que desejam inspecioná‑lo. Use divulgação progressiva ao longo desse ciclo de vida. O raciocínio pode ser visível enquanto o modelo ainda está trabalhando, tornando‑se um elemento secundário mais discreto após a aparição da resposta final. A atividade de ferramentas deve ser lida como status, não como discurso: use rótulos concisos como “Searching”, “Opening source”, “Running tool”, “Finished” ou “Failed”, e mantenha cada invocação de ferramenta agrupada como um item da linha do tempo, mesmo que seu estado mude ao longo do tempo. Uma boa hierarquia visual é: - Resposta do assistente: maior destaque, tipografia de leitura normal, parte da conversa principal. - Raciocínio em progresso: visível o suficiente para mostrar o que o modelo está fazendo enquanto a resposta está sendo gerada. - Raciocínio concluído: menor destaque, cor ou contêiner suavizado, colapsado ou minimizado por padrão. - Blocos de ferramentas: linhas de status compactas com indicadores claros de carregamento, sucesso e erro. - Detalhes brutos: ocultos por padrão, a menos que o cliente seja um desenvolvedor, auditor ou superfície de depuração. Evite expor internals barulhentos diretamente aos usuários finais. Mostre nomes de ferramentas, estados, rótulos de origem ou resumos curtos quando ajudarem o usuário a entender o que aconteceu. Oculte argumentos brutos, cargas úteis grandes e detalhes de implementação, a menos que o usuário solicite explicitamente detalhes ou a superfície do produto seja projetada para inspeção técnica. Para acessibilidade, torne cada bloco colapsado alternável por teclado, dê a cada linha de status um rótulo legível, evite depender apenas de cor para indicar estado e mantenha o movimento sutil. Uma resposta em stream deve parecer estável enquanto se atualiza: novos raciocínios ou linhas de ferramentas podem aparecer em ordem, mas o conteúdo existente não deve saltar ou forçar o usuário a perder a posição de leitura. ## Chamada direta ou gateway Use uma chamada direta para tarefas simples, testes, rotinas internas e integrações onde a aplicação controla o modelo, o prompt, as ferramentas e o contexto de cada requisição. Use um AI Gateway quando o comportamento precisar ser estável, auditável e reutilizável. Gateways são mais adequados para assistentes de suporte, bots de chat, agentes RAG, ferramentas permanentes, workers, skills e configurações compartilhadas por vários clientes. --- Source: https://docs.aivax.net/pt-br/docs/inference/agentic-tests.html # Testes Agentes Testes Agentes avaliam como um AI Gateway se comporta ao longo de uma conversa completa e orientada a objetivos, em vez de pontuar uma única resposta isolada. O AIVAX simula a próxima mensagem do usuário, envia cada turno ao gateway selecionado e usa um juiz independente para determinar se a conversa alcançou seu objetivo, permanece recuperável ou se desviou persistentemente do resultado esperado. Use Testes Agentes para criar verificações de regressão repetíveis para suporte, vendas, onboarding, uso de ferramentas, RAG e outros fluxos de agente de múltiplas interações. Como um teste passa pelo AI Gateway configurado, ele exercita o modelo, as instruções, as ferramentas, as habilidades, o conhecimento e as configurações de inferência do gateway em conjunto. ## Testes persistentes no painel Abra **Testes Agentes** no painel do AIVAX para criar e gerenciar casos de teste reutilizáveis. Um teste armazena: - o AI Gateway em teste; - um objetivo que descreve o resultado conversacional esperado e é compartilhado com o usuário simulado e o juiz; - critérios de validação opcionais usados apenas pelo juiz; - mensagens iniciais opcionais, recursos externos e um identificador de usuário externo; - amostragem do usuário simulado, limites de turnos, comportamento de saída e limites de avaliação; - um agendamento recorrente opcional; - configurações de notificação de falha e recuperação. A definição do teste é reutilizável. Cada execução cria uma execução separada, de modo que alterar um teste depois não substitui o histórico já coletado para execuções anteriores. ### Crie um teste útil Escreva o objetivo a partir da perspectiva do usuário simulado: descreva quem ele é, o que deseja e como deve avançar na conversa. Não o escreva como instruções para o assistente. O objetivo é compartilhado tanto com o usuário simulado, que o persegue, quanto com o juiz, que o avalia. Por exemplo: > Você está escolhendo um plano para sua equipe. Explique o tamanho e as necessidades da sua equipe quando solicitado, pergunte qual plano se encaixa e continue até entender a recomendação e como se inscrever. Use **Critérios de validação** para requisitos opcionais que devem afetar apenas a avaliação do juiz, não o comportamento do usuário simulado. Por exemplo: > A recomendação deve nomear o plano selecionado e conectá‑lo ao tamanho de equipe declarado. A resposta final deve incluir um passo direto de inscrição. Manter esses critérios separados impede que o usuário simulado direcione artificialmente a conversa para as verificações que o juiz aplicará. Use **Mensagens iniciais** quando o cenário exigir um contexto estabelecido, como uma objeção de cliente, uma resposta anterior do assistente ou um ponto específico em um fluxo existente. Use `external_user_id` quando o comportamento do gateway depender de uma identidade da sua própria aplicação. O valor é encaminhado para a inferência do gateway em cada execução desse teste. Use `resources` para fornecer ao usuário simulado e ao juiz um contexto compartilhado que não pertence à conversa inicial. Forneça até 16 objetos com um `type` e um valor `data` não vazio. `Text` usa `data` como contexto literal; `RemoteResource` recupera o conteúdo da URL em `data`. Por exemplo: ```json { "resources": [ { "type": "Text", "data": "O cliente tem uma janela de reembolso de 14 dias." }, { "type": "RemoteResource", "data": "https://example.com/refund-policy" } ] } ``` Os recursos são visíveis ao usuário simulado e ao juiz; eles não são enviados ao gateway em teste como histórico de conversa. Eles não adicionam conhecimento ao gateway. Se o assistente precisar recuperar o mesmo material, disponibilize‑o através do próprio conhecimento ou das ferramentas do gateway. O usuário simulado ainda pode revelar naturalmente informações do recurso em suas mensagens, portanto não trate recursos como critérios ocultos apenas para o juiz. Conteúdo remoto pode mudar entre execuções de teste e contribui para o uso. Use apenas URLs confiáveis e publicamente acessíveis cujo conteúdo seja adequado para o teste. Um teste focado costuma gerar resultados mais acionáveis do que um cenário amplo. Separe objetivos não relacionados em testes diferentes para que uma falha identifique o comportamento que regrediu. ### Ganchos de validação Testes Agentes persistentes podem chamar ganchos de validação externos durante uma execução. Configure o array `hooks` ao criar ou atualizar um teste: ```json { "hooks": [ { "event": "before-test", "url": "https://validator.example/hooks/agentic-tests" }, { "event": "after-test", "url": "https://validator.example/hooks/agentic-tests" }, { "event": "before-inference", "url": "https://validator.example/hooks/gateway" }, { "event": "after-inference", "url": "https://validator.example/hooks/gateway" }, { "event": "context-changed", "url": "https://validator.example/hooks/agentic-tests" } ] } ``` Os eventos suportados são: | Evento | Quando é enviado | Dados do evento | |---|---|---| | `before-test` | Antes do primeiro turno simulado. | `gateway`, `goal` e `metadata`. | | `after-test` | Depois que o teste atinge um resultado terminal normal e antes de emitir o evento final. | O resultado final, motivo, estado, número do turno, pontuação, delta da conversa e sequência de perdas. | | `before-inference` | Uma vez antes da inferência principal do gateway em cada turno. | `turn_number` e o array `messages` atual. | | `after-inference` | Uma vez depois da inferência principal do gateway em cada turno. | `turn_number` e o array `messages` atual. | | `context-changed` | Uma vez por turno após a resposta do gateway ser concluída. | `turn_number` e o array `messages` atual. | `before-inference` e `after-inference` estão disponíveis apenas quando o teste tem como alvo um AI Gateway. Ganchos são suportados para testes persistentes no painel e execuções agendadas; o endpoint direto de validação SSE não aceita `hooks`. Cada gancho recebe um envelope JSON compatível com worker: ```json { "testId": "", "runId": "", "gatewayId": "", "moment": "2026-08-16T03:00:00Z", "event": { "name": "before-inference", "data": { "turn_number": 1, "messages": [] } } } ``` A URL do gancho deve ser um HTTP ou HTTPS absoluto sem credenciais embutidas e não pode apontar para localhost, loopback, redes privadas, link‑local ou outros endereços locais bloqueados. Quando a conta tem uma chave de gancho, o AIVAX também envia `X-Request-Nonce`; valide‑a antes de confiar no payload. As requisições de gancho usam `POST` com `Content-Type: application/json`. Respostas de gancho seguem a convenção de worker: qualquer resposta `2xx` continua a execução; uma resposta não `2xx` ou falha na requisição HTTP a interrompe imediatamente. O corpo da resposta não seleciona outra ação. A execução interrompida é armazenada como `failed`, emite um resultado terminal com `reason: "validation_hook_interrupted"` e inclui entradas de auditoria da chamada de gancho no array `result.hooks` da execução. As entradas de auditoria contêm o evento, URL, timestamp, status ou erro, se a execução continuou e até 4 000 caracteres do corpo da resposta. ### Executar e inspecionar um teste Selecione **Run test** para enfileirar uma execução. As execuções podem estar `pending`, `running`, `succeeded`, `failed` ou `cancelled`. Tanto a taxa de novas execuções quanto a simultaneidade ao nível da conta dependem do plano atual. Veja [Plans and limits](https://docs.aivax.net/pt-br/docs/limits.md#plan-limits) para valores atuais. Execuções manuais, execuções agendadas e avaliações diretas por API compartilham uma cota de novas execuções entre as chaves de API da conta. Uma execução persistente conta quando é enfileirada e não conta novamente quando a execução começa. Turnos de conversa não consomem unidades de execução adicionais, embora limites de inferência aplicáveis ainda se apliquem. Uma requisição de execução manual acima da cota retorna HTTP 429 sem criar uma execução; aguarde a janela de limite de taxa limpar antes de tentar novamente. Uma execução processa sua conversa sequencialmente, enquanto execuções elegíveis da mesma conta podem ser executadas simultaneamente. Cada turno verifica se a conta pode continuar operando. Uma execução pode falhar se o saldo for esgotado ou a inferência não puder prosseguir, e uma execução pendente ou em andamento pode ser cancelada pelo painel. O inspetor de execução retém: - mensagens do usuário simulado, assistente e juiz em ordem cronológica; - timestamp preciso para cada mensagem retida; - uso de tokens de prompt, prompt em cache e conclusão por mensagem; - cada opinião do juiz, incluindo seu raciocínio, pontuação, estado e valores de trajetória; - o resultado final da avaliação, informações de falha e custo total cobrado na execução. Use as opiniões do juiz para identificar o turno em que a conversa melhorou, ficou em risco, teve sucesso ou entrou em perda persistente. O detalhe da execução também pode ser exportado como JSON para revisão offline. ### Agendar testes recorrentes Um teste pode ser executado automaticamente a partir de uma expressão cron padrão de cinco campos. O intervalo mínimo suportado é cinco minutos. Por exemplo, `*/15 * * * *` executa a cada 15 minutos. Se a cota de novas execuções da conta estiver esgotada, um teste agendado pendente aguarda a próxima verificação de agendamento sem criar uma execução. O agendamento não contorna a cota nem reserva capacidade separadamente de execuções manuais e avaliações diretas. Desative o agendamento quando quiser preservar a definição do teste sem criar novas execuções agendadas. Execuções manuais permanecem disponíveis a partir da página do teste. ### Notificações de falha e recuperação Habilite notificações de falha quando execuções repetidas com falha devem alertar o proprietário da conta. O **Notification threshold** controla quantas execuções consecutivas no estado `failed` são necessárias antes que o AIVAX envie um alerta. O padrão é `1`. Essas notificações rastreiam erros de execução, não falhas de teste comportamental. Uma execução no estado `succeeded` completou sem erro de execução, mas seu resultado comportamental ainda pode ser `loss` ou `incomplete`. Esses resultados não contam para o limite de notificação de falha. Quando **Recovery notification** está habilitada, o AIVAX também notifica a conta após uma execução concluir com sucesso depois de falhas de execução consecutivas suficientes para atingir o limite configurado. Uma execução bem‑sucedida redefine o contador de falhas consecutivas, mesmo que seu resultado comportamental seja `loss` ou `incomplete`. Recuperação, portanto, significa que a execução foi recuperada, não que o assistente passou nas verificações comportamentais. ### Retenção Execuções bem‑sucedidas e falhas são retidas por um mês. Execuções canceladas são retidas por um dia. Exporte qualquer resultado que precise permanecer disponível além desses períodos. ## Configurações de avaliação | Configuração | Padrão | Valores aceitos | Descrição | | --- | --- | --- | --- | | `validation_criteria` | `null` | String, parte de mensagem ou lista de partes de mensagem | Requisitos opcionais fornecidos apenas ao juiz. Não orientam o usuário simulado nem o gateway em teste. | | `resources` | `[]` | Até 16 objetos `{ "type", "data" }` | Contexto adicional fornecido ao usuário simulado e ao juiz. Use `Text` para `data` literal ou `RemoteResource` para conteúdo recuperado da URL em `data`. | | `hooks` | `[]` | Até 16 objetos `{ "event", "url" }` | Callbacks externos para execuções persistentes. Eventos suportados: `before-test`, `after-test`, `before-inference`, `after-inference` e `context-changed`; `before-inference` e `after-inference` exigem um AI Gateway. | | `profile` | `medium` | `low`, `medium`, `high` | Seleciona o nível de capacidade e preço usado pelo usuário simulado e pelo juiz. Não substitui o modelo configurado no gateway em teste. | | `max_turns` | `10` | `2`–`64` | Número máximo de turnos do usuário simulado antes que a execução termine. | | `minimum_turns` | `1` | `1`–`63`, menor que `max_turns` | Primeiro turno em que o usuário simulado pode receber a opção de encerrar a conversa. | | `allow_user_exit` | `true` | Boolean | Quando habilitado, o prompt do usuário simulado expõe o token de saída da conversa a partir de `minimum_turns`. Quando desabilitado, essa opção é omitida em todos os prompts do usuário simulado. | | `judge_start_turn` | `1` | `1`–`63`, menor que `max_turns` | Primeiro turno avaliado pelo juiz. O último turno é sempre avaliado. | | `loss_threshold` | `0.2` | `0.01`–`0.99` | Limite usado para identificar uma trajetória persistentemente malsucedida. | | `base_threshold` | `0.9` | `0.01`–`0.99` | Pontuação igual ou acima da qual o objetivo é considerado alcançado. Deve ser maior que `loss_threshold`, com pelo menos `0.1` de diferença entre eles. | | `user_sampling.top_k` | `0.4` | `0`–`2` | Controla quantas características de comunicação amostradas guiam o usuário simulado. Valores maiores aumentam a variação. | | `user_sampling.max_decay` | `0.02` | `0`–`1` | Controla quanto as características amostradas do usuário podem mudar entre turnos. | Reduza `max_turns` para verificações de regressão rápidas e delimitadas. Aumente-o para fluxos que naturalmente exigem descoberta ou várias chamadas de ferramenta. `minimum_turns` e `judge_start_turn` devem ser menores que `max_turns`; eles são independentes. Adie `judge_start_turn` quando se espera esclarecimento precoce e pontuações intermediárias não são úteis. Desative `allow_user_exit` quando apenas o juiz ou o orçamento de turnos devem encerrar o teste; `minimum_turns` controla apenas quando o usuário simulado vê sua opção de saída e não atrasa decisões do juiz. Mantenha uma diferença ampla entre os limites de perda e de sucesso, a menos que a política tenha sido calibrada contra conversas representativas. Testes Agentes cobram a inferência do gateway selecionado mais o uso do usuário simulado e do juiz nas taxas do perfil selecionado. Veja [Pricing](https://docs.aivax.net/pt-br/docs/pricing.md#agentic-tests) para as taxas atuais. ## Execução direta por API Cada avaliação direta consome uma unidade da mesma cota de conta que as execuções persistentes. Se essa cota for excedida, a requisição retorna HTTP 429 antes de abrir o stream SSE. Verifique o status HTTP antes de processar eventos e use tentativas limitadas com backoff. Veja [Plans and limits](https://docs.aivax.net/pt-br/docs/limits.md#semantic-decision-and-agentic-test-rate-limits). Use o endpoint de geração direta quando uma aplicação precisar executar um teste efêmero e consumir seus eventos imediatamente. Uma execução direta **não** cria um caso de teste persistente nem uma execução no painel. Autentique‑se com uma chave de API privada do AIVAX, envie `Accept: text/event-stream` e mantenha a chave em um backend confiável. Não exponha uma chave privada em código de navegador ou em um bundle de aplicação distribuída. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Evaluate%20Agentic%20Test) A requisição aceita as mesmas configurações principais de avaliação de um teste persistente. Use `model` para o slug do AI Gateway, `goal` para o resultado desejado compartilhado com o usuário simulado e o juiz, `validation_criteria` para requisitos opcionais apenas do juiz, `minimum_turns` e `allow_user_exit` para controlar quando o usuário simulado vê sua opção de saída, `judge_start_turn` para agendar a avaliação do juiz, `start` para mensagens iniciais opcionais, `resources` para contexto adicional `Text` ou `RemoteResource`, e `external_user_id` para uma identidade encaminhada à inferência do gateway. Todo mensagem de Server‑Sent Events contém este envelope: ```json { "timestamp": 1786329000000, "event": { "type": "chat.start", "data": { "turn_number": 1, "max_remaining_turns": 10 } } } ``` Roteie mensagens por `event.type` e concatene blocos de conteúdo transmitidos em ordem. Os exemplos abaixo mostram o objeto `event` dentro do envelope SSE. Marcadores de ciclo de vida (`start_generation`, `end_generation`, `turn_analysis_start`, `turn_analysis_end`) carregam um objeto vazio (`data: {}`); blocos de raciocínio compartilham a forma `{ "reasoning_content": "..." }`. Apenas eventos que carregam conteúdo são mostrados integralmente. - **`chat.start`** — Inicia um turno e reporta seu número e o orçamento de turnos restante. ```json { "type": "chat.start", "data": { "turn_number": 1, "max_remaining_turns": 10 } } ``` - **`chat.user_message.start_generation`** — Marca o início da geração da mensagem do usuário simulado (`data: {}`). - **`chat.user_message.reasoning`** — Transmite um bloco de raciocínio exposto pelo modelo do usuário simulado. Use apenas para depuração. - **`chat.user_message.content`** — Transmite um bloco de conteúdo da mensagem do usuário simulado. Concatene blocos consecutivos na ordem de chegada. ```json { "type": "chat.user_message.content", "data": { "content": "Você pode explicar a política de reembolso?" } } ``` - **`chat.user_message.end_generation`** — Marca o fim da geração da mensagem do usuário simulado (`data: {}`). - **`chat.user_message.end_conversation`** — Reporta uma saída permitida do usuário simulado após `minimum_turns`. Este evento não é emitido quando `allow_user_exit` está desativado. ```json { "type": "chat.user_message.end_conversation", "data": { "reason": "simulated_user_ended_conversation" } } ``` - **`chat.assistant_message.start_generation`** — Marca o início da resposta do gateway selecionado (`data: {}`). - **`chat.assistant_message.reasoning`** — Transmite um bloco de raciocínio exposto pelo modelo do gateway (mesma forma `reasoning_content`). - **`chat.assistant_message.refusal`** — Reporta uma recusa retornada pelo modelo do gateway. - **`chat.assistant_message.tool_call`** — Reporta uma chamada de ferramenta do assistente, incluindo seu ID, nome e argumentos. - **`chat.assistant_message.tool_result`** — Reporta o resultado de uma ferramenta, incluindo o ID da chamada associada, nome e conteúdo. - **`chat.assistant_message.content`** — Transmite um bloco de conteúdo da resposta do assistente. Concatene blocos consecutivos na ordem de chegada. ```json { "type": "chat.assistant_message.content", "data": { "content": "Reembolsos estão disponíveis dentro de 30 dias." } } ``` - **`chat.assistant_message.end_generation`** — Marca o fim da resposta do gateway selecionado (`data: {}`). - **`chat.judge.turn_analysis_start`** — Marca o início de uma avaliação contra o objetivo e quaisquer critérios de validação apenas do juiz (`data: {}`). - **`chat.judge.turn_analysis_result_ready`** — Retorna o raciocínio do juiz, pontuação normalizada, estado atual, medições de trajetória e decisão de continuação. `score` varia de `0.001` a `0.999`; `pass` é falso somente após uma perda persistente ser estabelecida. ```json { "type": "chat.judge.turn_analysis_result_ready", "data": { "result": { "reasoning": "A resposta atendeu ao resultado solicitado e aos critérios de validação.", "score": 0.92, "pass": true, "should_continue": false, "state": "success", "turn_delta": 0.84, "conversation_delta": 1.0, "loss_streak": 0, "required_loss_streak": 2 } } } ``` - **`chat.judge.turn_analysis_end`** — Marca o fim da avaliação do turno atual (`data: {}`). - **`usage_updated`** — Reporta uso de tokens de prompt, prompt em cache e conclusão. `role` é `user`, `assistant` ou `judge` dependendo da inferência que gerou o uso. ```json { "type": "usage_updated", "data": { "role": "judge", "usage": { "prompt_tokens": 1240, "cached_prompt_tokens": 320, "completion_tokens": 180 } } } ``` - **`unhandled_error`** — Reporta um erro de inferência, seu escopo e se a operação será reexecutada. `scope` é `user_inference`, `gateway_inference` ou `judge_analysis`. ```json { "type": "unhandled_error", "data": { "error": "O provedor de inferência está temporariamente indisponível.", "scope": "gateway_inference", "will_retry": true } } ``` - **`chat.validation.end`** — Reporta o resultado final e encerra a avaliação. O nome legado do evento é preservado para compatibilidade. `score` é incluído quando o resultado final segue uma avaliação do juiz, mas pode estar ausente quando o orçamento de turnos se esgota. ```json { "type": "chat.validation.end", "data": { "outcome": "success", "reason": "baseline_reached", "state": "success", "turn_number": 3, "score": 0.92, "conversation_delta": 1.0, "loss_streak": 0 } } ``` O estado do juiz pode ser `active`, `at_risk`, `success` ou `loss`. Um turno fraco não falha imediatamente uma conversa recuperável: a pontuação baixa e a trajetória cumulativa devem permanecer iguais ou abaixo do limite de perda configurado para as avaliações consecutivas necessárias. Os resultados finais são: | Resultado | Significado | | --- | --- | | `success` | O juiz atingiu `base_threshold`, ou o usuário simulado declarou o objetivo concluído. | | `loss` | A pontuação e a trajetória cumulativa permaneceram iguais ou abaixo de `loss_threshold` nas avaliações consecutivas necessárias. | | `incomplete` | A conversa esgotou `max_turns` sem alcançar sucesso ou uma perda persistente. | | `interrupted` | Uma regra de validação interrompeu a avaliação antes de concluí‑la. | Uma chave ausente ou inválida retorna `401 Unauthorized`; uma chave de API pública retorna `403 Forbidden`; saldo insuficiente retorna `402 Payment Required`; e campos malformados, slugs de gateway indisponíveis ou combinações de limites inválidas retornam `400 Bad Request`. Uma falha de inferência pode chegar como um evento SSE após o início da transmissão. Para investigar uma falha de inferência, revise a [configuração do AI Gateway](https://docs.aivax.net/pt-br/docs/inference/ai-gateway.md) usada pelo teste. --- Source: https://docs.aivax.net/pt-br/docs/inference/voice-session.html # Sessão de Voz Sessão de Voz é a API de conversação por voz em tempo real e com estado da AIVAX. Um WebSocket autenticado transporta áudio do microfone, eventos de detecção de fala, transcrições, turnos de IA, segmentos WAV sintetizados, interrupções e chamadas de ferramentas executadas pelo cliente durante a vida da conversação. O agente também pode encerrar a chamada diretamente através da ferramenta `end_call` fornecida pelo servidor. Use a Sessão de Voz quando o usuário deve poder falar naturalmente, ouvir o assistente assim que o áudio estiver pronto e interromper uma resposta falando novamente. A AIVAX possui o pipeline de fala‑para‑texto, inferência conversacional, histórico de turnos, detecção de atividade de voz no servidor, segmentação de respostas e texto‑para‑fala. Use os endpoints independentes [Audio Transcriptions](https://docs.aivax.net/pt-br/docs/generations/audio-transcriptions.md) e [Speech Generation](https://docs.aivax.net/pt-br/docs/generations/speech.md) quando sua aplicação processa gravações completas ou já tem o texto final. Use a [Inference](https://docs.aivax.net/pt-br/docs/inference/inference.md) regular quando a interação for primeiro texto ou sua aplicação precisar orquestrar cada etapa de forma independente. ## O que uma sessão faz Após a atualização do WebSocket, o cliente envia uma mensagem de configuração. A AIVAX valida a configuração e cria imediatamente o primeiro turno do assistente, que produz uma saudação curta baseada no Gateway de IA selecionado e no contexto opcional da sessão. Para o restante da conexão: 1. O cliente envia continuamente quadros PCM mono, incluindo o silêncio entre falas. 2. A AIVAX detecta quando a fala começa e para. 3. Quando a fala para, a AIVAX transcreve a fala capturada. 4. A AIVAX adiciona a transcrição à conversa da sessão e inicia uma resposta de IA. 5. Segmentos WAV sintetizados são enviados assim que ficam disponíveis. 6. Se o usuário começar a falar enquanto o assistente está respondendo, a AIVAX cancela essa resposta e começa a capturar a nova fala. 7. O cliente relata a conclusão da reprodução ou o corte exato da reprodução para que a conversa retenha apenas o conteúdo do assistente que o usuário realmente ouviu. 8. Quando a conversa termina ou o chamador pede para desligar, o agente pode invocar `end_call` e a AIVAX fecha o WebSocket do servidor aproximadamente 200 ms depois. O estado da conversa existe apenas para o WebSocket ativo. Fechar a conexão, incluindo um `end_call` do lado do servidor, encerra a sessão. Reconectar cria uma nova sessão e uma nova saudação; o protocolo não retoma uma sessão desconectada. ## Quando usar a Sessão de Voz A Sessão de Voz é adequada para: - assistentes conversacionais com microfone e reprodução por alto-falante; - suporte mãos‑livres, tutoriais, intake e fluxos guiados; - respostas de baixa latência que devem começar a tocar antes que a resposta completa seja sintetizada; - conversas onde os usuários podem interromper o assistente naturalmente; - agentes de voz que expõem ferramentas de propriedade da aplicação e retornam seus resultados pela mesma conexão. Prefira outra API quando: - precisar apenas de transcrição, sem resposta de IA; - precisar sintetizar um texto conhecido uma única vez; - o cliente envia gravações completas de forma assíncrona; - precisar escolher o modelo de fala‑para‑texto ou texto‑para‑fala de forma independente; - a única fronteira de autenticação disponível for uma chave pública de navegador. ## Endpoint e autenticação
GET /api/v1/voice-session
Abra o endpoint de produção como: ```text wss://inference.aivax.net/api/v1/voice-session ``` A requisição HTTP deve ser uma atualização de WebSocket autenticada com uma chave de API **privada**. Chaves de API públicas não podem abrir sessões de voz. Autenticação preferencial: ```http Authorization: Bearer ``` O parâmetro de consulta padrão `?api-key=` também é aceito, mas use‑o somente quando a biblioteca de WebSocket não puder definir cabeçalhos. Strings de consulta são comumente retidas pelo histórico do navegador, proxies reversos, logs de acesso e sistemas de monitoramento. > [!WARNING] > JavaScript do navegador não pode adicionar um cabeçalho `Authorization` ao construtor nativo `WebSocket`, e uma chave de API privada nunca deve ser enviada a um navegador ou pacote móvel. Para um cliente final, encerre a conexão do navegador no seu backend e deixe esse backend abrir o WebSocket autenticado da AIVAX. Não contorne essa fronteira colocando uma chave privada na URL enviada ao navegador. A conexão pode falhar antes da atualização com: - `400 Bad Request` quando a requisição não é uma atualização de WebSocket válida; - `401 Unauthorized` quando a chave está ausente ou inválida; - um erro de API quando uma chave pública é usada. A AIVAX envia a mensagem de texto simples `keep-alive` a cada 10 segundos para manter a conexão ativa. Isso é uma mensagem de texto de aplicação, não um evento JSON ou quadro de controle ping do WebSocket. Os clientes devem ignorá‑la antes de analisar as mensagens do servidor como JSON. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Open%20voice%20session) ## Visão geral do protocolo Eventos de aplicação em ambas as direções são mensagens de texto JSON UTF‑8 do WebSocket. A única mensagem de aplicação não‑JSON é o heartbeat de texto simples `keep-alive` do servidor, enviado a cada 10 segundos; descarte‑o antes da análise JSON. O áudio é codificado em base64 dentro dos eventos JSON, e o protocolo não aceita mensagens binárias do WebSocket. Uma sessão típica segue este cronograma: | Etapa | Direção | Evento | Observações | | ---: | --- | --- | --- | | 1 | Cliente → AIVAX | Atualização de WebSocket | Autenticar com uma chave de API privada. | | 2 | Cliente → AIVAX | `session_start` | Configurar e iniciar a sessão. | | 3 | AIVAX → Cliente | `response.created` | Iniciar a saudação inicial. | | 4 | AIVAX → Cliente | `response.inference_started` | Começar a gerar a saudação. | | 5 | AIVAX → Cliente | `response.tts_started` | Iniciar a síntese de fala. | | 6 | AIVAX → Cliente | `output_audio` | Receber um ou mais segmentos WAV. | | 7 | AIVAX → Cliente | `response.inference_done` | Concluir a geração da saudação. | | 8 | AIVAX → Cliente | `response.done` | Concluir a resposta. | | 9 | Cliente → AIVAX | `output_audio_buffer.playback_completed` | Confirmar que a reprodução terminou. | | 10 | Cliente → AIVAX | `input_audio_buffer.append` | Enviar continuamente quadros PCM. | | 11 | AIVAX → Cliente | `input_audio_buffer.possible_speech` | Reportar um sinal precoce de fala. | | 12 | AIVAX → Cliente | `input_audio_buffer.speech_started` | Confirmar que a fala começou. | | 13 | AIVAX → Cliente | `input_audio_buffer.speech_stopped` | Reportar que a fala parou. | | 14 | AIVAX → Cliente | `input_audio_buffer.stt_started` | Iniciar a transcrição. | | 15 | AIVAX → Cliente | `input_audio_buffer.stt_done` | Retornar a transcrição. | | 16 | AIVAX → Cliente | `response.created` | Iniciar o turno de resposta. | | 17 | AIVAX → Cliente | `output_audio` | Transmitir a resposta sintetizada. | | 18 | AIVAX → Cliente | `response.done` | Concluir a resposta. | | 19 | Cliente → AIVAX | `output_audio_buffer.playback_completed` | Confirmar que a reprodução terminou. | O servidor pode enviar o heartbeat de texto simples `keep-alive` entre qualquer dessas etapas. Não faz parte da sequência numerada de eventos e deve ser descartado antes da análise JSON. `possible_speech` é um sinal precoce e pode ser seguido por fala confirmada ou silêncio. Não interrompa a reprodução atual nesse evento. Um `speech_started` confirmado é o limite de interrupção. ## Iniciar a sessão A primeira mensagem do WebSocket deve ser a configuração da sessão. Nenhum áudio ou outro evento pode ser enviado antes disso. O envelope recomendado é: ```json { "event_type": "session_start", "session": { "voice": "Eve", "gateway": "support-assistant", "language": null, "reasoning_effort": "minimal", "context": "The caller is using the account recovery screen.", "tools": [] } } ``` Para compatibilidade, a primeira mensagem também pode conter as propriedades de configuração diretamente, sem `event_type` e `session`. Clientes novos devem usar o envelope explícito `session_start`. ### Propriedades de configuração | Propriedade | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `voice` | `string` | Sim | Voz usada para cada resposta sintetizada na sessão. A correspondência não diferencia maiúsculas de minúsculas. | | `gateway` | `string` | Não | Slug ou identificador do Gateway de IA usado como configuração do agente. Quando omitido, a AIVAX usa o padrão atual da Sessão de Voz. A Sessão de Voz substitui o modelo principal do gateway por um modelo otimizado para conversação de baixa latência. | | `language` | `string` ou `null` | Não | Dica de idioma encaminhada para a transcrição de fala, como `en`, `pt` ou `pt-BR`. Quando nulo, vazio ou omitido, a AIVAX usa `auto` para que o modelo de transcrição detecte o idioma falado. | | `reasoning_effort` | `string` | Não | `minimal`, `low`, `medium` ou `high`. O padrão é `minimal`. Esforço maior pode aumentar a latência da resposta e o uso. | | `context` | `string` | Não | Contexto adicional ao nível da sessão fornecido ao agente. Use para fatos relevantes e não secretos sobre esta chamada ou jornada do usuário. | | `tools` | `array` | Não | Definições de ferramentas compatíveis com OpenAI. O cliente executa essas ferramentas e retorna eventos `tool_result`. | > [!IMPORTANT] > A Sessão de Voz não executa o modelo principal configurado do gateway. Ela preserva o gateway como configuração do agente e substitui seu modelo principal por um modelo gerenciado pela AIVAX otimizado para baixa latência. Não dependa da identidade, capacidades ou comportamento específico do modelo principal do gateway ao projetar uma integração de voz. Vozes suportadas: `Carina`, `Zagan`, `Helix`, `Orion`, `Luna`, `Iris`, `Altair`, `Zenith`, `Perseus`, `Helios`, `Lux`, `Kepler`, `Rigel`, `Cosmo`, `Celeste`, `Ursa`, `Sirius`, `Lumen`, `Castor`, `Naksh`, `Atlas`, `Ara`, `Eve`, `Leo`, `Rex` e `Sal`. Se a primeira mensagem não for JSON válido, não contiver uma configuração válida, nomear uma voz ou esforço de raciocínio não suportados, ou referenciar um gateway indisponível, a AIVAX envia um evento `error` e fecha a conexão. Esteja pronto para receber eventos de resposta imediatamente após uma configuração válida, pois a saudação inicial começa automaticamente; não há um evento separado `session.ready`. ## Enviar áudio do microfone em tempo real O evento de entrada recomendado é `input_audio_buffer.append`: ```json { "event_type": "input_audio_buffer.append", "audio": { "sequence": 42, "format": "pcm_s16le", "sample_rate": 16000, "channels": 1, "data": "" } } ``` A propriedade pode ser nomeada `audio` ou `input_audio`; use `audio` em novas integrações. ### Contrato de quadro de áudio | Propriedade | Valor exigido | Observações | | --- | --- | --- | | `sequence` | Inteiro crescente | Deve ser maior que todo ` enviado anteriormente nesta conexão WebSocket. Comece em `0` e incremente uma vez por quadro. Não reinicie entre falas. | | `format` | `pcm_s16le` | PCM bruto assinado de 16 bits little‑endian. Não inclua cabeçalho WAV. | | `sample_rate` | `16000` | Reamostra a entrada do microfone antes de enviá‑la. | | `channels` | `1` | Converta entrada estéreo para mono. | | `data` | String base64 não vazia | Após decodificação, a contagem de bytes deve ser par porque cada amostra ocupa dois bytes. | Envie quadros continuamente enquanto a captura do microfone está ativa, incluindo silêncio. Não espere o usuário terminar de falar e não envie um evento “commit” do lado do cliente: a AIVAX detecta o limite da fala e a confirma automaticamente. Um quadro de 32 ms contém 512 amostras, ou 1 024 bytes antes da codificação base64. Esse é um tamanho de quadro prático porque oferece entrega em tempo real suave sem enviar mensagens excessivamente pequenas. Outros tamanhos de quadros não vazios e pares são aceitos e armazenados em buffer entre mensagens. Mantenha um único produtor de quadros de microfone ou serialize o acesso ao so. Se dois produtores assíncronos entrarem em competição, seus valores `sequence` podem chegar fora de ordem e causar `invalid_audio_frame`. ### Capturando o formato PCM correto A saída do `MediaRecorder` do navegador normalmente é WebM/Opus comprimido, não PCM bruto, e não pode ser enviada diretamente. Capture amostras através de um audio worklet ou API de áudio nativa, então: 1. converta para um canal; 2. reamostra para 16 000 Hz; 3. limite cada amostra ponto flutuante a `[-1, 1]`; 4. converta para PCM assinada de 16 bits little‑endian; 5. codifique em base64 os bytes resultantes; 6. envie quadros em ordem de sequência monotonicamente crescente. Não rotule áudio comprimido como `pcm_s16le`; o quadro pode passar na validação básica de forma, mas produzirá detecção de fala e transcrição inutilizáveis. ## Eventos de detecção de fala e transcrição A AIVAX envia os seguintes eventos enquanto processa entrada em tempo real. ### `input_audio_buffer.possible_speech` Um sinal precoce e tentativo de atividade de voz: ```json { "event_type": "input_audio_buffer.possible_speech", "sequence": 42, "probability": 0.72 } ``` Use apenas para feedback sutil de UI, como mudar o indicador de microfone. Não é um limite de fala confirmado e não deve limpar a reprodução do assistente. ### `input_audio_buffer.speech_started` Fala confirmada: ```json { "event_type": "input_audio_buffer.speech_started", "sequence": 48, "probability": 0.91 } ``` Neste ponto, trate o usuário como interrompendo qualquer resposta ativa. A AIVAX cancela o turno ativo e, quando aplicável, segue com `response.cancelled` e `output_audio_cancelled`. Pare a reprodução imediatamente quando o evento de cancelamento chegar; não continue reproduzindo segmentos já enfileirados. ### `input_audio_buffer.speech_stopped` A fala atual terminou e foi confirmada para transcrição: ```json { "event_type": "input_audio_buffer.speech_stopped", "sequence": 77, "probability": 0.12 } ``` O cliente não precisa enviar outro evento para confirmar o buffer. ### `input_audio_buffer.stt_started` A transcrição começou para a fala confirmada: ```json { "event_type": "input_audio_buffer.stt_started", "sequence": 77 } ``` Use este evento para um estado “transcrevendo”. Não inicie uma resposta de IA localmente. ### `input_audio_buffer.stt_done` Transcrição concluída: ```json { "event_type": "input_audio_buffer.stt_done", "sequence": 77, "transcript": "Can you help me reset my password?" } ``` Exiba ou registre a transcrição se seu produto exigir. Quando a transcrição não está vazia, a AIVAX a adiciona automaticamente à conversa e inicia a próxima resposta. Uma transcrição vazia não cria um turno de resposta. O `sequence` nesses eventos identifica o quadro de áudio cliente mais recente envolvido no limite detectado. Não é a mesma sequência da sequência de eventos de resposta ordenados descrita abaixo. ## Receber e reproduzir respostas do assistente Cada resposta pertence a um `turn_id` numérico e a um `response_id` string. - `turn_id` identifica a tentativa de geração do lado do servidor dentro desta conexão. - `response_id` identifica a resposta reproduzível do assistente e é a chave que o cliente deve usar para filas de reprodução, reconhecimentos de conclusão e truncamento. - `sequence` aparece em payloads de resposta ordenados como `output_audio` e `tool_call`. Começa em `0` para cada turno de resposta e aumenta nesses payloads. Eventos de ciclo de vida podem ser intercalados com trabalho de áudio. Use `response_id` para correlação e preserve a ordem de chegada do WebSocket. Para payloads que carregam `sequence`, verifique se os valores aumentam dentro da resposta. Payloads de áudio e chamada de ferramenta compartilham esse contador, portanto um salto entre dois valores de sequência de áudio pode representar um `tool_call`; não espere outro evento de áudio para preenchê‑lo. ### `response.created` Um turno de resposta foi criado: ```json { "event_type": "response.created", "turn_id": 3, "response_id": "" } ``` Crie o estado de resposta do cliente e a fila de reprodução aqui. ### `response.inference_started` O agente começou a gerar a resposta: ```json { "event_type": "response.inference_started", "turn_id": 3, "response_id": "" } ``` ### `response.inference_done` O fluxo de inferência terminou. A síntese de áudio ainda pode estar finalizando, portanto isso não é um sinal de reprodução concluída: ```json { "event_type": "response.inference_done", "turn_id": 3, "response_id": "" } ``` ### `response.tts_started` A AIVAX começou a sintetizar áudio reproduzível: ```json { "event_type": "response.tts_started", "turn_id": 3, "response_id": "" } ``` Quando `kind` é `tool_preamble`, o áudio explica uma ação de ferramenta futura em vez de entregar a resposta final. ### `output_audio` Um segmento WAV reproduzível está pronto: ```json { "event_type": "output_audio", "turn_id": 3, "response_id": "", "sequence": 0, "output_audio": { "data": "", "format": "wav", "duration_ms": 1380 } } ``` Decodifique `output_audio.data` de base64 e enfileire o arquivo WAV completo. Cada evento é um segmento WAV reproduzível de forma independente; não concatene strings base64 nem presuma que um evento contém a resposta completa. Preserve a ordem de chegada do WebSocket e verifique se `sequence` aumenta para o mesmo `response_id`. `duration_ms` é a duração do segmento calculada pelo servidor e é útil para contabilidade de reprodução. Para truncamento preciso, prefira a posição real reproduzida pelo player de mídia e use durações apenas como fallback. Um evento `output_audio` pode incluir: ```json { "kind": "tool_preamble" } ``` Áudio de pré‑ámbulo de ferramenta pertence à mesma linha de tempo de reprodução ordenada. Inclua sua duração reproduzida ao relatar `audio_end_ms`, embora a AIVAX exclua esse pré‑ámbulo ao decidir quais frases de resposta permanecem no histórico da conversa. ### `response.tts_done` A AIVAX concluiu a fase de síntese de pré‑ámbulo de ferramenta: ```json { "event_type": "response.tts_done", "turn_id": 3, "response_id": "", "kind": "tool_preamble" } ``` Este evento é atualmente emitido para uma resposta de ferramenta do cliente. Use `response.done`, não `response.tts_done`, como limite geral do ciclo de vida da resposta. ### `response.done` A AIVAX terminou de produzir eventos para esta resposta: ```json { "event_type": "response.done", "turn_id": 3, "response_id": "" } ``` `response.done` significa que o servidor não adicionará mais conteúdo a essa resposta. Não **significa** que o usuário ouviu todo o áudio enfileirado. Continue a reprodução, então envie `output_audio_buffer.playback_completed` após o segmento final realmente terminar. ## Confirmar reprodução Quando todo o áudio enfileirado para uma resposta foi reproduzido com sucesso, envie: ```json { "event_type": "output_audio_buffer.playback_completed", "response_id": "" } ``` Envie uma vez por `response_id` concluído, após a reprodução — não quando `response.done` chega e não apenas quando todos os arquivos WAV foram baixados. Isso permite que a AIVAX descarte o rastreamento temporário de reprodução para essa resposta. Não envie este evento para uma resposta que foi cancelada antes da reprodução concluir. Relate o corte real com `conversation.item.truncate` em vez disso. ## Lidar com interrupções e truncamento A Sessão de Voz suporta barge‑in: o usuário pode falar sobre uma resposta ativa do assistente. Quando a fala confirmada interrompe uma resposta, a AIVAX envia: ```json { "event_type": "response.cancelled", "turn_id": 3, "response_id": "" } ``` e: ```json { "event_type": "output_audio_cancelled", "turn_id": 3, "response_id": "" } ``` Ao receber `output_audio_cancelled`: 1. pare o áudio atualmente reproduzido para esse `response_id` imediatamente; 2. descarte todo segmento enfileirado mas não reproduzido para essa resposta; 3. meça quantos milissegundos da linha de tempo da resposta foram realmente ouvidos; 4. envie `conversation.item.truncate` com esse corte. Evento recomendado: ```json { "event_type": "conversation.item.truncate", "truncate": { "response_id": "", "audio_end_ms": 1840 } } ``` A forma plana também é aceita: ```json { "event_type": "conversation.item.truncate", "response_id": "", "audio_end_ms": 1840 } ``` `audio_end_ms` é o tempo de reprodução decorrido não‑negativo desde o início da linha de tempo de áudio da resposta, incluindo qualquer pré‑ámbulo de ferramenta que foi reproduzido. Não é tempo de relógio real nem a duração apenas do segmento WAV atual. A AIVAX reconhece a atualização: ```json { "event_type": "conversation.item.truncated", "response_id": "", "audio_end_ms": 1840 } ``` Por que o truncamento importa: o áudio pode ser gerado e adicionado ao turno do assistente antes que o usuário o ouça. Relatar o corte real impede que frases não ouvidas influenciem respostas posteriores como se tivessem sido faladas. Se a reprodução nunca começou, envie `audio_end_ms: 0`. Um player robusto deve manter, por `response_id`: - duração concluída de segmentos totalmente reproduzidos; - posição de reprodução do segmento atual; - se a resposta foi cancelada; - segmentos enfileirados indexados por `sequence`; - a maior sequência contígua já consumida. Calcule o corte como a duração do segmento concluído mais a posição real dentro do segmento interrompido. ## Ferramentas executadas pelo cliente A configuração opcional `tools` permite que o modelo solicite uma ação que seu cliente ou backend possui. As definições usam o formato de ferramenta de função do OpenAI: ```json { "event_type": "session_start", "session": { "voice": "Eve", "gateway": "support-assistant", "tools": [ { "type": "function", "function": { "name": "lookup_order", "description": "Look up an order visible to the authenticated caller.", "parameters": { "type": "object", "properties": { "order_number": { "type": "string", "description": "The order number provided by the caller." } }, "required": ["order_number"], "additionalProperties": false } } } ] } } ``` Quando o modelo seleciona uma ferramenta do cliente, a AIVAX pode primeiro enviar áudio de pré‑ámbulo de ferramenta, então envia: ```json { "event_type": "tool_call", "turn_id": 4, "response_id": "", "sequence": 1, "tool_call": { "id": "", "name": "lookup_order", "content": { "order_number": "A-1042" } } } ``` Trate `content` como saída de modelo não confiável, mesmo que seja baseada no seu esquema. Valide tipos, valores permitidos, autorização do usuário e regras de negócio antes de executar a ação. Ignore ou remova `_tool_reason` e `_tool_goal` antes da validação estrita de esquema se sua aplicação não os definir; são metadados conversacionais usados para explicar a ação. Retorne o resultado como string: ```json { "event_type": "tool_result", "tool_result": { "id": "", "result": "{\"status\":\"shipped\",\"estimated_delivery\":\"2026-08-08\"}" } } ``` Regras importantes para ferramentas: - ecoar exatamente o `tool_call.id` em `tool_result.id`; - enviar um resultado para cada chamada de ferramenta pendente; - quando várias chamadas são emitidas, a AIVAX aguarda todos os resultados chegarem antes de iniciar a resposta de acompanhamento; - `result` deve ser uma string; serialize dados estruturados para JSON primeiro; - mantenha os resultados concisos e exclua segredos que o modelo não precise; - retorne falhas de aplicação como uma string de resultado clara para que o modelo possa explicar ou se recuperar delas; - não tente novamente a mesma ferramenta com efeitos colaterais após reconexão; - se o usuário começar a falar, chamadas de ferramenta pendentes podem ser canceladas e resultados posteriores podem ser rejeitados como `unknown_tool_call`. A resposta contendo a solicitação de ferramenta ainda termina com `response.done`. A resposta de acompanhamento após todos os resultados de ferramenta é uma nova resposta com um novo `turn_id` e `response_id`. ## Encerramento de chamada do lado do servidor Cada Sessão de Voz fornece automaticamente ao agente uma ferramenta `end_call` além das ferramentas do cliente configuradas em `session.tools`. Use as instruções do gateway ou o contexto da sessão para dizer ao agente quando encerrar a chamada é apropriado, por exemplo, após o chamador dizer adeus ou pedir explicitamente para desligar. `end_call` é executado inteiramente pela AIVAX: - os clientes não devem adicioná‑la a `session.tools`; - a AIVAX não emite um evento `tool_call` para ela; - os clientes não enviam um `tool_result` para ela; - o servidor fecha o WebSocket aproximadamente 200 ms depois que o agente a invoca. Trate isso como um fechamento remoto normal. Pare a captura do microfone e a reprodução e limpe o estado escopo da sessão no manipulador de fechamento do WebSocket. O pequeno atraso é apenas uma margem de término ordenado; não dependa de outro evento de resposta ou segmento de áudio final chegando antes do fechamento. ## Entrada WAV completa `input_audio` é um caminho de compatibilidade para clientes que já possuem uma gravação WAV completa: ```json { "event_type": "input_audio", "input_audio": { "format": "wav", "data": "" } } ``` O payload decodificado deve ser um arquivo RIFF/WAVE válido com no máximo 75 MB. A AIVAX transcreve como uma única fala e inicia automaticamente uma resposta. Use este caminho apenas para gravações completas. Ele não fornece limites de fala em tempo real no servidor e usa `sequence: 0` nos eventos de ciclo de vida de transcrição. Não o misture com uma fala em tempo real ativa. Prefira `input_audio_buffer.append` para conversas interativas, menor latência percebida e comportamento de barge‑in. ## Referência de eventos cliente‑para‑servidor | Evento | Quando enviar | Payload obrigatório | | --- | --- | --- | | `session_start` | Exatamente uma vez, como a primeira mensagem do WebSocket. | `session.voice`; opcional `gateway`, `language`, `reasoning_effort`, `context` e `tools`. | | `input_audio_buffer.append` | Continuamente enquanto a captura de microfone em tempo real está ativa. | `audio.sequence`, `format`, `sample_rate`, `channels` e `data` base64. | | `input_audio` | Uma vez por fala WAV legada completa. | `input_audio.format: "wav"` e `data` base64. | | `output_audio_buffer.playback_completed` | Após o segmento de áudio final de uma resposta realmente terminar de reproduzir. | `response_id`. | | `conversation.item.truncate` | Após reprodução cancelada ou interrompida. | `response_id` e `audio_end_ms` decorrido. | | `tool_result` | Após executar uma chamada de ferramenta pendente do cliente. | `tool_result.id` correspondente e `result` string. | Não há evento cliente para confirmar um buffer de entrada em tempo real, solicitar a saudação inicial, criar manualmente uma resposta normal ou cancelar uma resposta. Limites de fala e interrupção conduzem essas ações automaticamente. ## Referência de eventos servidor‑para‑cliente | Evento | Significado | Ação importante | | --- | --- | --- | | `input_audio_buffer.possible_speech` | Atividade de voz tentativa. | Atualizar UI apenas; não interromper a reprodução. | | `input_audio_buffer.speech_started` | Fala do usuário confirmada. | Marcar microfone ativo e esperar cancelamento da resposta. | | `input_audio_buffer.speech_stopped` | Fala confirmada. | Mostrar estado de processamento; não enviar evento de commit. | | `input_audio_buffer.stt_started` | Transcrição iniciada. | Opcionalmente mostrar “transcrevendo”. | | `input_audio_buffer.stt_done` | Transcrição disponível. | Exibir a transcrição; a AIVAX inicia a resposta automaticamente quando não vazia. | | `response.created` | Nova identidade de resposta alocada. | Criar estado e fila de reprodução. | | `response.inference_started` | Geração de agente iniciada. | Opcionalmente mostrar “pensando”. | | `response.inference_done` | Geração de agente concluída. | Não tratar como conclusão de áudio. | | `response.tts_started` | Síntese de áudio iniciada. | Preparar o player; inspecionar `kind` opcional. | | `output_audio` | Um segmento WAV completo. | Decodificar, ordenar por `sequence`, enfileirar e reproduzir. | | `response.tts_done` | Síntese de pré‑ámbulo de ferramenta concluída. | Informacional; aguardar `response.done`. | | `tool_call` | Ação solicitada pelo cliente. | Validar, autorizar, executar e enviar `tool_result`. | | `response.done` | Servidor terminou de produzir esta resposta. | Finalizar fila de reprodução, então reconhecer conclusão. | | `response.cancelled` | Geração ativa foi cancelada por fala. | Parar trabalho de UI relacionado à resposta. | | `output_audio_cancelled` | Reprodução enfileirada está obsoleta. | Parar/limpar áudio e relatar truncamento. | | `conversation.item.truncated` | Corte de reprodução registrado. | Liberar registro de truncamento. | | `error` | Erro de sessão, evento, transcrição ou turno. | Inspecionar `error.code`; decidir se continua ou reconecta. | ## Eventos de erro Erros usam este envelope: ```json { "event_type": "error", "error": { "code": "invalid_audio_frame", "message": "Realtime audio must be mono PCM signed 16-bit little-endian at 16000 Hz." } } ``` | Código | Causa | Recuperação | | --- | --- | --- | | `invalid_session` | A primeira mensagem não é um objeto de configuração válido. | Corrija o handshake e reconecte; a AIVAX fecha esta conexão. | | `invalid_reasoning_effort` | Esforço de raciocínio não suportado. | Use `minimal`, `low`, `medium` ou `high`, então reconecte. | | `invalid_voice` | Voz não suportada. | Selecione uma voz listada, então reconecte. | | `gateway_unavailable` | O gateway solicitado não pode ser resolvido para a conta. | Verifique o identificador do gateway e acesso, então reconecte. | | `invalid_event` | Uma mensagem pós‑handshake não é um objeto JSON. | Corrija a serialização; a sessão pode continuar. | | `unsupported_event` | `event_type` desconhecido ou ausente. | Envie um dos eventos de cliente documentados. | | `invalid_audio_frame` | Base64, formato, taxa de amostragem, canais, contagem de bytes ou sequência não crescente inválidos. | Corrija captura/ordenação antes de enviar mais quadros em tempo real. | | `invalid_audio` | Payload WAV completo ausente ou inválido, ou payload acima de 75 MB. | Envie um arquivo RIFF/WAVE válido ou use PCM em tempo real. | | `unsupported_audio_format` | Entrada de arquivo completo não declarada como WAV. | Converta para WAV ou use PCM em tempo real. | | `transcription_failed` | A fala confirmada não pôde ser transcrita. | Mantenha a conexão aberta; informe o usuário e capture uma nova fala. | | `invalid_tool_result` | Objeto `tool_result` ausente. | Envie o envelope documentado. | | `unknown_tool_call` | O ID não está pendente, já foi respondido ou foi cancelado. | Não reenvie; reconcilie o estado pendente do cliente. | | `turn_failed` | A resposta atual de IA ou fala não pôde ser concluída. | Mantenha a conexão aberta quando possível e permita outra fala; reconecte após falhas repetidas. | Erros de configuração são terminais porque ocorrem antes da sessão iniciar. Erros de eventos em tempo de execução são normalmente recuperáveis e não exigem fechar o socket por si só. Fechamento de transporte, falha de autenticação ou falhas repetidas de turno devem mover o cliente para um estado desconectado. ## Integração Node.js de referência O exemplo a seguir demonstra a máquina de estados do protocolo com o pacote `ws`. Ele intencionalmente deixa a captura de microfone e a reprodução de áudio específicas da plataforma para funções adaptadoras; essas partes diferem substancialmente entre navegadores, aplicações desktop, sistemas telefônicos e runtimes móveis. ```javascript import WebSocket from "ws"; const apiKey = process.env.AIVAX_API_KEY; if (!apiKey) { throw new Error("Set AIVAX_API_KEY to a private account API key."); } const socket = new WebSocket( "wss://inference.aivax.net/api/v1/voice-session", { headers: { Authorization: `Bearer ${apiKey}` } } ); let inputSequence = 0; const responses = new Map(); const pendingTools = new Map(); socket.on("open", () => { send({ event_type: "session_start", session: { voice: "Eve", gateway: "support-assistant", language: null, reasoning_effort: "minimal", context: "The caller is using the account recovery screen.", tools: [] } }); startPcmCapture((pcmS16le) => { send({ event_type: "input_audio_buffer.append", audio: { sequence: inputSequence++, format: "pcm_s16le", sample_rate: 16000, channels: 1, data: Buffer.from(pcmS16le).toString("base64") } }); }); }); socket.on("message", async (raw, isBinary) => { if (isBinary) { console.error("Unexpected binary WebSocket message"); return; } const message = raw.toString("utf8"); if (message === "keep-alive") { return; } const event = JSON.parse(message); switch (event.event_type) { case "response.created": responses.set(event.response_id, { lastSequence: -1, playedMs: 0, cancelled: false, serverDone: false, playback: Promise.resolve() }); break; case "output_audio": { const state = responses.get(event.response_id); if (!state || state.cancelled) break; if (event.sequence <= state.lastSequence) { throw new Error("Non-increasing response sequence"); } state.lastSequence = event.sequence; const wav = Buffer.from(event.output_audio.data, "base64"); const durationMs = event.output_audio.duration_ms; state.playback = state.playback.then(async () => { if (state.cancelled) return; await playWav(event.response_id, wav); state.playedMs += durationMs; }); break; } case "response.done": { const state = responses.get(event.response_id); if (!state) break; state.serverDone = true; await state.playback; await acknowledgeIfPlaybackFinished(event.response_id); break; } case "output_audio_cancelled": { const state = responses.get(event.response_id); if (!state) break; state.cancelled = true; const audioEndMs = await stopPlaybackAndGetElapsedMs(event.response_id); send({ event_type: "conversation.item.truncate", truncate: { response_id: event.response_id, audio_end_ms: Math.max(0, Math.round(audioEndMs)) } }); break; } case "tool_call": { const state = responses.get(event.response_id); if (state) { if (event.sequence <= state.lastSequence) { throw new Error("Non-increasing response sequence"); } state.lastSequence = event.sequence; } pendingTools.set(event.tool_call.id, event.tool_call); try { const result = await executeAuthorizedTool( event.tool_call.name, event.tool_call.content ); send({ event_type: "tool_result", tool_result: { id: event.tool_call.id, result: typeof result === "string" ? result : JSON.stringify(result) } }); } finally { pendingTools.delete(event.tool_call.id); } break; } case "input_audio_buffer.stt_done": console.log("User:", event.transcript); break; case "error": console.error(`Voice Session ${event.error.code}: ${event.error.message}`); break; } }); socket.on("close", () => { stopPcmCapture(); stopAllPlayback(); responses.clear(); pendingTools.clear(); }); socket.on("error", (error) => { console.error("Voice Session transport error:", error); }); function send(event) { if (socket.readyState !== WebSocket.OPEN) return; socket.send(JSON.stringify(event)); } async function acknowledgeIfPlaybackFinished(responseId) { const state = responses.get(responseId); if (!state || state.cancelled || !state.serverDone) return; if (isResponsePlaying(responseId)) return; send({ event_type: "output_audio_buffer.playback_completed", response_id: responseId }); responses.delete(responseId); } ``` Se adaptadores devem preservar estes invariantes: - `startPcmCapture` emite PCM mono s16le exatamente a 16 kHz; - apenas um caminho atribui e envia `inputSequence`; - cada resposta encadeia a reprodução através de sua promessa `playback` para que callbacks de mensagem não reproduzam segmentos simultaneamente; - `lastSequence` avança tanto para payloads de áudio quanto de chamada de ferramenta porque compartilham uma sequência de resposta; - `playWav` resolve após o segmento realmente ter sido reproduzido, não após ter sido enfileirado; - `stopPlaybackAndGetElapsedMs` retorna o tempo decorrido ao longo da linha de tempo completa da resposta; - `executeAuthorizedTool` valida argumentos e aplica a autorização do usuário atual; - o fechamento do socket, incluindo o fechamento iniciado por `end_call`, encerra captura, reprodução e trabalho pendente da aplicação. O exemplo serializa a reprodução aguardando cada segmento WAV. Uma UI de produção pode usar um worker de reprodução dedicado, mas deve manter a mesma ordenação, cancelamento e semânticas de conclusão. ## Reconexão e orientações de ciclo de vida Trate o WebSocket como um recurso com escopo de sessão: - abra‑o somente quando a experiência de voz estiver ativa; - envie a configuração imediatamente após `open`; - inicie quadros de microfone somente depois que a configuração foi enviada; - pare a captura do microfone antes de fechar intencionalmente o socket; - limpe filas de áudio e chamadas de ferramenta pendentes quando o socket fechar; - trate um fechamento de servidor após `end_call` como término de sessão intencional, não como falha de reconexão automática; - use backoff exponencial com jitter para falhas de transporte inesperadas; - não reproduza automaticamente quadros de áudio ou resultados de ferramentas da conexão anterior; - informe ao usuário que uma reconexão inicia uma nova conversa; - crie uma nova sequência de entrada começando em `0` somente para o novo WebSocket. Não tente novamente erros de configuração terminais sem mudar a configuração. Para falhas de rede transitórias, limite as tentativas e forneça um controle de reconexão explícito para que o usuário não fique preso em um loop invisível. ## Checklist de produção Antes de enviar, verifique se a integração: - mantém a chave de API privada em um backend confiável; - envia a configuração como a primeira e única mensagem `session_start`; - ignora o heartbeat de texto simples `keep-alive` antes de analisar eventos JSON; - captura PCM mono s16le verdadeiro a 16 kHz; - mantém `sequence` de entrada estritamente crescente durante toda a conexão; - continua enviando silêncio para que limites de fala do servidor possam ser concluídos; - decodifica cada evento `output_audio` como um arquivo WAV independente; - ordena payloads de resposta por seu `sequence` escopo de resposta; - separa filas de reprodução por `response_id`; - não confunde `response.done` com conclusão de reprodução; - envia a conclusão da reprodução somente após o usuário ouvir o segmento final; - para o áudio imediatamente ao receber `output_audio_cancelled`; - relata o corte real da reprodução através de `conversation.item.truncate`; - valida e autoriza cada chamada de ferramenta do cliente; - retorna cada resultado de ferramenta pendente com o ID exato da chamada; - trata `error`, `error` de socket e `close` de socket de forma independente; - limpa o estado da sessão ao desconectar em vez de reproduzir trabalho antigo; - evita registrar chaves de API, áudio bruto do microfone, transcrições ou resultados de ferramentas, a menos que o produto tenha uma política explícita de retenção e privacidade. --- Source: https://docs.aivax.net/pt-br/docs/inference/pipelines.html # Pipelines de IA Os pipelines do AI Gateway são as etapas de processamento que o AIVAX aplica antes e durante a inferência. Eles podem adicionar contexto, reescrever consultas, expor ferramentas, moderar entrada, rotear modelos, truncar conversas e chamar trabalhadores externos. A maioria dos pipelines é configurada nos parâmetros do gateway. Opções ao nível da requisição podem sobrescrever alguns parâmetros de inferência em chamadas diretas de `chat/completions`. ## RAG RAG vincula [coleções](https://docs.aivax.net/pt-br/docs/rag/collections.md) a um AI Gateway. O gateway controla: - Coleções incluídas na recuperação. - Número máximo de documentos recuperados. - Pontuação mínima. - Nome do reranker. - Se referências de fragmentos são incluídas. - Estratégia de consulta. Quando um gateway tem coleções de conhecimento e a última mensagem do usuário contém texto, o AIVAX pode recuperar documentos correspondentes antes da chamada ao modelo. Para estratégias de injeção, o contexto recuperado é inserido no início da última mensagem do usuário. Se uma coleção vinculada tem seu próprio texto de contexto, esse contexto de coleção é adicionado às instruções do sistema. Estratégias de consulta: - `Plain`: Usa a última mensagem do usuário como consulta de pesquisa. - `Concatenate`: Junta o número configurado mais recente de mensagens do usuário linha a linha e pesquisa com o texto combinado. - `UserRewrite`: Reescreve mensagens recentes do usuário em uma ou mais consultas de pesquisa usando um modelo resolvedor. - `FullRewrite`: Reescreve mensagens recentes do usuário e do assistente em uma ou mais consultas de pesquisa usando um modelo resolvedor. - `QueryFunction`: Adiciona uma função de consulta ao modelo. O modelo decide quando pesquisar as coleções vinculadas, e os resultados da pesquisa são retornados como respostas de ferramenta. Estratégias de reescrita adicionam custo de modelo resolvedor (veja [Pricing](https://docs.aivax.net/pt-br/docs/pricing.md)) e latência. Elas são úteis quando os usuários fazem perguntas de acompanhamento, como "e sobre este caso?", pois o resolvedor pode transformar a conversa recente em uma consulta de pesquisa mais clara. Definir muitos resultados de RAG aumenta o uso de tokens de entrada e pode aumentar o custo final da inferência (veja [Pricing](https://docs.aivax.net/pt-br/docs/pricing.md)). Comece com uma contagem pequena de resultados e aumente apenas quando o modelo não tiver evidência suficiente. ## Instruções As configurações de instrução moldam o prompt voltado ao provedor: - **Instruções do sistema**: Adicionadas ao conjunto de instruções do sistema. - **Fontes remotas de instruções do sistema**: Obtidas de URLs configuradas e adicionadas ao conjunto de instruções do sistema. - **Modelo de prompt do usuário**: Substitui `{prompt}` pelo texto de cada mensagem do usuário antes de enviá‑la ao modelo. - **Pré‑preenchimento do assistente**: Adiciona conteúdo inicial do assistente antes da geração quando o modelo suporta pré‑preenchimento. Fontes remotas de instrução são obtidas como texto com tamanho máximo de resposta de 10 MB. Sua duração de cache é configurável; o padrão é 600 segundos. Alguns modelos não suportam pré‑preenchimento do assistente, temperatura, sequências de parada ou esforço de raciocínio. A validação integrada de modelo rejeita configurações de gateway incompatíveis quando essas limitações são conhecidas. ## Habilidades Habilidades são pacotes de instruções sob demanda disponíveis para o modelo. Quando um gateway habilita habilidades, o AIVAX carrega as habilidades da conta configuradas no gateway e pode expor funções internas relacionadas a habilidades. Leia mais sobre [habilidades](https://docs.aivax.net/pt-br/docs/features/skills.md). ## Pré‑processamento multimodal O pré‑processamento multimodal converte conteúdo de mídia selecionado em texto antes da chamada ao modelo principal. As bandeiras disponíveis são `Image`, `Audio`, `Video`, `File`, `OtherFiles` e `All`. Use pré‑processamento quando o modelo principal for texto‑primeiro ou quando quiser que o AIVAX normalize a mídia em contexto textual. Para modelos multimodais diretos, envie a mídia original sem pré‑processamento para que o modelo possa inspecioná‑la diretamente. As descrições de mídia são armazenadas em cache por hash de conteúdo para reutilização. ## Parametrização O pipeline de parametrização configura opções de requisição ao modelo, tais como: - `temperature` - `top_p` - `presence_penalty` - `frequency_penalty` - `stop` - `max_completion_tokens` - `reasoning_effort` - `verbosity` - `seed` Valores ao nível da requisição podem sobrescrever valores do gateway quando o endpoint suporta o parâmetro. Alguns modelos integrados rejeitam parâmetros específicos, e provedores BYOK podem ter suas próprias restrições. ## Truncamento de contexto O pipeline de truncamento de contexto usa uma contagem aproximada de tokens. Quando `ContextMaximumSize` está definido e a conversa excede o limite, o gateway segue `ContextOverflowAction`: - `Throw`: Retorna um erro em vez de chamar o modelo. - `Truncate`: Remove mensagens não‑sistêmicas mais antigas até que a conversa caiba. O truncamento preserva mensagens do sistema e mantém pelo menos uma mensagem do usuário quando possível. Se a mensagem do usuário restante ainda exceder o limite, a requisição falha com um erro de tamanho de mensagem. Em planos inferiores, o contexto de entrada efetivo pode ser limitado mesmo quando um contexto maior está configurado; veja [Plans and limits](https://docs.aivax.net/pt-br/docs/limits.md#plan-limits). ## Truncamento de mensagem de ferramenta `ToolContextCount` controla quantas mensagens recentes de resposta de ferramenta mantêm seu conteúdo original. Quando definido para um valor maior que zero, mensagens de ferramenta mais antigas permanecem na conversa, mas seu conteúdo é substituído por: ```text [tool response truncated - call this tool again] ``` Isso pode reduzir o uso de contexto em conversas longas de agentes. Também pode prejudicar cadeias onde um resultado antigo de ferramenta continua importante, portanto use apenas quando o modelo puder chamar a ferramenta novamente com segurança. ## Ferramentas do lado do servidor Ferramentas do lado do servidor são funções internas executadas pelo AIVAX durante a inferência. Elas podem vir de: - Ferramentas internas. - Funções de protocolo. - Fontes remotas de funções de protocolo. - Fontes MCP. - QueryFunction RAG. - Habilidades. - Ambiente bash opcional. Eventos de ferramenta do lado do servidor podem ser transmitidos aos clientes como atualizações `servertool`. ## Ferramentas internas Ferramentas internas podem ser configuradas em um gateway ou fornecidas por requisição com `builtin_tools`. As bandeiras de ferramenta interna disponíveis incluem: - `DateTime` — data e hora atuais através de `get_date_time`; configure `dateTimeTimeZone` nas opções da ferramenta interna (padrão: `America/Los_Angeles`, horário do Pacífico). - `WebSearch` - `AdvancedWebUsage` (desativado; retorna uma resposta indisponível. Veja [Changelogs](https://docs.aivax.net/pt-br/docs/changelogs.md).) - `OpenUrl` - `Code` - `Request` - `Calendar` - `Remember` - `GenerateWebPage` - `GenerateDocument` - `XPostsSearch` - `ImageGeneration` Veja [Built-in tools](https://docs.aivax.net/pt-br/docs/tools/builtin-tools.md). ## MCP e funções de protocolo Ferramentas listadas por uma fonte MCP ficam disponíveis ao modelo com seus esquemas declarados. Resultados de ferramenta MCP podem incluir texto, imagens e áudio; resultados de mídia são anexados à conversa como mensagens adicionais quando suportado. Funções de protocolo expõem callbacks HTTP ou URLs de callback do AIVAX como ferramentas chamáveis pelo modelo. Fontes remotas de funções de protocolo são obtidas e armazenadas em cache antes que suas ferramentas fiquem disponíveis ao modelo. Veja [Protocol functions](https://docs.aivax.net/pt-br/docs/tools/protocol-functions.md) e [MCP](https://docs.aivax.net/pt-br/docs/tools/mcp.md). ## Interpretador de funções Um manipulador de ferramenta pode adicionar comportamento de chamada de ferramenta para modelos que não produzem chamadas nativas de forma confiável. Valores suportados são: - `native` ou `null`: Usa chamada nativa de ferramenta do modelo. - `react.v1.selfcall`: Usa o manipulador de auto‑chamada estilo ReAct. Se um nome de manipulador não for reconhecido, a configuração do gateway falha no tempo de inferência. ## Moderação A moderação é um filtro de entrada que roda antes do modelo principal. Quando ao menos uma categoria de moderação está habilitada, o AIVAX envia a conversa textual disponível a um modelo de salvaguarda. O modelo de salvaguarda avalia a última solicitação do usuário no contexto estabelecido pela conversa e devolve uma pontuação de 0 a 10 para cada categoria. | Categoria | Propriedade do gateway | O que o salvaguarda avalia | | --- | --- | --- | | **Violência e discurso de ódio** | `violenceThreshold` | Violência, ódio, extremismo, ameaças ou incentivo a dano físico. | | **Conteúdo sexual e explícito** | `sexualExplicitThreshold` | Conteúdo sexualmente explícito ou adulto. | | **Temas políticos** | `politicalThreshold` | Persuasão política, campanha, manipulação ou conteúdo altamente político. | | **Conteúdo perigoso** | `dangerousContentThreshold` | Armas, explosivos, abuso cibernético, automutilação ou outros atos e instruções perigosas. | | **Tentativas de jailbreak** | `jailbreakThreshold` | Tentativas de sobrescrever instruções, revelar instruções protegidas, exfiltrar dados ou injetar prompts. | ### Entendendo níveis de sensibilidade O valor configurado no gateway é um **nível de sensibilidade**, não a pontuação da salvaguarda em si. Um nível mais alto reduz a pontuação necessária para bloquear a entrada. | Nível de sensibilidade | Pontuações de salvaguarda que bloqueiam | | ---: | --- | | `0` | Categoria desativada | | `1` | `10` | | `3` | `8`–`10` | | `5` | `6`–`10` | | `8` | `3`–`10` | | `10` | `1`–`10` | Para categorias habilitadas, o corte de bloqueio é `11 - nível de sensibilidade`. Uma pontuação de salvaguarda de `0` nunca bloqueia. Configure cada categoria independentemente; a requisição é bloqueada quando qualquer categoria habilitada atinge seu corte. ### Adicionar regras específicas do gateway **Regras de moderação adicionais** permitem que um administrador de gateway descreva políticas que não são totalmente expressas pelas descrições de categoria internas. A salvaguarda lê essas regras junto com a política interna e as usa para calibrar todas as cinco pontuações. Por exemplo: ```text Allow users to describe accidents and injuries when asking for insurance coverage or assistance. Treat requests for instructions to cause an accident or harm someone as dangerous content. ``` Regras adicionais orientam a classificação; elas não criam uma pontuação separada nem bloqueiam diretamente uma entrada. Pelo menos uma categoria deve ter um nível de sensibilidade acima de `0` para que a moderação seja executada. No exemplo acima, habilite **Conteúdo perigoso** para que a pontuação da salvaguarda possa gerar uma decisão de bloqueio. Escreva regras como declarações de política curtas com casos explicitamente permitidos e proibidos. Não inclua segredos, credenciais ou dados operacionais privados, pois as regras são armazenadas com a configuração do gateway e enviadas ao modelo de salvaguarda durante a moderação. O fragmento de gateway a seguir habilita diferentes níveis de sensibilidade e fornece orientações específicas ao domínio para a salvaguarda. Os valores são um exemplo, não uma baseline recomendada para produção: ```json { "moderationParameters": { "violenceThreshold": 4, "sexualExplicitThreshold": 4, "politicalThreshold": 2, "dangerousContentThreshold": 6, "jailbreakThreshold": 7, "additionalRules": "Permitir descrições de acidentes e lesões para suporte de seguro. Tratar instruções para causar acidentes ou machucar alguém como conteúdo perigoso." } } ``` ### O que acontece quando uma entrada é bloqueada Quando qualquer categoria habilitada atinge seu corte: 1. O AIVAX marca as mensagens originais da conversa como indisponíveis para a requisição de inferência principal. 2. O AIVAX as substitui por uma instrução identificando as categorias que causaram o bloqueio. 3. O modelo principal gera uma recusa em vez de responder à requisição original. A recusa é gerada pelo modelo; a moderação não devolve um corpo de resposta fixo. Se a salvaguarda não puder produzir um resultado de moderação válido, a requisição falha antes que a conclusão normal seja gerada. ### Contexto e limitações atuais A salvaguarda recebe o histórico de conversa disponível, não apenas a última mensagem. Papéis e textos das mensagens são preservados como dados de conversa serializados não confiáveis, de modo que instruções dentro da conversa não podem substituir a política da salvaguarda. Se a conversa exceder a janela de contexto da salvaguarda, o contexto mais antigo pode ser truncado. A moderação atualmente se aplica apenas ao texto de entrada: - Saída gerada não é moderada. - Imagens, áudio, vídeo e conteúdo de arquivos não são analisados. A salvaguarda recebe apenas um marcador indicando que mídia estava presente. - Autorização de ferramenta ou trabalhador ainda requer política ao nível da aplicação; a moderação não é um mecanismo de autorização. - A moderação adiciona uma inferência de salvaguarda antes da inferência principal, o que acrescenta latência e uso de moderação cobrável. Use a moderação para políticas de segurança amplas. Use trabalhadores quando a decisão depender de identidade externa, estado da conta ou política específica de negócio. ## Trabalhadores Configure eventos de trabalhador e detalhes de endpoint nos parâmetros do gateway; implemente o comportamento do evento em seu endpoint externo. Veja [AI Workers](https://docs.aivax.net/pt-br/docs/inference/workers.md). --- Source: https://docs.aivax.net/pt-br/docs/inference/structured-responses.html # Respostas Estruturadas AIVAX pode produzir JSON estruturado por dois caminhos: - `response_schema`: AIVAX valida a saída final do modelo contra um JSON Schema e tenta novamente com feedback de validação quando a saída é inválida. Este é o caminho de Reparação JSON. - `response_format`: AIVAX envia um formato de resposta nativo compatível com OpenAI ao provedor, ou aplica reparação quando `healing_options` está presente ou a Reparação JSON automática está habilitada na conta. Use respostas estruturadas quando outro sistema consumirá a saída e texto livre seria frágil. ## Como funciona a Reparação JSON Quando `response_schema` está presente, AIVAX adiciona instruções de esquema à requisição do modelo. Após o modelo gerar uma resposta, AIVAX tenta extrair JSON de: - O texto completo gerado. - Variantes reparadas comuns, como chaves de abertura ou fechamento ausentes. - Blocos de código JSON encontrados no texto gerado. Se o JSON extraído não validar contra o esquema, AIVAX adiciona uma mensagem de feedback com os erros de validação e pede ao modelo que gere o JSON novamente. Isso continua até que um valor JSON válido seja gerado ou o limite de tentativas configurado seja alcançado. A Reparação JSON melhora a confiabilidade, mas não é uma garantia absoluta. Se o modelo falhar repetidamente o esquema, a requisição pode falhar após o limite de tentativas. ## Escolhendo um modo Use `response_schema` quando AIVAX deve ser responsável pela validação e reparação. Este é o modo mais seguro para modelos que não suportam saída estruturada nativamente, para respostas que utilizam ferramentas antes de gerar JSON e para sistemas que não podem tolerar JSON malformado. Use `response_format` com `type: "json_schema"` quando o modelo do provedor deve lidar com a saída estruturada nativamente. AIVAX ainda usará o esquema internamente, e a reparação será aplicada quando `response_format.json_schema.healing_options` for fornecido ou a conta tiver a Reparação JSON automática habilitada. Use `json_only: true` quando o corpo da resposta HTTP deve conter apenas o JSON final. Isso remove o envelope normal de conclusão de chat, escolhas, uso e metadados de geração do corpo da resposta. ## Exemplo básico Referência: [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Inference%20(chat%20completions))
POST /v1/chat/completions
```json { "model": "@google/gemini-2.5-flash", "prompt": "Search for recent news about electric vehicles.", "stream": true, "builtin_tools": { "tools": [ "WebSearch" ], "options": { "web_search_mode": "full" } }, "response_schema": { "type": "object", "properties": { "news": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "News title" }, "summary": { "type": "string", "description": "News summary" } }, "required": ["title", "summary"] } } }, "required": ["news"] } } ``` `builtin_tools` é opcional. Se você habilitar ferramentas, o modelo selecionado deve suportar chamadas de ferramenta ou o gateway deve fornecer um manipulador de ferramenta. ## Saída estruturada nativa Use `response_format` quando quiser usar o suporte nativo a JSON Schema do provedor: ```json { "model": "@openai/gpt-4o", "messages": [ { "role": "user", "content": "List 3 European capitals." } ], "response_format": { "type": "json_schema", "json_schema": { "schema": { "type": "object", "properties": { "capitals": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" } }, "required": ["city", "country"] } } }, "required": ["capitals"] } } } } ``` Se o modelo integrado selecionado tem suporte estrito a JSON, AIVAX pode encaminhar o esquema usando o formato de resposta JSON Schema do provedor. ## Habilitando reparação em `response_format` Você pode habilitar explicitamente a Reparação JSON dentro de `response_format.json_schema`: ```json { "model": "@openai/gpt-4o", "messages": [ { "role": "user", "content": "Return a short status object." } ], "response_format": { "type": "json_schema", "json_schema": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": ["status", "message"] }, "healing_options": { "max_attempts": 5 } } } } ``` `max_attempts` deve estar entre 1 e 10. Cada nova tentativa é outra geração do modelo e pode aumentar custo e latência. Se a reparação frequentemente atinge o limite de tentativas, ajuste a instrução e o esquema antes de aumentar o limite. Causas comuns são esquemas excessivamente rígidos, campos `required` ausentes, prompts vagos, resultados de ferramentas ruidosos ou um modelo pequeno demais para a tarefa. ## Modo `json_only` Defina `json_only: true` quando o cliente deve receber apenas o JSON gerado: ```json { "model": "@openai/gpt-4o", "messages": [ { "role": "user", "content": "List 3 European capitals." } ], "response_schema": { "type": "object", "properties": { "capitals": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" } }, "required": ["city", "country"] } } }, "required": ["capitals"] }, "json_only": true } ``` Com `stream: false`, o corpo da resposta HTTP é o JSON final com `Content-Type: application/json`. Com `stream: true`, AIVAX envia o JSON completo como um único evento de dados SSE e depois envia `[DONE]`. ## Recursos de esquema suportados AIVAX valida o JSON gerado com JSON Schema. Os recursos suportados documentados são: - `string`: `minLength`, `maxLength`, `pattern`, `format` e `enum`. - `number` e `integer`: `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum` e `multipleOf`. - `array`: `items`, `uniqueItems`, `minItems` e `maxItems`. - `object`: `properties` e `required`. - `boolean` e `bool`. - `null`. - Tipos múltiplos, por exemplo `"type": ["string", "number"]`. Use `required` para campos que sua aplicação deve receber. Use `items` explícitos para arrays. Use `enum`, `format` e restrições de comprimento ou padrão quando os valores aceitos são conhecidos. ## Padrões práticos Para extração, indique ao modelo quais campos devem ser inferidos, quais campos devem ser `null` quando ausentes e quais campos não devem ser inventados. Para classificação, use `enum` para o r final e adicione um campo curto `reason` quando humanos precisarem auditar a decisão. Para JSON suportado por ferramentas, permita que o modelo use ferramentas antes de gerar o JSON e inclua campos de origem quando a aplicação precisar de procedência. Para gravações em banco de dados ou chamadas de API externas, valide o JSON novamente em sua aplicação. AIVAX valida a estrutura do JSON, mas sua aplicação continua responsável por regras de negócio como permissões, IDs válidos, intervalos de datas e restrições específicas da conta. --- Source: https://docs.aivax.net/pt-br/docs/inference/workers.html # Trabalhadores de IA Os trabalhadores do AI Gateway são hooks HTTP que permitem que um serviço externo controle a execução do gateway em tempo de execução. Um trabalhador pode permitir um evento, interrompê-lo, reescrever o contexto, adicionar instruções ou ferramentas, ou substituir o resultado de uma ferramenta do lado do servidor. Use trabalhadores quando uma regra deve ser decidida fora do prompt. Casos comuns incluem verificações de assinatura, enriquecimento de CRM, política específica de locatário, registro de auditoria, bloqueio dinâmico de ferramentas e substituir o resultado de uma ferramenta visível ao modelo por dados de um sistema interno. Os trabalhadores executam no caminho crítico da inferência. Cada evento de trabalhador adiciona uma requisição HTTP antes que o gateway possa continuar, portanto o endpoint deve responder rápida e previsivelmente. ## Formato da solicitação Quando um evento de trabalhador configurado dispara, o AIVAX envia uma requisição `POST` para a URL do trabalhador do gateway. ```json { "gatewayId": "your-gateway-id", "moment": "2025-12-29T17:04:39", "event": { "name": "message.received", "data": { "messages": [ { "role": "system", "content": "User local date is Monday, December 29, 2025 (timezone is America/Sao_Paulo)" }, { "role": "user", "content": "Good morning" } ], "origin": "ChatCompletionsApi", "externalUserId": "customer-123", "metadata": {} } } } ``` A forma exata de `event.data` depende do evento. Sempre valide `gatewayId` quando um endpoint serve mais de um gateway. ## Autenticação Quando a conta possui uma chave de hook, o AIVAX envia `X-Request-Nonce`. O nonce é um hash BCrypt derivado da chave de hook da conta. Valide este cabeçalho antes de confiar no corpo, especialmente quando o trabalhador libera dados privados, altera o contexto ou autoriza o uso de ferramentas. Trate `externalUserId`, `metadata`, mensagens e argumentos de ferramentas como entrada não confiável. ## Comportamento da resposta Após enviar a requisição, o AIVAX trata a resposta do trabalhador da seguinte forma: | Resposta | Comportamento | |---|---| | `Content-Type: application/json+worker-action` | Execute a ação descrita no corpo JSON. | | `2xx` sem `application/json+worker-action` | Continue normalmente. | | Resposta não OK sem `application/json+worker-action` | Interrompa o evento. | Se a requisição do trabalhador falhar com uma exceção de requisição HTTP, o AIVAX registra a falha e interrompe o evento. Escolha intencionalmente o comportamento fail-open ou fail-closed. Retorne `2xx` quando o enriquecimento for opcional. Retorne uma resposta não OK quando a autorização, conformidade ou política de negócio não puder falhar aberta. ## `message.received` O evento `message.received` dispara após o gateway preparar o contexto da mensagem recebida e antes da chamada ao modelo. ```json { "name": "message.received", "data": { "messages": [], "origin": "ChatCompletionsApi", "externalUserId": "customer-123", "metadata": {} } } ``` Para modificar o contexto, retorne `Content-Type: application/json+worker-action` com `type: "message.received.response"`: ```json { "type": "message.received.response", "data": { "rewrites": [ { "type": "add-system", "message": "Answer in formal English." } ] } } ``` Ações de reescrita disponíveis: | Ação | Descrição | Parâmetros | |---|---|---| | `clear` | Remove elementos do contexto. | `argument`: `messages`, `meta`, `system`, `tools`, `skills`, `all` ou omitido. | | `add-message` | Adiciona uma mensagem à conversa. | `message`: objeto de mensagem compatível com OpenAI. | | `remove-message` | Remove uma mensagem por índice. | `index`: índice da mensagem (baseado em zero). | | `add-system` | Adiciona uma instrução de sistema. | `message`: texto da instrução. | | `add-tool` | Adiciona uma definição de ferramenta compatível com OpenAI. | `tool`: objeto JSON da ferramenta. | | `add-protocol-tool` | Adiciona uma [função de protocolo](https://docs.aivax.net/pt-br/docs/tools/protocol-functions.md). | `tool`: definição da função de protocolo. | | `add-mcp-source` | Adiciona as ferramentas descobertas de uma fonte [MCP](https://docs.aivax.net/pt-br/docs/tools/mcp.md) ao contexto. | `source`: objeto de fonte MCP com `url`, `headers`, `name` e/ou `cacheDuration`. | ### Substituir o contexto do usuário ```json { "type": "message.received.response", "data": { "rewrites": [ { "type": "clear" }, { "type": "add-message", "message": { "role": "user", "content": "The original message was removed by an external policy check. Tell the user they need an active subscription to continue." } } ] } } ``` ### Remover uma mensagem ```json { "type": "message.received.response", "data": { "rewrites": [ { "type": "remove-message", "index": 0 } ] } } ``` ### Adicionar uma fonte MCP temporária ```json { "type": "message.received.response", "data": { "rewrites": [ { "type": "add-mcp-source", "source": { "name": "Internal CRM", "url": "https://crm.example.com/mcp", "headers": { "Authorization": "Bearer " }, "cacheDuration": 600 } } ] } } ``` Use `add-mcp-source` quando a lista de ferramentas precisar depender da mensagem, usuário, canal ou de uma política externa. O AIVAX lista as ferramentas do servidor MCP, converte cada esquema em uma função chamável pelo modelo e disponibiliza essas ferramentas apenas para aquela inferência. Para fontes permanentes, configure o MCP diretamente no AI Gateway. ## `tool.called` O evento `tool.called` dispara antes que o AIVAX execute uma ferramenta interna do lado do servidor. ```json { "name": "tool.called", "data": { "toolName": "check_order", "toolArguments": { "order_id": "A123" }, "origin": "ChatCompletionsApi", "externalUserId": "customer-123", "metadata": {} } } ``` Retorne uma resposta não OK para bloquear a chamada da ferramenta. Retorne `2xx` para permitir que o AIVAX execute a ferramenta normalmente. Para substituir o resultado da ferramenta, retorne `Content-Type: application/json+worker-action` com `type: "tool.called.response"`: ```json { "type": "tool.called.response", "data": { "result": "Order A123 is paid and scheduled for delivery tomorrow.", "messages": [] } } ``` Campos de `data`: | Campo | Descrição | |---|---| | `result` | Conteúdo textual injetado como resultado da ferramenta. | | `messages` | Mensagens adicionais opcionais no formato OpenAI anexadas ao contexto da conversa. | Quando `tool.called.response` é retornado, o AIVAX usa o resultado fornecido pelo trabalhador em vez de executar o manipulador padrão da ferramenta. ## Exemplo: bloqueando usuários não autorizados O exemplo abaixo mostra um Cloudflare Worker que bloqueia uma chamada ao gateway quando o usuário externo não tem permissão. ```js export default { async fetch(request, env) { if (request.method !== "POST") { return new Response("Method not allowed", { status: 405 }); } const body = await request.json(); if (body.gatewayId !== env.CHECKING_GATEWAY_ID) { return new Response(); } if (body.event?.name !== "message.received") { return new Response(); } const externalUserId = body.event.data.externalUserId; const allowedUsers = new Set((env.ALLOWED_USERS || "").split(",")); if (!allowedUsers.has(externalUserId)) { return new Response("User is not authorized", { status: 403 }); } return new Response(); } }; ``` ## Exemplo: substituindo uma ferramenta por um sistema interno Use `tool.called` quando o modelo deve ver um resultado de ferramenta, mas os dados reais devem vir do seu sistema. ```js export default { async fetch(request, env) { const body = await request.json(); if (body.event?.name !== "tool.called") { return new Response(); } const { toolName, toolArguments, externalUserId } = body.event.data; if (toolName !== "check_order") { return new Response(); } const orderId = toolArguments?.order_id; const orderResponse = await fetch(`${env.INTERNAL_API}/orders/${orderId}`, { headers: { "Authorization": `Bearer ${env.INTERNAL_API_TOKEN}` } }); if (!orderResponse.ok) { return new Response(JSON.stringify({ type: "tool.called.response", data: { result: `The order ${orderId} could not be retrieved for user ${externalUserId}. Ask the user to confirm the order number.` } }), { headers: { "Content-Type": "application/json+worker-action" } }); } const order = await orderResponse.json(); return new Response(JSON.stringify({ type: "tool.called.response", data: { result: `Order ${order.id}: status ${order.status}, estimated delivery ${order.eta}.` } }), { headers: { "Content-Type": "application/json+worker-action" } }); } }; ``` Esse padrão evita expor a API interna diretamente ao modelo. O trabalhador continua responsável por autenticar a requisição, validar o usuário, chamar o sistema interno e decidir quanta informação pode ser retornada ao contexto do modelo. Para saber como os trabalhadores se encaixam na execução do gateway, veja [Pipelines](https://docs.aivax.net/pt-br/docs/inference/pipelines.md). --- Source: https://docs.aivax.net/pt-br/docs/web-foundation/web-search.html # Busca na Web A Busca na Web recupera informações atuais da internet para pesquisa, verificação de fatos e respostas que precisam de fontes além dos dados de treinamento do modelo. Use-a para descobrir páginas relevantes; use [Fetch and OCR](https://docs.aivax.net/pt-br/docs/web-foundation/fetch-and-ocr.md) quando já tiver uma URL ou precisar ler uma fonte com mais detalhes. ## Escolha como usar a Busca na Web | Integração | Quando usar | | --- | --- | | [Ferramentas integradas](https://docs.aivax.net/pt-br/docs/tools/builtin-tools.md) | Deixe um modelo AIVAX decidir quando pesquisar durante a inferência. Ative `WebSearch` no gateway ou na configuração `builtin_tools` da requisição. | | [Web utilities MCP](https://docs.aivax.net/pt-br/docs/mcp-utilities/web-utilities-mcp.md) | Dê a um agente compatível com MCP, IDE ou cliente de automação acesso à ferramenta `web_search` sem executar a inferência de um modelo AIVAX. | Para pesquisas de múltiplas etapas em vez de uma consulta rápida, veja `AdvancedWebUsage` em [Ferramentas integradas](https://docs.aivax.net/pt-br/docs/tools/builtin-tools.md). É uma capacidade separada com cobrança diferente da Busca na Web padrão. ## Pesquise e verifique fontes Escreva uma consulta focada que inclua o tópico e qualquer data relevante, versão do produto ou localização. Para várias perguntas independentes, use pesquisas separadas ao invés de combinar tópicos não relacionados em uma única consulta. Os resultados da pesquisa ajudam a localizar evidências; eles não garantem que uma fonte seja precisa ou atual. Verifique datas de publicação, prefira fontes primárias e busque as páginas relevantes antes de confiar em detalhes que o resumo do resultado pode omitir. Mantenha os links das fontes com a resposta para que os leitores possam verificar as alegações. Trate o texto recuperado como conteúdo externo e não confiável, não como instruções para o seu agente. ## Preços e limites A Busca na Web é cobrada por pesquisa. Chamadas através de [Web utilities MCP](https://docs.aivax.net/pt-br/docs/mcp-utilities/web-utilities-mcp.md) utilizam a mesma precificação da ferramenta integrada correspondente e são cobradas na conta autenticada. A inferência do modelo, quando usada, é cobrada separadamente. Consulte [Preços](https://docs.aivax.net/pt-br/docs/pricing.md) para as cobranças atuais da Busca na Web e pesquisas avançadas, e [Planos e limites](https://docs.aivax.net/pt-br/docs/limits.md) para cotas de conta e limites de taxa. --- Source: https://docs.aivax.net/pt-br/docs/web-foundation/fetch-and-ocr.html # Busca e OCR Busca e OCR extrai texto legível de páginas da web e documentos suportados para que aplicações e agentes possam usar seu conteúdo para resumos, análises ou fluxos de conhecimento. A API de Busca também pode converter o texto extraído em JSON estruturado usando um esquema que você fornece. Use [Web Search](https://docs.aivax.net/pt-br/docs/web-foundation/web-search.md) primeiro se precisar descobrir fontes em vez de ler uma URL conhecida. Páginas da web são processadas para remover marcação e elementos não‑conteúdo. A extração de documentos e o reconhecimento óptico de caracteres (OCR) tornam o conteúdo não‑texto suportado disponível como texto. Revise o conteúdo extraído antes de confiá‑lo: qualidade da digitalização, layouts complexos e tabelas podem afetar o resultado. ## O que você pode extrair | Conteúdo | Formatos suportados | Conteúdo extraído | | --- | --- | --- | | Páginas da web | HTML, XHTML | Conteúdo legível da página, como artigos, documentação e informações de produto, com marcação e elementos não‑conteúdo removidos. JavaScript e CSS são renderizados antes da extração. | | Texto simples e Markdown | TXT, Markdown | Texto do documento, incluindo formatação Markdown existente. | | PDFs | PDF | Texto de documentos digitais e texto OCR de páginas digitalizadas. PDFs mistos podem combinar extração direta de texto com OCR quando necessário. | | Imagens contendo texto | PNG, JPEG, WebP, TIFF, BMP | Texto reconhecido de capturas de tela, documentos digitalizados, recibos e outras imagens com escrita legível. | | Documentos de processamento de texto | DOC, DOCX, ODT, RTF | Texto do documento convertido em uma representação textual legível. | | Apresentações | PPT, PPTX, ODP | Conteúdo textual dos slides. | | Planilhas e arquivos tabulares | XLSX, ODS, CSV | Conteúdo de células e linhas como texto, para leitura ou análise subsequente. | | E‑books | EPUB | Texto da publicação. | Por exemplo, você pode buscar um artigo online, ler um manual em PDF, extrair texto de uma imagem de recibo ou transformar uma planilha em texto para que um agente a analise. Forneça uma URL que retorne a página ou arquivo real, não uma página de compartilhamento que exija login. Ao enviar um URI de dados através da API, declare o tipo MIME correto do conteúdo. O resultado é texto extraído, não uma cópia pixel‑a‑pixel do documento original. Não presuma que layout, estrutura de tabelas, gráficos ou imagens incorporadas serão reproduzidos exatamente. A extração de planilhas não executa fórmulas ou macros. ## API de Busca vs. Descrições de Mídia Use a **API de Busca para extrair texto existente**. Use [Media Descriptions](https://docs.aivax.net/pt-br/docs/generations/media-descriptions.md) para **interpretar mídia com IA**, opcionalmente guiado pelo que sua aplicação precisa aprender a partir dela. | | API de Busca | Descrições de Mídia | | --- | --- | --- | | Propósito principal | Recuperar texto legível de páginas e documentos, usando OCR para imagens suportadas e PDFs digitalizados. | Gerar descrições ou extrair informações de imagens, PDFs, áudio e vídeo usando IA. | | Saída | Texto extraído, JSON opcional guiado por esquema gerado a partir desse texto, uso de unidades de processamento e erros por item. | Conteúdo gerado pelo modelo focado nas suas diretrizes, que pode descrever informações visuais ou audiovisuais além do texto presente na fonte. | | Imagens e PDFs | Ler texto, como as palavras em um recibo ou os parágrafos de um manual. | Descrever conteúdo visual ou interpretar um documento, como explicar um diagrama ou identificar informações relevantes para uma pergunta. | | Áudio e vídeo | Não é uma API de compreensão ou transcrição de áudio/vídeo. | Analisar conteúdo de áudio e vídeo. Para um fluxo dedicado de fala‑para‑texto, use [Audio Transcriptions](https://docs.aivax.net/pt-br/docs/generations/audio-transcriptions.md). | | Cobrança | Unidades de processamento de extração (PUs), com alocações e tarifas dependentes do plano. Conversão JSON opcional é cobrada separadamente e não está coberta pela alocação de extração. | Cobranças de uso de IA sob a precificação de Media Descriptions; as alocações de PU da Busca não substituem essas cobranças. | Para um relatório em PDF, escolha Busca quando precisar do texto para indexação ou análise posterior. Escolha Descrições de Mídia quando precisar de uma explicação de seus gráficos ou de uma interpretação guiada do conteúdo. Para uma imagem de recibo, Busca lê o texto impresso; Descrições de Mídia podem interpretar o recibo de acordo com suas diretrizes de extração. Nenhum garante resultados perfeitos. Busca pode perder texto ou estrutura por causa de OCR e limitações de layout. Descrições de Mídia podem omitir detalhes ou introduzir interpretações incorretas porque sua saída é gerada pelo modelo. Verifique detalhes consequentes contra a fonte original e compare os caminhos de cobrança na seção de preços abaixo. ## Escolha uma integração | Integração | Quando usar | | --- | --- | | API de Busca | Sua aplicação controla quais URLs ou URIs de dados base64 inline processar e precisa de resultados estruturados, uso de unidades de processamento e erros por item. | | [Web utilities MCP](https://docs.aivax.net/pt-br/docs/mcp-utilities/web-utilities-mcp.md) | Um cliente compatível com MCP precisa ler URLs públicas através de `fetch_url`. Esta ferramenta aceita de uma a cinco URLs por chamada. | | [Built-in tools](https://docs.aivax.net/pt-br/docs/tools/builtin-tools.md) | Um modelo AIVAX precisa ler uma URL durante a inferência. Ative `OpenUrl` e siga o guia de configuração de Contexto de URL. | As integrações têm contratos de entrada diferentes. Em particular, a ferramenta MCP aceita URLs públicas; use a API de Busca para URIs de dados base64 inline. ## Buscar conteúdo com a API Autentique‑se com uma chave de API AIVAX; veja [Authentication](https://docs.aivax.net/pt-br/docs/authentication.md). Forneça um array `contents` não vazio contendo URLs ou URIs de dados base64. Cada item tem limite de 10 MB. A operação `system.v1.web.fetch` aceita os seguintes campos de requisição JSON: | Campo | Tipo | Obrigatório | Comportamento | | --- | --- | --- | --- | | `contents` | Array de strings | Sim | Lista não vazia de URLs ou URIs de dados base64 para extrair. | | `returnErrors` | Boolean | Não | Padrão `true`: inclui um resultado para cada item que falhar. Quando `false`, itens falhos são omitidos. | | `responseSchema` | Objeto JSON Schema | Não | Converte o texto extraído de cada item em JSON guiado por esse esquema. Omitir ou usar `null` para extração somente de texto. O mesmo esquema se aplica a todos os itens do lote. | | `responseSchema.instructions` | String | Não | Diretrizes de extração opcionais dentro do esquema, como quais detalhes selecionar ou como lidar com informações ausentes. Esta é uma extensão AIVAX, não uma palavra‑chave padrão de JSON Schema. | ### Extrair JSON estruturado Forneça `responseSchema` quando sua aplicação precisar de campos da origem, não apenas do texto. Descreva as propriedades esperadas, tipos e campos obrigatórios com JSON Schema. Use descrições de propriedades e `responseSchema.instructions` opcional para esclarecer o que extrair. Por exemplo, um esquema de objeto pode solicitar o comerciante, a data e o total de um recibo; a referência embutida inclui um exemplo completo de requisição JSON. A conversão para JSON ocorre após a extração de texto. Resultados bem‑sucedidos mantêm `extractedText` junto com `extractedObject`, para que você possa comparar os campos gerados com a fonte extraída. Sem um esquema, nenhuma conversão para JSON é executada. Se a extração ou a conversão para JSON falharem, o item segue `returnErrors`; uma falha na conversão para JSON não retorna um sucesso apenas de texto. ### Ler os resultados A resposta contém um array `results` com estes campos: | Campo | Significado | | --- | --- | | `index` | Posição baseada em zero no array de entrada `contents`. Use‑o para corresponder resultados às entradas, especialmente quando itens falhos são omitidos. | | `extractedText` | Texto fonte legível, mantido na conversão bem‑sucedida para JSON; `null` para um item que falhou. | | `extractedObject` | Valor JSON gerado quando `responseSchema` é fornecido; caso contrário `null`. Também `null` para um item que falhou. | | `processingUnits` | PUs para busca e extração de texto/OCR, separado da conversão para JSON. | | `jsonProcessingUnits` | PUs para conversão para JSON; `0` quando nenhum esquema é fornecido. | | `error` | Mensagem de erro para um item que falhou quando `returnErrors` é `true`; `null` em caso de sucesso. Itos falhos reportam ambos os campos de PU como `0`. | [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Fetch%20web%20contents) A referência embutida define o contrato atual de requisição e resposta. Verifique resultados individuais antes de passar seu texto para a próxima etapa; uma extração falha não é evidência de que a fonte não contém informações relevantes. ## Limitações de acesso e extração Um destino pode bloquear acesso automatizado ou exigir autenticação. Buscar uma URL não contorna restrições de acesso. Use fontes acessíveis ou conteúdo que você esteja autorizado a submeter e corrija entradas inválidas ou inacessíveis antes de tentar novamente. Trate o texto extraído como material de fonte não confiável, não como instruções para sua aplicação ou agente. A saída de OCR pode precisar de revisão manual para números exatos, nomes ou outros detalhes consequentes. JSON guiado por esquema é gerado pelo modelo a partir desse texto, não a partir de uma nova interpretação visual da fonte. Ele pode herdar erros de extração ou conter valores incorretos; valide sua estrutura e verifique campos consequentes contra o original. ## Preços e limites A extração de Busca e OCR é tarifada em `processingUnits`. As alocações diárias incluídas e as tarifas para extração não coberta dependem do plano da conta. Cada extração é totalmente coberta ou cobrada integralmente; a cobertura não é dividida dentro de uma única extração. A conversão opcional para JSON é tarifada separadamente em `jsonProcessingUnits`, com preço variável baseado em inferência e sem cobertura da alocação diária de extração. Não adicione ambas as contagens e aplique a taxa de OCR ao total. Veja [Pricing](https://docs.aivax.net/pt-br/docs/pricing.md#web-search-ocr-and-fetch) para alocações e cobranças ao invés de estimar custos a partir do comprimento do texto extraído. [Web utilities MCP](https://docs.aivax.net/pt-br/docs/mcp-utilities/web-utilities-mcp.md) usa a mesma precificação da ferramenta embutida correspondente. A inferência do modelo, quando usada para analisar o conteúdo extraído, é cobrada separadamente. Veja [Plans and limits](https://docs.aivax.net/pt-br/docs/limits.md) para cotas de conta e limites de taxa. A API de Busca requer saldo positivo na conta. --- Source: https://docs.aivax.net/pt-br/docs/generations/speech.html # Geração de Fala Use a Geração de Fala quando sua aplicação já possui o texto final e precisa de áudio reproduzível sem executar uma conclusão de chat. Selecione um modelo de fala e voz disponíveis, então entregue o áudio gerado na forma mais adequada ao consumidor. Autentique solicitações com uma chave de API AIVAX. Consulte [Autenticação](https://docs.aivax.net/pt-br/docs/authentication.md) para orientações de autorização. ## Gerar fala Escreva um texto pronto para ser falado em voz alta, incluindo pontuação e formatação que comuniquem pausas ou ênfase. Teste a voz selecionada com conteúdo representativo antes de usá-la em produção, especialmente para nomes, abreviações ou termos especializados. A referência incorporada é a fonte de verdade para modelos e vozes disponíveis, opções de solicitação, formatos de saída e campos de resposta. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Generate%20speech) ## Preços, limites e erros Para preços, disponibilidade e limites de conta atuais, veja [Preços](https://docs.aivax.net/pt-br/docs/pricing.md) e [Planos e Limites](https://docs.aivax.net/pt-br/docs/limits.md). Revise os erros de validação relatados antes de tentar novamente uma solicitação falhada. --- Source: https://docs.aivax.net/pt-br/docs/generations/audio-transcriptions.html # Transcrições de Áudio Use as Transcrições de Áudio para converter fala gravada em texto para pesquisa, revisão, legendas ou automação subsequente. Envie o áudio em um formulário de solicitação suportado e use a transcrição retornada na próxima etapa do seu fluxo de trabalho. Autentique solicitações com uma chave de API AIVAX. Veja [Authentication](https://docs.aivax.net/pt-br/docs/authentication.md) para orientações de autorização. ## Escolha um modelo de transcrição Consulte os modelos de transcrição disponíveis para a conta autenticada antes de selecionar um. A disponibilidade pode variar de acordo com a configuração da conta, portanto não codifique rigidamente um catálogo em sua aplicação. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Get%20Audio%20Transcription%20Models) ## Transcrever áudio Forneça áudio que seja acessível ao AIVAX e preserve o contexto linguístico original quando for importante para seu caso de uso. Revise o texto retornado antes de usá-lo em ações visíveis ao usuário ou irreversíveis: gravações com ruído, múltiplos falantes, vocabulário especializado e baixa qualidade do microfone podem afetar a qualidade da transcrição. A referência incorporada é a fonte da verdade para os formulários de solicitação aceitos, opções e campos de resposta. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Transcribe%20audio) ## Preços, limites e erros Para disponibilidade atual, preços e limites de conta, consulte [Pricing](https://docs.aivax.net/pt-br/docs/pricing.md) e [Plans and Limits](https://docs.aivax.net/pt-br/docs/limits.md). Corrija áudio inválido ou inacessível antes de tentar novamente uma solicitação falhada. --- Source: https://docs.aivax.net/pt-br/docs/generations/media-descriptions.html # Descrições de Mídia Use Descrições de Mídia quando uma aplicação precisa de informações estruturadas de áudio, imagens, vídeo ou conteúdo PDF. É útil para preparar mídia para busca, revisão de moderação, fluxos de acessibilidade e automação downstream. Escolha a API mais especializada quando a tarefa for limitada a um único meio, como [Transcrições de Áudio](https://docs.aivax.net/pt-br/docs/generations/audio-transcriptions.md) para fala para texto. ## Descrever mídia Forneça mídia que o AIVAX possa acessar e use orientações que foquem a extração nas informações que seu fluxo de trabalho necessita. Cada item enviado é tratado de forma independente, portanto preserve a ordem de entrada ao correlacionar os resultados com a mídia original. Para mídias remotas, certifique-se de que o recurso permaneça acessível durante todo o processamento e não exija login interativo. Evite enviar credenciais, dados pessoais ou outro conteúdo que não deve aparecer em uma descrição gerada. A referência incorporada é a fonte de verdade para os formatos de mídia aceitos, opções de solicitação e campos de resposta. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Describe%20media) ## Preços, limites e erros Para preços atuais, disponibilidade de mídia e limites de conta, veja [Pricing](https://docs.aivax.net/pt-br/docs/pricing.md) e [Plans and Limits](https://docs.aivax.net/pt-br/docs/limits.md). Corrija mídia inacessível ou conteúdo inválido antes de tentar novamente. --- Source: https://docs.aivax.net/pt-br/docs/generations/teach-skill.html # Ensinar Habilidade Use o recurso Ensinar Habilidade para transformar demonstrações gravadas em instruções de habilidade reutilizáveis, passo a passo. Os usos típicos incluem capturar o fluxo de tela de um especialista para que agentes de suporte o repitam consistentemente, converter tutoriais de integração em comportamento de assistente e iniciar um rascunho de habilidade que um humano depois aperfeiçoa. Envie vídeos tutoriais como partes de conteúdo `video_url` — URLs hospedados ou URIs de dados base64. Como a análise leva um tempo em gravações mais longas, a API recomenda `direct.inference.aivax.net`. ## Grave uma demonstração que ensine bem A qualidade do rascunho segue a qualidade da gravação. Antes de enviar: - Mostre o fluxo de trabalho na ordem em que deve ser compreendido, um passo de cada vez, sem pular entre telas. - Narre ou legendue a intenção por trás de cada ação ("Eu abro este painel porque..."), não apenas o clique em si — gravações silenciosas deixam o contexto necessário implícito e forçam o modelo a adivinhar. - Mantenha credenciais, dados pessoais e informações do cliente fora do quadro; tudo que for visível pode acabar nas instruções resultantes. - Prefira algumas gravações curtas e focadas em vez de uma sessão longa quando o procedimento tem fases naturais. ## Crie um rascunho de habilidade Organize as gravações na ordem em que o procedimento deve ser compreendido. A resposta usa o envelope JSON padrão. `data.resultText` contém um rascunho Markdown estruturado que pode incluir front matter, etapas, notas e suposições quando a gravação deixa o contexto necessário implícito. `data.usage.processedUnits` relata as unidades de uso processadas para a solicitação. Um rascunho gerado não é publicado automaticamente como uma habilidade de conta. Valide cada etapa contra o fluxo de trabalho real, remova detalhes específicos da gravação (tamanhos de janela, nomes de teste, valores pontuais), confirme pré-requisitos e reescreva etapas vagas como instruções imperativas antes de salvá-lo. Consulte [Habilidades](https://docs.aivax.net/pt-br/docs/features/skills.md) para a estrutura da habilidade e orientações de ativação. A referência incorporada é a fonte de verdade para a entrada de vídeo aceita e o comportamento da resposta. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Teach%20skill) ## Preços, limites e erros Para disponibilidade atual e limites de conta, veja [Preços](https://docs.aivax.net/pt-br/docs/pricing.md) e [Planos e Limites](https://docs.aivax.net/pt-br/docs/limits.md). Corrija conteúdo de vídeo inválido ou inacessível antes de tentar novamente uma solicitação falhada. --- Source: https://docs.aivax.net/pt-br/docs/generations/images.html # Geração de Imagens Use a Geração de Imagens para criar imagens a partir de um prompt de texto em um fluxo de trabalho de aplicativo. Usos típicos incluem esboços de ilustrações para revisão editorial, maquetes de produtos, variações de marketing para testes A/B e arte de espaço reservado que um designer refina posteriormente. Autentique solicitações com uma chave de API AIVAX. Consulte [Autenticação](https://docs.aivax.net/pt-br/docs/authentication.md) para orientações de autorização. ## Escolha um modelo Selecione um modelo de geração de imagens disponível na conta autenticada. A disponibilidade e as capacidades do modelo podem mudar, portanto obtenha as opções atuais da plataforma em vez de depender de uma lista fixa neste guia. Quando vários modelos estão disponíveis, decida por capacidade: se você precisa de suporte a imagens de referência (apenas alguns modelos aceitam `referenceImages`), quantas variações por prompt você precisa (`count` aceita de 1 a 4) e quanto tempo seu aplicativo pode esperar — solicitações de imagem em alguns modelos demoram, caso em que a API recomenda `direct.inference.aivax.net`. ## Gere uma imagem Use prompts que declarem o resultado que você precisa, ao invés de confiar em rótulos visuais vagos. Inclua os detalhes importantes, como o assunto, ambiente, enquadramento e qualquer texto que deve estar presente. Uma solicitação pode conter um único prompt ou um array de prompts, e cada prompt gera `count` imagens cujas URLs são retornadas agrupadas pelo prompt de entrada. Forneça até quatro imagens de referência HTTP(S) quando o modelo selecionado as suportar e a saída deve seguir um assunto, estilo ou composição existente. As referências orientam o resultado; elas não garantem preservação de identidade, portanto inspecione a saída antes de publicar. Trate os ativos gerados como rascunhos e revise-os quanto à precisão, adequação à marca e conteúdo não intencional antes do lançamento. Quando o primeiro resultado estiver próximo, mas não correto, itere apertando um elemento de cada vez — detalhe do assunto, composição, restrição de estilo — ao invés de reescrever todo o prompt de uma vez. A referência incorporada é a fonte da verdade para a forma da solicitação, opções suportadas e campos de resposta. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Generate%20images) ## Preços, limites e erros Para preços atuais, disponibilidade e limites de conta, veja [Preços](https://docs.aivax.net/pt-br/docs/pricing.md) e [Planos e Limites](https://docs.aivax.net/pt-br/docs/limits.md). Se uma solicitação falhar, revise o problema de validação relatado antes de tentar novamente. --- Source: https://docs.aivax.net/pt-br/docs/generations/decisions.html # Decisões semânticas Decisões semânticas avaliam perguntas nomeadas contra um estado compartilhado e retornam respostas estruturadas ao invés de uma explicação gerada. Use-as para encaminhar solicitações de suporte, selecionar uma categoria, verificar uma condição ou atribuir uma pontuação ordenada. Uma solicitação fornece o modelo, as evidências em `state` e um objeto `questions`. Cada pergunta tem um ID que você escolhe; a resposta usa o mesmo ID em `answers`. Você pode fazer tipos de perguntas diferentes em uma única solicitação sem precisar de chamadas de API separadas. Use [structured responses](https://docs.aivax.net/pt-br/docs/inference/structured-responses.md) quando precisar de um objeto gerado maior ou de uma explicação escrita. Para similaridade baseada em embeddings entre documentos e rótulos, veja [Text classification](https://docs.aivax.net/pt-br/docs/rag/classification.md). ## Escolha um modelo Todos os modelos abaixo suportam `choice`, `noul` e `score`. Os preços são valores base em USD por milhão de tokens de entrada; ajustes de conta e plano ainda se aplicam. Tokens de saída não têm custo no catálogo atual de modelos de decisão. | Modelo | Preço de entrada / milhão de tokens | Contexto | | --- | ---: | --- | | `@supersonic-labs/julia-1` | $0.008 | 1.024 tokens por pergunta | | `@typesafe/jev-1.13` | $0.042 | 32.768 tokens | | `@respan/span-01` | $0.020 | Não especificado no catálogo atual | | `@respan/span-01-lite` | $0.000 | Não especificado no catálogo atual | | `@jaredpalmer/kev-4b` | $0.042 | 8.192 tokens | `@typesafe/jev` também é aceito e atualmente resolve para `@typesafe/jev-1.13`. Um limite de contexto não especificado não significa entrada ilimitada. Limites específicos do modelo e interpretação de pontuações podem diferir; valide um modelo com exemplos representativos antes de mudar o tráfego de produção. Uma chave de API autenticada e um saldo positivo são necessários, inclusive ao selecionar um modelo com preço base de token zero. Veja [Authentication](https://docs.aivax.net/pt-br/docs/authentication.md), [Pricing](https://docs.aivax.net/pt-br/docs/pricing.md) e [Plans and limits](https://docs.aivax.net/pt-br/docs/limits.md). ### Descobrir modelos programaticamente `GET /api/v1/information/decisions-models.json` lista o catálogo atual de modelos de decisão sem autenticação. O array `data` da resposta contém: - `name`: o identificador canônico a ser usado em uma solicitação de decisão. - `aliases`: outros identificadores aceitos para esse modelo. - `contextLength`: o contexto anunciado em tokens, ou `null` quando não especificado. - `releaseDate`: a data de lançamento do catálogo no formato `yyyy-MM-dd`. - `capabilities`: tipos de pergunta suportados (`noul`, `choice` e/ou `score`). - `inputPricePerMillionTokens` e `outputPricePerMillionTokens`: preços base em USD, antes de ajustes de conta e plano. Use esta lista para preencher seletores de modelo ao invés de manter um catálogo codificado separadamente. Ela descreve modelos configurados, não um verificador de saúde do provedor em tempo real. Limites específicos de opção e pergunta não estão incluídos nesta lista. ## Escreva as perguntas | Tipo | Formato de `criteria` | Use para | | --- | --- | --- | | `choice` | Objeto que mapeia IDs de escolha para descrições | Selecionar um destino ou categoria | | `noul` | Objeto com descrições não vazias de `false` e `true` | Avaliar uma condição booleana | | `score` | Array ordenado de descrições de nível | Avaliar uma condição graduada | Cada pergunta requer `instructions` não vazias. Use descrições que distingam as opções, não apenas IDs opacos. Por exemplo, `"billing": "Charges, payments, and refunds"` fornece mais evidência que `"billing": "B"`. Para `noul`, ambos os critérios são necessários. Descreva o que conta como falso com o mesmo cuidado que o que conta como verdadeiro, especialmente quando o estado pode omitir a informação relevante. Para `score`, mantenha a ordem dos níveis consistente entre solicitações. ## Avaliar uma solicitação de suporte Envie o seguinte corpo JSON para `POST /api/v1/generations/decisions`. O exemplo usa Julia-1; seu estado pode ser texto, um objeto ou um array. ```json { "model": "@supersonic-labs/julia-1", "state": { "message": "Fui cobrado duas vezes. Por favor, devolva o pagamento extra." }, "questions": { "department": { "type": "choice", "instructions": "Qual equipe deve lidar com esta solicitação?", "criteria": { "billing": "Cobranças, pagamentos e reembolsos", "technical": "Erros de software e interrupções de serviço", "sales": "Planos, preços e compras" } }, "refund_requested": { "type": "noul", "instructions": "O cliente pede explicitamente a devolução do dinheiro?", "criteria": { "false": "O cliente não pede que o dinheiro seja devolvido", "true": "O cliente pede um reembolso ou devolução de um pagamento" } }, "urgency": { "type": "score", "instructions": "Quão urgente é a solicitação com base no prazo declarado?", "criteria": [ "Nenhum prazo declarado", "Um prazo foi declarado, mas não é hoje", "O cliente precisa explicitamente de resolução hoje" ] } } } ``` Mantenha apenas evidências relevantes no estado. As instruções devem explicar a decisão, não solicitar uma cadeia de raciocínio ou texto adicional. Evite descrições de escolha sobrepostas a menos que a ambiguidade seja intencional. ### Ler a resposta A resposta de sucesso é um objeto JSON direto, **sem um envelope `data`**. Ele contém: - `id`: o identificador da decisão. - `model`: o identificador canônico do modelo usado na solicitação. - `provider`: o provedor relatado para o resultado. - `answers`: um objeto indexado pelos seus IDs de pergunta. - `usage`: `input_tokens`, `output_tokens` e o `cost` faturado. Para Julia-1, um objeto `answers` ilustrativo para o exemplo acima é mostrado abaixo. Esses números explicam o formato; eles não são uma resposta registrada nem uma garantia de qualidade. ```json { "department": { "type": "choice", "choice": "billing", "probabilities": { "billing": 0.90, "technical": 0.06, "sales": 0.04 } }, "refund_requested": { "type": "noul", "noul": 0.95, "probabilities": { "false": 0.05, "true": 0.95 } }, "urgency": { "type": "score", "score": 0.3, "legend": { "0": "Nenhum prazo declarado", "1": "Um prazo foi declarado, mas não é hoje", "2": "O cliente precisa explicitamente de resolução hoje" }, "probabilities": { "0": 0.8, "1": 0.1, "2": 0.1 } } } ``` Com Julia-1: - `choice` é o ID definido pelo chamador selecionado, não a descrição da opção. - `noul` é a probabilidade atribuída ao critério verdadeiro, não um Booleano JSON. Seu aplicativo escolhe o limiar e como lidar com casos incertos. - `score` é o **índice de nível baseado em zero** esperado. No exemplo, `0 × 0.8 + 1 × 0.1 + 2 × 0.1 = 0.3`. Não é necessariamente um inteiro e não é uma pontuação normalizada de 0–1 quando há mais de dois níveis. - `probabilities` são indexadas por IDs de escolha, `false`/`true` ou índices de nível de pontuação. `legend` descreve os níveis de pontuação. Outros modelos podem omitir campos opcionais como `probabilities`, `legend` ou `confidence`. Não presuma que todo provedor usa a mesma escala de pontuação ou definição de confiança. Uma alta probabilidade não prova que a decisão está correta; valide limites e regras de escalonamento com exemplos rotulados do seu próprio domínio. ## Limites de taxa da conta Solicitações de decisão semântica compartilham um limite de taxa a nível de conta entre modelos e chaves de API. Cada solicitação conta uma vez, mesmo contendo várias perguntas. Essa cota é separada da alocação diária de assinatura e se aplica tanto ao uso incluído quanto ao pago. Veja [Plans and Limits](https://docs.aivax.net/pt-br/docs/limits.md#plan-limits) para os limites Free, Pro e Max. Solicitações acima do limite retornam `429 Too Many Requests` antes da avaliação. Distribua as chamadas ao longo da conta e faça novas tentativas com backoff após a janela de limite de taxa limpar; mudar chaves de API dentro da mesma conta não fornece uma cota separada. ## Limites do Julia-1 | Limite | Valor | | --- | --- | | Perguntas por solicitação | 1–32 | | Escolhas ou níveis de pontuação por pergunta | 2–20 | | Opções booleanas | Exatamente duas: false e true | | Contexto combinado por pergunta | 1.024 tokens, incluindo estado, pergunta, opções e tokens especiais | | Orçamento de pergunta e opções | 256 tokens dentro do contexto combinado | | Descrição de uma opção individual | No máximo 48 tokens | | Limite de payload de decisão | 256 KiB | Os limites interagem: vinte opções podem exceder o orçamento combinado de pergunta/opção mesmo que cada descrição seja individualmente curta o suficiente. Encurte as descrições ou reduza a contagem de opções ao invés de assumir que o máximo pode ser usado de uma vez. Entradas que excedem o contexto ou o orçamento de pergunta/opção são rejeitadas, não truncadas silenciosamente. O literal `` é reservado e não pode aparecer no estado, nas instruções ou nas descrições de opções. Estes são os limites atuais de serviço AIVAX Julia-1; figuras de contexto maiores em um cartão de modelo upstream não os substituem. ## Uso e custo Para Julia-1, o uso de entrada soma a sequência codificada para cada pergunta, excluindo preenchimento. O estado compartilhado, portanto, é contado novamente para cada pergunta. Quatro perguntas sobre um estado não têm o mesmo uso de entrada que uma única pergunta sobre esse estado. Julia-1 não gera texto, então seu valor `output_tokens` é zero. Julia-1 está atualmente elegível para a alocação diária de decisões semânticas nos planos Free, Pro e Max. Outros modelos de decisão são cobrados normalmente. A alocação é compartilhada entre chamadas de decisão elegíveis, não reservada por pergunta ou chave de API. Veja [Plans and Limits](https://docs.aivax.net/pt-br/docs/limits.md#included-daily-subscription-allowances) para capacidade relativa do plano e regras de cobertura. Quando não coberto, a entrada do Julia-1 é cobrada ao preço base de $0.008 por milhão de tokens antes de ajustes de conta e plano. Use o `usage.cost` retornado para o valor efetivamente faturado; ele é zero quando a entrada está totalmente coberta pela alocação. ## Erros e uso confiável - **Modelo ou pergunta inválidos:** verifique o identificador exato do modelo, tipo de pergunta, instruções e formato dos critérios. IDs de pergunta e de escolha devem ser não vazios. - **Limite de contexto ou opção excedido:** encurte o estado ou as descrições, reduza a contagem de opções ou selecione um modelo com limites adequados. Repetir a mesma entrada inválida não a resolverá. - **Erro de autenticação ou saldo:** verifique a chave de API e o saldo da conta antes de tentar novamente. Um modelo com preço zero ainda requer saldo positivo. - **Limite de taxa (429):** reduza a taxa de solicitações da conta e tente novamente com backoff. Múltiplas perguntas em uma solicitação ainda contam como uma solicitação, mas limites de payload específicos do modelo e uso por pergunta permanecem aplicáveis. - **Capacidade temporária ou indisponibilidade do provedor:** evite uma tempestade de tentativas paralelas imediatas. Reduza a simultaneidade e use tentativas limitadas com backoff para falhas transitórias. Avalie `choice`, `noul` e `score` separadamente ao validar um modelo: sucesso no roteamento não estabelece pontuação confiável ou comportamento booleano. Inclua estados ambíguos e incompletos no seu conjunto de testes e use revisão humana onde uma decisão errada tem consequências materiais. Uma nova tentativa é uma nova solicitação; não presuma deduplicação automática ou saídas idênticas do modelo. ## Referência de API [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Evaluate%20semantic%20decisions) --- Source: https://docs.aivax.net/pt-br/docs/features/skills.html # Habilidades Habilidades (também conhecidas como competências) podem ser usadas para melhorar como seu agente executa tarefas específicas. Habilidades são instruções especiais que são recuperadas sob demanda, e seu agente carrega essas habilidades conforme necessário. Idealmente, seu agente deve usar uma habilidade apenas quando ela for relevante para a tarefa que está executando. Ela é incorporada à conversa por meio de uma ferramenta especial, e as instruções da habilidade são adicionadas ao contexto, indicando que o agente tem contexto fornecido no contexto que pode ser usado na conversa. ## Como as habilidades funcionam? Habilidades são fornecidas principalmente por meio de um slug e uma breve descrição do que a habilidade é e quando deve ser usada. Você pode ter várias habilidades em sua conta, mas usar apenas um subconjunto delas em seu [AI Gateway](https://docs.aivax.net/pt-br/docs/inference/ai-gateway.md). As habilidades habilitadas no AI Gateway são listadas nas instruções do sistema do modelo e a função `read_skill` é adicionada ao contexto. Quando o modelo chama `read_skill`, ele passa um array de slugs de habilidades. As instruções das habilidades correspondentes são inseridas nas instruções do sistema da próxima rodada de contexto dentro de blocos ``. Mais de uma habilidade pode ser ativada quando uma tarefa abrange múltiplos domínios, e o modelo pode chamar `read_skill` novamente com uma lista diferente quando a tarefa ativa mudar. Para que isso funcione, o modelo base escolhido deve suportar **chamadas de função** e **instruções do sistema**. - Se o seu modelo não suportar chamadas de função, considere usar um [manipulador de ferramentas](https://docs.aivax.net/pt-br/docs/inference/pipelines.md) para lidar com chamadas de função. - Se o seu modelo não suportar instruções do sistema, considere usar a flag `No system instructions`, que fornece instruções do sistema como uma mensagem de usuário. Modelos maiores tendem a seguir as instruções e chamadas de função de forma muito rígida. Execute testes para ver se seu modelo está alterando suas habilidades conforme necessário. ## Estrutura e operação Uma habilidade tem `slug`, `description`, `instructions` e `options`. O `slug` é o identificador técnico usado pela conta e deve ter 64 caracteres ou menos, usando letras, números, sublinhados, pontos ou hífens. A `description` é o texto que ajuda o modelo a decidir quando essa habilidade deve ser carregada; ela precisa explicar o cenário de uso em vez de repetir o nome. As `instructions` são o conteúdo completo que será inserido quando a habilidade for ativada. No caminho de tempo de execução atual, `instructionSources` é armazenado e exportado com a configuração da habilidade, mas apenas o campo `instructions` inline é injetado quando o modelo ativa uma habilidade. Escreva a descrição como uma regra de roteamento. Uma descrição como “habilidade legal” é fraca porque não indica quando usar. Uma descrição melhor seria “use quando o usuário solicitar análise, revisão ou explicação de cláusulas contratuais em linguagem simples”. As instruções, por outro lado, devem ser operacionais: explicar como responder, quais perguntas fazer quando dados estão ausentes, quais ferramentas podem ser úteis, quais limites devem ser respeitados e o formato final esperado. O modelo lê a descrição para escolher a habilidade e lê as instruções para executar a tarefa. `allowedToolsNames` faz parte da configuração da habilidade e tem a intenção de associar nomes de ferramentas em tempo de execução a uma habilidade, como `web_search`, `open_url`, `generate_image` ou `generate_web_page`. No caminho de tempo de execução atual, a lista geral de ferramentas sempre visível é a forma confiável de manter as ferramentas compartilhadas visíveis quando o gateway oculta ferramentas sem uma habilidade. Habilidades também podem ser importadas e exportadas em JSONL. Esse formato é útil para versionar habilidades, migrar configurações entre contas, manter um conjunto de habilidades em um repositório ou revisar mudanças antes de publicar. Cada linha deve representar uma habilidade com pelo menos `slug` e `instructions`; `description` e `options` podem complementar a configuração. Ao importar uma habilidade com um `slug` existente, o AIVAX atualiza a habilidade correspondente em vez de criar um duplicado. ## Como escrever habilidades? Escrever habilidades eficazes requer clareza e especificidade nas instruções. Aqui estão as principais diretrizes: ### Estrutura da habilidade Uma habilidade bem escrita deve conter: 1. **Slug claro e descritivo**: Use um slug curto que identifique imediatamente o propósito da habilidade, como `python_code_analysis`, `customer_support` ou `technical_translation`. 2. **Descrição concisa**: Forneça uma descrição breve (1–2 frases) que explique quando a habilidade deve ser ativada. Essa descrição é crucial porque o modelo a usa para decidir se carrega a habilidade. 3. **Instruções detalhadas**: As instruções reais devem incluir: - Objetivos claros da tarefa - Formato de resposta esperado - Regras específicas a seguir - Exemplos quando apropriado - Restrições ou limitações importantes ### Melhores práticas - **Seja específico**: Evite instruções vagas. Em vez de “ser útil”, diga “forneça explicações passo a passo com exemplos de código.” - **Use linguagem imperativa**: Comece as frases com verbos de ação (analisar, explicar, comparar, listar). - **Mantenha o escopo limitado**: Cada habilidade deve se concentrar em uma área de conhecimento específica ou tipo de tarefa. - **Teste iterativamente**: Refine suas habilidades com base em como o modelo responde na prática. - **Evite redundância**: Não repita informações já presentes nas instruções base do sistema. ### Exemplo de habilidade - Nome: Análise de Desempenho de Código - Descrição: Use quando o usuário solicitar análise de desempenho, otimização ou identificação de gargalos em código. ```markdown - Analise o código fornecido identificando possíveis gargalos de desempenho - Considere a complexidade temporal (Big O) e o uso de memória - Sugira otimizações específicas com exemplos de código - Explique o impacto de cada otimização proposta - Priorize legibilidade e manutenção junto com desempenho ``` ## Quando usar habilidades? Habilidades são mais úteis em cenários específicos onde você precisa de comportamento especializado: ### Cenários ideais **1. Expertise específica de domínio** - Terminologia técnica específica de um setor - Conformidade com regulamentos ou padrões - Metodologias específicas (Scrum, ITIL, SOC 2, etc.) **2. Mudança de tom ou estilo** - Serviço formal vs. casual - Comunicação técnica vs. simplificada - Personas ou papéis diferentes **3. Processos complexos e estruturados** - Fluxos de trabalho multi‑etapa - Análises que seguem frameworks específicos - Geração de documentos com formatos rígidos **4. Tarefas que requerem contexto extenso** - Quando as instruções são muito longas para incluir a cada vez - Conhecimento que é apenas ocasionalmente relevante - Vários conjuntos de regras mutuamente exclusivos ### Quando NÃO usar habilidades - **Instruções permanentes**: Se as instruções devem estar sempre ativas, coloque-as nas instruções base do sistema. - **Tarefas simples**: Para respostas diretas que não requerem contexto especial. - **Conhecimento geral**: Informações que o modelo já conhece bem não precisam ser reforçadas via habilidades. - **Poucas ou muitas habilidades**: Mire em 3–10 habilidades. Menos que isso, considere usar instruções base. Mais que isso pode confundir o modelo. ### Comparação: Habilidades vs. Instruções do Sistema | Aspecto | Habilidades | Instruções do Sistema | |--------|--------|----------------------| | Quando aplicar | Sob demanda, quando relevante | Sempre ativo | | Tamanho ideal | Pode ser extenso | Deve ser conciso | | Troca de contexto | Sim, pode alternar | Não, fixo | | Uso de tokens | Econômo (somente quando necessário) | Constante | | Melhor para | Conhecimento especializado | Comportamento base do agente | ### Dicas de implementação - **Comece pequeno**: Implemente 2–3 habilidades inicialmente e expanda conforme necessário. - **Monitore o uso**: Verifique se o modelo está ativando habilidades corretamente. - **Evite sobreposição**: Habilidades com descrições semelhantes podem confundir o modelo. - **Teste transições**: Garanta que o modelo troque de habilidades quando apropriado. ## Comparando Habilidades, RAG e Prompt de Sistema Para entender melhor quando e como usar habilidades em comparação com outras técnicas como **RAG (Geração Aumentada por Recuperação)** e **Prompt de Sistema (Instruções do Sistema)**, use as orientações nesta página juntamente com a documentação de [collections](https://docs.aivax.net/pt-br/docs/rag/collections.md) e [pipelines](https://docs.aivax.net/pt-br/docs/inference/pipelines.md). Veja também: - [Guia de Engenharia de Prompt](https://www.promptingguide.ai/) - [Construindo Aplicações RAG Prontas para Produção](https://www.anthropic.com/index/building-effective-agents) - [Documentação do AI Gateway](https://docs.aivax.net/pt-br/docs/inference/ai-gateway.md) --- Source: https://docs.aivax.net/pt-br/docs/features/chat-clients.html # Clientes de Chat Um cliente de chat fornece uma interface de usuário através de um [AI Gateway](https://docs.aivax.net/pt-br/docs/inference/ai-gateway.md) que permite ao usuário conversar com seu assistente. Um cliente de chat é integrado à inferência do AI gateway e suporta pensamento profundo, busca, conversa em texto e envio de imagens. Os recursos de áudio dependem da integração e da configuração do cliente. Você pode personalizar a interface do cliente de chat com CSS, JavaScript personalizado, cores, rótulos, botões de sugestão, origens de quadros, modos de entrada e o idioma usado pelos recursos de chat. ## Como funciona o cliente de chat Um cliente de chat é uma camada de sessão sobre um AI Gateway. O gateway define o comportamento do assistente; o cliente de chat define como um usuário final conversa com ele, como a sessão é identificada, quanto tempo dura, quais limites são aplicados, quais recursos visuais aparecem e como as mensagens entram e saem por canais externos. Essa separação é importante: você pode usar o mesmo gateway em uma API interna, um widget web, Telegram e WhatsApp, mas cada canal terá suas próprias regras para identidade, anexos, formatação, comandos e entrega de mensagens. Cada sessão mantém um histórico de mensagens, contexto adicional, metadados, token de conversa e um identificador externo opcional. Quando você cria uma sessão com um `tag`, a AIVAX tenta reutilizar a sessão ativa para essa tag em vez de criar uma nova conversa. Isso permite que o usuário retorne ao widget ou envie outra mensagem pelo mesmo canal sem perder o contexto imediatamente. Quando a sessão não tem `tag`, ela funciona como uma conversa independente controlada pelo token de acesso gerado na criação. O `tag` também serve como ponto de conexão entre o cliente de chat, memória, calendário, workers e integrações. Ferramentas como memória precisam de um identificador estável para saber a quem uma preferência ou informação persistente pertence. Workers recebem `externalUserId` para aplicar regras por usuário, por canal ou por conta externa. Integrações do WhatsApp e Telegram usam o ID da conversa, número de telefone ou usuário para recuperar a sessão correta. Portanto, escolha um `tag` estável, não sensível e único por usuário ou conversa. ## Criando uma sessão de chat Uma sessão de chat é onde você cria uma conversa entre seu cliente de chat e o usuário. Você pode chamar este endpoint fornecendo contexto adicional para a conversa, como nome, localização, etc., do usuário. Uma sessão pode ser identificada com um tag estável e não sensível para que o cliente possa continuar a conversa adequada. Consulte a Referência de API incorporada para o comportamento e configuração de sessão suportados. Referência: [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Create%20Web%20Chat%20Session) Ao criar uma sessão, use `extraContext` para informações que ajudam o assistente nessa conversa, mas não devem se tornar memória permanente: nome exibido, plano do cliente, idioma preferido, página de referência, produto que o usuário está visualizando, número do pedido ou estado atual do fluxo. Não use este campo para segredos, tokens internos ou dados que o modelo não deve ver. O contexto adicional vai para a inferência e pode influenciar respostas, ferramentas e workers. Você também pode fornecer `contextLocation`, uma URL que a AIVAX carrega durante a geração da resposta e anexa ao contexto da sessão. Use-a para contexto controlado pelo servidor que pode mudar ao longo do tempo e certifique-se de que a URL seja acessível pela AIVAX. O chat web aceita mensagens de texto e anexos. Imagens, arquivos, vídeos e áudio são materializados antes da inferência; tipos suportados de imagem, arquivo, vídeo e áudio podem ser encaminhados como conteúdo multimodal quando o modelo selecionado e a configuração do gateway o suportam. O áudio também pode ser sintetizado como resposta quando a configuração de síntese de áudio do cliente de chat está ativa. Quando um canal não pode incorporar um anexo, a AIVAX transforma o conteúdo não suportado em um aviso de anexo textual para que o assistente possa responder claramente. ## Enviando prompts da sua aplicação Use **Send Prompt** quando sua aplicação precisa de uma resposta síncrona usando uma sessão de cliente de chat existente. A chave de acesso da sessão autoriza a requisição; mantenha-a privada. A requisição usa o histórico da sessão e a configuração do AI Gateway associado. Para inferência de longa duração, envie `POST /api/v1/public/chat-clients//prompt` para `https://direct.inference.aivax.net` para contornar o caminho do Cloudflare Tunnel. Configure o timeout do seu cliente HTTP para a duração esperada da geração. O domínio direto expõe rotas selecionadas, não toda a API do cliente de chat. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Send%20Prompt) ### Escolha o formato de entrada O `prompt` obrigatório aceita texto simples, um objeto de mensagem compatível com OpenAI ou um array ordenado de objetos de mensagem. Texto simples se torna uma mensagem de usuário. Use objetos de mensagem para conteúdo multimodal ou resultados de ferramentas, e um array quando várias mensagens devem ser fornecidas juntas. Pelo menos uma mensagem deve conter conteúdo ou chamadas de ferramenta. A resposta contém `completionText`, `reasoning` quando disponível, `toolCalls` para sua aplicação executar, `usage` e `createdMessages`. O último campo contém apenas as mensagens geradas durante esta requisição, em ordem de geração — não as mensagens enviadas ou o histórico de sessão anterior. Suas mensagens usam o formato compatível com OpenAI e podem incluir chamadas de ferramenta, resultados de ferramenta, raciocínio e metadados por mensagem. `completionText` é o texto da última mensagem do assistente em `createdMessages`, não uma concatenação da rodada: após uma chamada de ferramenta, ele contém apenas a resposta final. Ele recorre ao texto acumulado da inferência quando a última mensagem do assistente está ausente ou vazia, portanto uma rodada apenas com chamada de ferramenta pode retornar um `completionText` vazio — verifique `toolCalls` para decidir se continua. ### Decida se salva a rodada `commit` tem padrão `true`: mensagens enviadas e geradas são salvas na sessão. Use `commit: false` para uma inferência pontual contra o histórico atual sem salvar aquela rodada. Você ainda recebe a conclusão e `createdMessages`. Isso não é uma execução de teste: a inferência ainda é cobrada e as ferramentas ainda podem atuar. Mensagens não comitadas permanecem fora do histórico de sessões posteriores — para continuar esse ramo, reenvie-as em um array `prompt` ordenado. ### Adicione contexto para uma inferência Use `instructions` para contexto que deve ser aplicado apenas à requisição atual, como um formato de resposta temporário ou o item atualmente selecionado na sua aplicação. Aceita uma string ou um array de strings; as entradas do array são unidas por linhas em branco. Esse contexto é anexado após o `extraContext` da sessão e qualquer contexto carregado de `contextLocation`. Ao contrário do `extraContext` da sessão, `instructions` não é salvo como contexto de sessão, mesmo quando `commit` é `true`. Ele ainda é enviado ao modelo e pode influenciar respostas e ferramentas; não inclua segredos ou dados que o modelo não deve ver. ### Concluir chamadas de ferramenta do lado do cliente 1. Configure a ferramenta desejada do lado do cliente no AI Gateway e envie um prompt. 2. Quando `toolCalls` não estiver vazio, execute a função solicitada na sua aplicação. Cada entrada expõe `id`, `functionName`, `contents` (argumentos codificados em JSON) e `isProtocolFunction`. Valide os argumentos e aplique as permissões da sua aplicação antes da execução. 3. Envie um novo prompt com uma mensagem `role: "tool"`. Defina `tool_call_id` como o `id` da chamada retornada, `name` como seu `functionName` e `content` como o resultado da ferramenta em texto. Para múltiplas chamadas, envie um array de mensagens de resultado correspondentes. 4. Leia a próxima conclusão ou repita se solicitar mais ferramentas. Com o padrão `commit: true`, a mensagem de chamada de ferramenta do assistente já está na sessão: envie apenas os resultados da ferramenta, sem duplicar aquela mensagem do assistente. Se a requisição anterior usou `commit: false`, inclua as mensagens de conversa não salvas — incluindo a mensagem do assistente contendo `tool_calls` — antes dos resultados. As entradas de `toolCalls` de nível superior não são objetos de mensagem; use as mensagens compatíveis com OpenAI em `createdMessages` ao reconstruir essa troca. Para ferramentas do lado do servidor, a AIVAX executa as ferramentas e continua a geração dentro da mesma requisição. `createdMessages` pode, portanto, conter uma chamada de ferramenta do assistente, seu resultado e a resposta final do assistente, enquanto `toolCalls` de nível superior está vazio. Não execute essas chamadas do lado do servidor novamente. A referência de API acima inclui exemplos para conclusões simples, chamadas do lado do cliente, resultados enviados do lado do cliente e múltiplas mensagens de chamadas do lado do servidor. ## Sessões de integração AIVAX oferece integrações para clientes de chat via Telegram e WhatsApp, incluindo [Z-Api](https://www.z-api.io/), Evolution API e Kapso. Cada conversa em um aplicativo é uma sessão individual, identificada pelo ID da conversa, ID do chat ou número de telefone do usuário, dependendo do provedor. Sessões de integração têm duração padrão de três horas, a menos que os parâmetros da integração especifiquem outro valor. Essas sessões obedecem às regras originais do cliente de chat. Além disso, sessões de chat nessas integrações têm dois comandos especiais: - `/reset`: limpa o contexto da sessão atual. - `/usage`: quando `debug` está ativo no cliente de chat, exibe o uso atual do chat em tokens. Integrações tratam o canal como a origem das mensagens, mas a inferência continua a ser realizada pelo AI Gateway associado ao cliente de chat. No Telegram, a conversa recebe instruções adicionais sobre formatação e comportamento esperado do canal. No WhatsApp, cada provedor tem seus próprios detalhes de webhook, download de mídia e envio de resposta; Z-Api, Evolution API e Kapso são caminhos diferentes para o mesmo objetivo operacional. Em todos os casos, as mensagens do usuário entram na sessão, são materializadas como mensagens compatíveis com inferência, e a resposta do assistente é enviada de volta via mensageiro da integração. Use o Telegram quando precisar de um bot simples com usuários identificáveis por chat e comandos fáceis de testar. Use o WhatsApp quando o canal principal de suporte do usuário já for o telefone e a conversa precisar acontecer em um aplicativo diário. Use o widget web quando quiser incorporar o assistente em um site, produto, centro de suporte ou painel. A escolha do canal não deve mudar o conteúdo essencial do gateway, mas pode exigir ajustes no tom, tamanho da resposta, formatação e tolerância a anexos. Antes de abrir um canal ao público, revise a configuração do cliente de chat e explique o comportamento da memória aos usuários quando aplicável. Quando uma integração não responde como esperado, primeiro verifique o gateway associado e a configuração da integração, então tente novamente com uma mensagem simples antes de investigar recursos opcionais. Para os próximos passos, revise a [configuração do AI Gateway](https://docs.aivax.net/pt-br/docs/inference/ai-gateway.md) e a [Autenticação](https://docs.aivax.net/pt-br/docs/authentication.md), especialmente a fronteira entre acesso público ao chat e credenciais de API. --- Source: https://docs.aivax.net/pt-br/docs/features/batch.html # Batch Batch é o recurso da AIVAX para executar o mesmo fluxo de trabalho de IA em muitos itens independentes. Ele transforma uma lista de entradas em uma fila processada em segundo plano com instruções fixas, saída estruturada, validação opcional, acompanhamento de progresso, tentativas de nova execução e exportação de resultados. Use o Batch quando você tem dezenas, centenas ou milhares de registros que precisam passar pelo mesmo raciocínio: classificar leads, extrair campos de texto, enriquecer registros, resumir documentos curtos, avaliar respostas, moderar conteúdo, gerar dados estruturados ou invocar ferramentas internas para cada linha de uma lista. ## O que o Batch resolve Processar muitos itens com IA normalmente requer uma fila, tratamento de erros, novasativas, validação JSON e exportação de resultados. O Batch consolida essas partes na AIVAX. Na prática, ele resolve principalmente: - **Processamento repetível:** a mesma instrução, modelo e esquema são aplicados a todos os itens. - **Execução assíncrona:** o trabalho continua em segundo plano, sem manter a solicitação aberta. - **Saída estruturada:** cada item pode ser exigido a retornar um objeto compatível com um JSON Schema. - **Correção e validação:** a AIVAX tenta reprocessar respostas inválidas e pode executar uma segunda etapa de validação. - **Operação em escala:** os jobs podem ser iniciados, pausados, retomados, monitorados, filtrados, limpos, reenviados para tentativa e exportados. - **Controle operacional:** a UI mostra progresso, falhas, confiança e eventos do job. ## Quando usar Use o Batch quando os itens puderem ser processados independentemente e não precisarem compartilhar memória. Bons exemplos são uma linha por cliente, URL, produto, ticket, mensagem, documento curto, trecho de contrato ou registro bruto. O Batch é uma boa escolha quando: - o mesmo prompt se aplica a todos os itens; - você precisa de resultados tabulares ou JSON para consumo posterior; - o tempo de resposta pode ser assíncrono; - você quer rastrear erros e tentar novamente apenas os itens problemáticos; - você quer usar ferramentas internas, como busca web, para cada item; - você precisa medir confiança e taxa de sucesso por execução. Não **use** o Batch para conversas em tempo real, fluxos onde um item depende da resposta do item anterior, indexação de documentos para RAG ou tarefas puramente determinísticas que não requerem um modelo de IA. Para indexar conhecimento pesquisável, use [RAG collections](https://docs.aivax.net/pt-br/docs/rag/collections.md). Para uma única resposta imediata a um usuário, use [inference](https://docs.aivax.net/pt-br/docs/inference/inference.md). ## Conceitos ### Workflow O workflow é a receita de processamento. Ele define como os itens futuros serão tratados: - título; - instruções de processamento; - modelo; - esquema de resultado esperado; - ferramentas internas habilitadas; - instruções de validação; e - comportamento de tentativa e tratamento de erros. Alterar um workflow afeta jobs subsequentes e itens processados com essa configuração. Use workflows separados quando a instrução, esquema, modelo ou regras de validação mudarem de forma significativa. ### Job Um job é uma execução concreta criada a partir de um workflow. Ele agrupa os itens de uma carga de trabalho, mantém estado, eventos e métricas. Um job representa a carga de trabalho enquanto está sendo preparado, processado, pausado ou concluído. Consulte a Referência de API embutida para os estados de job suportados. ### Item Um item é uma linha da lista importada. Cada linha se torna uma entrada independente enviada ao modelo com as instruções do workflow. Cada item registra seu resultado de processamento, saída, confiança e detalhes de validação. Consulte a Referência de API embutida para os estados de item suportados. ## Como usar no console No console da AIVAX, vá para **Batch**. ### Criar um workflow Em **Workflows**, crie um workflow e configure: 1. **Básico:** defina um título, a instrução de processamento e o JSON Schema do resultado. 2. **Comportamento:** escolha as capacidades de assistente suportadas para o workflow. 3. **Validação:** habilite a validação quando a resposta precisar ser verificada contra regras de negócio. 4. **Manipulação:** configure o comportamento de tratamento de erros do workflow. Escreva a instrução como uma regra geral, não como uma única pergunta. O item importado será a variável de entrada. Exemplo de instrução: ```text Classify the company provided in the input. Return the likely sector, a short justification, and signals found in the text. If the input does not contain enough information, use sector "Undefined". ``` Exemplo de esquema: ```json { "type": "object", "properties": { "sector": { "type": "string" }, "reason": { "type": "string" }, "signals": { "type": "array", "items": { "type": "string" } } }, "required": ["sector", "reason", "signals"], "additionalProperties": false } ``` ### Criar e executar um job Depois de criar o workflow, crie um job para a carga que deseja processar. Novos jobs são criados no estado `Paused` para que você possa importar e inspecionar a carga antes de iniciar o processamento. Você pode importar itens em quatro modos: - `lines`: lê um arquivo de texto enviado e importa cada linha não vazia como um item. - `files`: importa cada arquivo de texto simples enviado como um item. - `zip`: importa cada entrada de texto simples em um arquivo ZIP enviado como um item. - `text`: importa o campo de texto enviado como um único item. Linhas podem ser texto simples, CSV delimitado, URLs, IDs, JSON compacto ou qualquer formato que a instrução saiba interpretar. Para entradas estruturadas baseadas em linhas, prefira JSONL: um objeto JSON por linha. Exemplo: ```jsonl {"name":"Company A","description":"B2B auto-parts marketplace"} {"name":"Company B","description":"Office specializing in employment contracts"} {"name":"Company C","description":"Regional pharmacy chain"} ``` Com os itens importados, inicie o job. A tela do job permite monitorar: - progresso geral; - itens pendentes, concluídos e falhados; - confiança média; - eventos do job; - itens processados mais recentes; - lista completa de itens com filtros por estado e confiança. ### Operar em itens falhados Use os filtros de lista para encontrar itens com erro de execução, erro de validação, recusa ou baixa confiança. Então você pode: - tentar novamente todos os erros; - tentar novamente apenas erros de execução; - tentar novamente apenas erros de validação; - tentar novamente itens concluídos com baixa confiança; - remover itens pendentes, concluídos, com erro ou todos os itens não em execução; - abrir um item individual para revisar entrada, saída, estado e confiança. ### Exportar resultados Quando o job terminar, exporte os resultados em JSONL. Cada linha exportada contém metadados, a entrada original e a saída. Use essa exportação para importar para uma planilha, banco de dados, pipeline de dados ou etapa de revisão manual. ## Como usar via API Use a API quando quiser integrar o Batch ao seu sistema interno, pipeline de dados ou automação. A autenticação segue o mesmo padrão da API da AIVAX. O fluxo da API é o mesmo do fluxo do console, apenas expresso como operações separadas. Primeiro crie o workflow, que é a receita reutilizável. Depois crie um job, importe os itens e inicie o job quando a carga estiver pronta. Após o início do processamento, use os endpoints de listagem, tentativa, limpeza e exportação para operar o job sem perder o rastreamento dos registros individuais. Se ainda estiver decidindo se o Batch é o recurso certo, compare-o com [RAG collections](https://docs.aivax.net/pt-br/docs/rag/collections.md) e [direct inference](https://docs.aivax.net/pt-br/docs/inference/inference.md). O Batch é para raciocínio repetido sobre itens independentes. As coleções RAG são para conhecimento pesquisável que deve ser recuperado posteriormente. A inferência direta é para uma resposta imediata. ### Criar workflow Crie um workflow quando quiser salvar a regra de processamento que jobs jobs futuros reutilizarão. É aqui que você define a instrução, modelo, esquema de saída, comportamento de validação, tentativas e ferramentas habilitadas. Um bom workflow lê como uma política para cada item, não como um prompt de uso único para um único registro. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Create%20Batch%20Workflow) ### Criar job Crie um job quando tiver uma carga de trabalho concreta para executar através de um workflow existente. Jobs são criados pausados para que você possa importar e inspecionar os itens antes do processamento. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Create%20Batch%20Job) Jobs são criados pausados. Importe os itens antes de iniciar. ### Importar itens Importe itens após o job existir. Cada item importado se torna uma unidade de trabalho independente, então escolha o modo que melhor corresponde aos seus dados de origem: uma linha por registro, um arquivo por registro, uma entrada ZIP por registro ou um texto enviado como um único registro. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Import%20Batch%20Job%20Items) Escolha o formato de importação que corresponde aos dados de origem. Consulte a Referência de API embutida para os modos de importação suportados, campos e restrições atuais. ### Iniciar, pausar ou concluir Inicie o job apenas depois que a lista de itens parecer correta. Pausá‑lo para investigar erros ou ajustar o workflow, e conclua‑lo quando o job deve ser encerrado em vez de retomado. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Edit%20Batch%20Job) Consulte a Referência de API embutida para os estados de job suportados. ### Monitorar O monitoramento é como você decide se o workflow está saudável. A visualização do job mostra o estado geral; a lista de itens indica onde o trabalho está travando, quais itens falharam na validação e quais resultados de baixa confiança merecem revisão humana. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=View%20Batch%20Job) Para listar itens: [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=List%20Batch%20Job%20Items) Use o endpoint de listagem para filtrar itens por estado, confiança ou texto de entrada. Consulte a Referência de API embutida para os filtros suportados. ### Tentativa e limpeza Tentativas são melhor usadas depois que você entende o padrão de falha. Tente novamente erros de execução quando o provedor ou a solicitação falhar, erros de validação quando a resposta puder ser regenerada para o formato esperado, e resultados de baixa confiança quando o item teve sucesso mas merece outra tentativa de modelo. Endpoints de limpeza servem para remover itens não em execução de um job quando eles não são mais úteis. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Retry%20Batch%20Job%20Items) Use o endpoint de tentativa após revisar o padrão de falha. Consulte a Referência de API embutida para as opções de tentativa suportadas e o comportamento resultante do job. Para remover itens não em execução: [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Remove%20Batch%20Job%20Items) Use o endpoint de remoção apenas para itens que não são mais úteis. Consulte a Referência de API embutida para as opções de remoção suportadas. ### Exportar Exportar é o ponto de entrega da AIVAX de volta ao seu próprio workflow. Use após o job terminar, ou exporte apenas um subconjunto quando um processo de revisão precisar primeiro dos itens concluídos e depois dos erros. O formato JSONL é conveniente para planilhas, bancos de dados, filas e ferramentas de auditoria manual porque cada linha permanece vinculada à entrada original e à sua saída gerada. [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Export%20Batch%20Job) Use o endpoint de exportação para selecionar os resultados concluídos que sua revisão ou processo subsequente necessita. Consulte a Referência de API embutida para os filtros de exportação suportados. ## Disponibilidade Revise [Pricing](https://docs.aivax.net/pt-br/docs/pricing.md) e [Plans and Limits](https://docs.aivax.net/pt-br/docs/limits.md) antes de processar uma carga de trabalho grande. ## Melhores práticas - Teste o workflow com alguns itens antes de importar uma lista grande. - Use esquemas restritivos com `required` e `additionalProperties: false` quando a saída for consumida por um sistema. - Inclua exemplos de entrada e saída na instrução quando o formato for ambíguo. - Prefira uma linha por item; se precisar enviar objetos complexos, use JSONL. - Mantenha a validação habilitada para tarefas sensíveis como extração jurídica, financeira ou dados que alimentam automações. - Use `maxRetries` para corrigir falhas ocasionais, mas investigue erros recorrentes no prompt ou esquema. - Defina um `errorStopThreshold` baixo em novos workflows para evitar gastar em um lote com configuração errada. - Tente novamente itens de baixa confiança separadamente; baixa confiança não significa erro, mas indica que a resposta merece revisão. - Exporte resultados por estado quando for necessária revisão manual, por exemplo, primeiro `finished`, depois `errors`. --- Source: https://docs.aivax.net/pt-br/docs/tools/builtin-tools.html # Ferramentas Integradas AIVAX fornece uma lista de ferramentas integradas para você habilitar em seu modelo. Essas ferramentas podem ser usadas juntamente com as [funções do lado do servidor](https://docs.aivax.net/pt-br/docs/tools/protocol-functions.md). Algumas funções têm custos de uso. Consulte [Preços](https://docs.aivax.net/pt-br/docs/pricing.md) antes de habilitá‑las em um fluxo de trabalho de produção. Observe que cada modelo decide qual função chamar e seus parâmetros. Nem todos os modelos podem obedecer às regras de chamada. ## Como Escolher e Combinar Ferramentas Ferramentas integradas devem ser habilitadas como capacidades de trabalho, não como decoração de agente. Cada ferramenta adiciona uma decisão ao modelo: ele precisa perceber que a ferramenta existe, entender quando usá‑la, montar argumentos válidos, aguardar o resultado e continuar a resposta. Quanto mais ferramentas semelhantes estiverem disponíveis ao mesmo tempo, maior a chance de uso redundante ou escolha inadequada. Comece com o menor conjunto que resolva o caso de uso e escreva instruções claras sobre quando usar cada uma. Use `WebSearch` quando a resposta depende de informações públicas, recentes ou variáveis. Use `OpenUrl` quando o usuário já forneceu uma URL e deseja que o assistente analise aquele conteúdo específico. Use `AdvancedWebUsage` quando a tarefa requer uma pesquisa mais profunda em múltiplas fontes ao invés de uma única busca. Use `Code` para cálculo, transformação de dados e raciocínio algorítmico pequeno. Use `Request` quando o modelo precisa chamar uma API HTTP com método, cabeçalhos ou corpo personalizado. Use `Remember` e `Calendar` apenas em clientes de chat ou chamadas com um usuário identificável, pois essas ferramentas dependem de contexto persistente por usuário. Ferramentas de geração, como imagem, documento e página web, devem ser tratadas como ações de saída. Elas fazem mais do que melhorar uma resposta; criam artefatos hospedados ou anexados à conversa. Portanto, instrua o modelo sobre quando gerar um artefato e quando responder em texto. No suporte, por exemplo, gerar um documento pode ser útil para uma cotação, proposta ou resumo formal; gerar uma página web pode ser útil para um relatório visual; gerar uma imagem pode ser útil para ideação criativa. Se o usuário apenas pediu uma explicação, texto simples geralmente é suficiente. Quando as ferramentas estão disponíveis via `builtin_tools` em uma chamada direta, a aplicação que faz a solicitação decide a lista para cada inferência. Quando configurado no AI Gateway, a lista é centralizada e pode ser combinada com habilidades, workers, MCP, funções de protocolo e shell. Em produção, prefira o gateway para políticas permanentes, pois impede que diferentes clientes habilitem ferramentas diferentes sem controle. Use chamadas diretas para testes, rotinas internas e fluxos onde a aplicação realmente precisa escolher ferramentas dinamicamente. Os valores em `builtin_tools.tools` são bandeiras de configuração como `WebSearch`, `Code` e `OpenUrl`. O modelo vê nomes de funções em tempo de execução como `web_search`, `evaluate_code` e `open_url`. Use nomes de funções em tempo de execução ao configurar listas de permissão de ferramentas de habilidade ou de shell. ## Busca na Internet Esta função habilita a busca na internet no seu modelo. Com isso, o modelo pode consultar informações específicas ou em tempo real, como dados meteorológicos, notícias, resultados de jogos, etc. A busca na internet é realizada por múltiplos provedores, escolhidos com base na disponibilidade de rede e latência. AIVAX usa uma combinação de provedores para realizar buscas na internet. AIVAX oferece dois tipos de buscas configuráveis via seu painel: - **Full**: a busca realizada é completa, inserindo o conteúdo inteiro de cada resultado no contexto da conversa. - **Summarized**: a busca realizada é resumida, inserindo no contexto da conversa um resumo gerado por IA pelo próprio provedor de busca. O modo `Full` pode consumir mais tokens de entrada da conversa, mas pode fornecer resultados mais precisos. Consulte [Preços](https://docs.aivax.net/pt-br/docs/pricing.md) e [Planos e limites](https://docs.aivax.net/pt-br/docs/limits.md) antes de habilitar a busca na internet em produção. > [!NOTE] > > **Importante:** a busca `Full` nem sempre está disponível. Activation via `builtin_tools`: ```json { "tools": [ "WebSearch" ], "options": { "web_search_max_results": 10, "web_search_mode": "full" } } ``` ## Diagnóstico de Ferramentas Quando uma ferramenta não é chamada, primeiro confirme que ela está habilitada no gateway ou no campo `builtin_tools` da solicitação. Em seguida, verifique se o modelo selecionado suporta chamadas de função ou se um manipulador de ferramenta está configurado para modelos sem suporte nativo. Depois, revise a instrução: se não especificar quando buscar, abrir uma URL, gerar uma imagem ou consultar a memória, o modelo pode responder apenas com seu próprio conhecimento. Finalmente, teste uma pergunta direta que claramente exija a ferramenta, como solicitar um artigo de notícias recente para `WebSearch` ou pedir para abrir uma URL específica para `OpenUrl`. Quando uma ferramenta é chamada com muita frequência, reduza a ambiguidade. Ferramentas como `WebSearch`, `AdvancedWebUsage` e `XPostsSearch` competem por informações recentes; `OpenUrl` e `Request` podem parecer semelhantes quando o usuário envia um link; `Remember` e `Calendar` podem se sobrepor quando o usuário fala sobre preferências e datas. Remova ferramentas desnecessárias, torne as descrições de instruções do gateway mais restritivas e, quando possível, use workers para bloquear ou substituir chamadas em cenários específicos. Quando uma ferramenta falha, trate-a como parte normal da experiência. As buscas podem retornar pouco conteúdo, URLs podem bloquear bots, APIs podem negar autorização, a geração de imagens pode recusar conteúdo e a execução de código pode receber entrada ambígua. Instrua o modelo a explicar a limitação de forma objetiva e oferecer o próximo passo, como solicitar outro link, tentar uma consulta mais específica, pedir autorização ou responder apenas com base no contexto disponível. Não dependa de uma ferramenta externa como a única forma de concluir uma conversa crítica sem um fallback de experiência. ## Busca Avançada na Internet Esta função executa uma solicitação de pesquisa web mais profunda através do agente de pesquisa da AIVAX. Destina‑se a perguntas complexas que necessitam de síntese entre múltiplas fontes ou de uma passagem de pesquisa mais detalhada do que `WebSearch`. O nome da função em tempo de execução é `advanced_web_search`, e ela aceita um único argumento `prompt`. Evite habilitá‑la para tarefas rotineiras de consulta; use `WebSearch` para fatos atuais rápidos e `OpenUrl` para URLs fornecidas pelo usuário. Esta função pode gerar custos de uso. Consulte [Preços](https://docs.aivax.net/pt-br/docs/pricing.md) antes de habilitá‑la em produção. Activation via `builtin_tools`: ```json { "tools": [ "AdvancedWebUsage" ], "options": { } } ``` ## Execução de Código Esta função permite que o modelo execute código JavaScript e inspecione o resultado da execução. Com isso, o modelo pode avaliar resultados algorítmicos de expressões matemáticas e outras situações que são melhor representadas através de código. O código roda em um ambiente JavaScript protegido. Destina‑se a cálculos e pequenas transformações, não a I/O de arquivos, acesso à rede ou importação de scripts externos. Activation via `builtin_tools`: ```json { "tools": [ "Code" ], "options": { } } ``` ## Contexto de URL Esta função permite que o modelo acesse conteúdo externo em URLs e links fornecidos pelo usuário. Com essa função, o modelo pode acessar links e avaliar seu conteúdo. Observe que alguns destinos podem identificar o acesso como um bot e bloqueá‑lo, pois esta função não é um rastreamento, mas um simples GET ao destino. Ao obter o conteúdo do link, o sistema verifica o conteúdo retornado e o trata de acordo com cada tipo: - O conteúdo HTML é renderizado: tags HTML, scripts, CSS e “ruído” são removidos do resultado de acesso, mantendo apenas o texto simples do link. - Outro conteúdo textual: o conteúdo é lido diretamente e nenhuma transformação é feita. - Conteúdo não‑textual: quando o link responde com conteúdo não‑textual e a resposta indica um nome de arquivo (por caminho ou pelo cabeçalho `Content‑Disposition`), o sistema tenta converter o arquivo baixado para uma versão textual. Activation via `builtin_tools`: ```json { "tools": [ "OpenUrl" ], "options": { } } ``` ## Memória Esta função permite que o modelo armazene conteúdo relevante para ser usado em múltiplas conversas. > Atualmente, esta função está disponível apenas quando usada em [clientes de chat](https://docs.aivax.net/pt-br/docs/features/chat-clients.md) e quando a sessão é identificada por um `tag`. Através do `tag` da sessão, o modelo armazena um pedaço relevante de dados da conversa, como preferências de nome ou contexto persistente que o assistente deve lembrar. A ferramenta de memória requer uma sessão identificável. Sem um ID de referência de usuário, as operações de memória retornam um erro ao invés de armazenar ou buscar informações. A instrução de memória diz ao modelo para não salvar dados sensíveis ou pessoais, porém, não há garantia de que o modelo sempre seguirá essa regra. Cada memória salva pode incluir um período de retenção. It itens de memória podem ser pesquisados, atualizados, removidos individualmente ou limpos para o usuário. > Nota: em solicitações de chat/completions, o `tag` é especificado no parâmetro `$.user`. Activation via `builtin_tools`: ```json { "tools": [ "Remember" ], "options": { "include_all_memory_context": true } } ``` ## Geração de Imagem Esta função permite que o modelo crie imagens de IA. Imagens geradas por IA são anexadas ao contexto da conversa, mas não são diretamente visíveis ao assistente. A geração de imagens pode gerar custos de uso. Consulte [Preços](https://docs.aivax.net/pt-br/docs/pricing.md) antes de habilitá‑la em produção. Você também pode habilitar a geração de imagens explícitas e adultas na geração de imagens. Quando esse recurso está habilitado, o modelo será permitido a gerar conteúdo adulto. Para que isso ocorra, o modelo também deve “concordar” em gerar tal conteúdo. Alguns modelos têm um filtro de segurança mais baixo que outros. Por exemplo, modelos Gemini têm o filtro de segurança mais baixo, tornando‑os uma opção viável para role‑play e geração desse tipo de material. Você é sempre responsável pelo [material que você gera](https://docs.aivax.net/pt-br/docs/legal/terms-of-service.md) e o material gerado deve ser compatível com nossos termos de serviço. Os modelos de geração de imagem disponíveis são: - `gpt-image-2` - `wan-image-2.7-pro` - `wan-image-2.7` - `grok-imagine-pro` - `grok-imagine` - `seedream-5-lite` - `nanobanana-2` - `gpt-image-1.5` - `gpt-image-1-mini` - `seedream-4.5-pro` - `seedream-4` - `nanobanana-pro` - `nanobanana` - `flux-schnell` - `zimage-turbo` - `flux-2-klein` - `majicMIX-realistic` - `AbsoluteReality` - `CyberRealistic` - `RealCartoon-Realistic` - `CyberRealistic-Pony` - `Hassaku-XL` - `Meina-Mix` Imagens geradas são armazenadas nos servidores da AIVAX por alguns meses antes de serem removidas permanentemente. Activation via `builtin_tools`: ```json { "tools": [ "ImageGeneration" ], "options": { "image_generation_model_name": "grok-imagine", "image_generation_allow_reference_usage": true, "image_generation_quality": "high", "image_generation_max_results": 2, "image_generation_allow_mature_content": false } } ``` ## Busca de Posts X Esta função permite que o modelo procure posts no X (antigo Twitter) e leia um post específico quando o modelo tem um ID de post. É uma alternativa direta ao `web_search`, pois pode ser usado para buscar informações atualizadas em tempo real, como notícias, informações, resultados de jogos, etc. Esta ferramenta fornece resultados muito mais recentes que a ferramenta convencional de busca na internet. Não é recomendado usar ambas as funções juntas porque elas têm o mesmo propósito. Esta função pode gerar custos de uso. Consulte [Preços](https://docs.aivax.net/pt-br/docs/pricing.md) antes de habilitá‑la em produção. Activation via `builtin_tools`: ```json { "tools": [ "XPostsSearch" ], "options": { } } ``` ## Geração de Documento Esta função permite que o modelo crie PDFs a partir de texto HTML. Os arquivos criados são hospedados nos servidores da AIVAX e disponibilizados pelo assistente. O conteúdo é hospedado por alguns meses antes de ser excluído permanentemente. Activation via `builtin_tools`: ```json { "tools": [ "GenerateDocument" ], "options": { } } ``` ## Geração de Página Web Esta função permite que o modelo hospede páginas HTML nos servidores da AIVAX. Isso permite que o modelo hospede relatórios, páginas de destino e outras infografias HTML. O conteúdo é hospedado por alguns meses antes de ser excluído permanentemente. Activation via `builtin_tools`: ```json { "tools": [ "GenerateWebPage" ], "options": { } } ``` ## Solicitação Avançada Esta função fornece ao modelo uma ferramenta avançada de requisição HTTP. Com essa função, o modelo pode definir cabeçalhos, formulários, conteúdos e métodos para realizar requisições HTTP avançadas. Respostas de texto são lidas até o limite de conteúdo da plataforma. Respostas binárias não são expandidas no contexto; a ferramenta retorna um marcador de conteúdo binário curto com o tipo de conteúdo e tamanho quando disponível. Activation via `builtin_tools`: ```json { "tools": [ "Request" ], "options": { } } ``` ## Calendário O Calendário é sustentado pelo mesmo armazenamento de informações persistente da memória, mas armazena objetos de lembrete baseados em datas ao invés de texto solto de memória. Ele pode criar, buscar, encontrar, atualizar e excluir compromissos para um usuário identificado. Não é recomendado ativar esta função juntamente com a função de memória ou funções de agendamento de mensagens do cliente de chat. Activation via `builtin_tools`: ```json { "tools": [ "Calendar" ], "options": { } } ``` --- Source: https://docs.aivax.net/pt-br/docs/tools/mcp.html ## Suporte ao Protocolo de Contexto de Modelo (MCP) Você pode vincular ferramentas externas do protocolo MCP ao seu [AI Gateway](https://docs.aivax.net/pt-br/docs/inference/ai-gateway.md). O protocolo define ferramentas que são executadas no lado do servidor e permitem que o assistente interaja com serviços em tempo real. AIVAX funciona como um cliente MCP para inferência de gateway: ele se conecta à fonte MCP configurada, lista ferramentas, converte cada esquema de ferramenta em uma função chamável pelo modelo e chama o servidor MCP remoto quando o modelo seleciona essa ferramenta. ## Quando usar MCP Use o MCP quando você já possui ferramentas externas que precisam ser descobertas e chamadas por modelos de forma padronizada. Um servidor MCP é adequado para catálogos de ferramentas, integrações com sistemas internos, operações com estado, ferramentas compartilhadas entre múltiplos agentes e ambientes onde você deseja manter a lógica fora do AIVAX. AIVAX funciona como um cliente MCP: ele conecta o AI Gateway ao servidor remoto, lê as ferramentas disponíveis e permite que o modelo chame essas ferramentas durante a inferência. Não use o MCP apenas para substituir uma única chamada HTTP simples. Quando precisar expor uma função isolada com um callback específico e autenticação por nonce, [funções de protocolo](https://docs.aivax.net/pt-br/docs/tools/protocol-functions.md) geralmente são mais simples. Quando a capacidade já existe no AIVAX, como busca na web, abertura de URL, execução de código ou geração de imagens, [ferramentas integradas](https://docs.aivax.net/pt-br/docs/tools/builtin-tools.md) geralmente são o caminho mais direto. O MCP é melhor quando há um conjunto de ferramentas com seus próprios esquemas, quando outro sistema já fala MCP ou quando você deseja que o mesmo servidor seja usado por diferentes clientes. Em produção, trate o servidor MCP como uma API exposta a um agente. As descrições das ferramentas devem ser claras, os esquemas devem ser restritivos e a autenticação deve ser configurada nos cabeçalhos do servidor. O modelo não deve receber ferramentas excessivamente genéricas, como `execute`, `request` ou `search`, sem descrições fortes e parâmetros controlados. Ferramentas ambíguas aumentam chamadas erradas; ferramentas específicas como `lookup_customer_by_email` ou `create_support_ticket` ajudam o modelo a decidir melhor. ### Escolhendo o nome da função O nome da função deve ser simples e determinístico sobre o que a função faz. Evite nomes que sejam difíceis de adivinhar ou que não indiquem o papel da função, pois o assistente pode ficar confuso e não chamar a função quando necessário. Como exemplo, vamos pensar em uma função que consulta um usuário em um banco de dados externo. Os nomes a seguir são bons exemplos a considerar para a chamada: - `search_user` - `query_user` Nomes ruins incluem: - `search` (implícito, possivelmente ambíguo) - `search user` (nome com caracteres inadequados) ### Escolhendo a descrição da função A descrição da função deve explicar conceitualmente duas situações: o que ela faz e quando o assistente deve chamá‑la. Essa descrição deve incluir os cenários que o assistente deve considerar para chamá‑la e quando não deve ser chamada, fornecendo alguns exemplos de chamadas de um único disparo e/ou tornando as regras da função explícitas. ### Definindo servidores MCP Você pode definir seus servidores MCP no gateway através de um array JSON: ```json [ { "name": "My MCP server", "url": "https://example-server.io/mcp", "headers": { "Authorization": "sk-pv-12nbo..." } } ] ``` Seu servidor MCP deve suportar **HTTP transmissível** para funcionar com o AIVAX como fonte de ferramentas do gateway. Você pode definir cabeçalhos personalizados na configuração do seu servidor MCP para configurar autenticação ou outras necessidades. A descoberta de ferramentas é armazenada em cache de acordo com `cacheDuration`; o padrão é 600 segundos. ## Metadados enviados com chamadas de ferramentas Para cada requisição `tools/call`, o AIVAX adiciona contexto de execução em `params._meta`, ao lado de `params.arguments`. Os argumentos contêm a entrada da ferramenta; os metadados identificam o contexto de chamada e carregam valores fornecidos pela aplicação. Esses campos descrevem solicitações de execução de ferramentas, não a descoberta de ferramentas (`tools/list`). O exemplo a seguir ilustra uma chamada com um usuário identificado, um token de conversa e metadados personalizados: ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "get_weather", "arguments": { "location": "New York" }, "_meta": { "_aiv_nonce": "", "_aiv_external_user_id": "", "_aiv_call_source": "WebChatClient", "_aiv_conversation_token": "", "_aiv_moment": "2025-09-09T16:58:05.0000000+00:00", "tenant_id": "", "request_id": "" } } } ``` ### Campos AIVAX Todos os caminhos abaixo são relativos a `params._meta`. Nomes que começam com `_aiv` são reservados; não os use para metadados personalizados. | Campo | Tipo JSON | Significado e disponibilidade | | --- | --- | --- | | `_aiv_nonce` | `string` ou `null` | Hash BCrypt derivada da chave de hook da conta chamadora. Sem uma chave de hook configurada, seu valor é `null`. Verifique a chave de hook em texto plano configurada contra esse hash conforme descrito em [autenticação de hook](https://docs.aivax.net/pt-br/docs/authentication.md#hook-authentication); não compare strings de hash nem espere a própria chave de hook. | | `_aiv_external_user_id` | `string` ou `null` | Identificador externo de usuário transportado pelo contexto de inferência. Para clientes de chat vem da sessão; para conclusões de chat vem do campo `user` da requisição. Pode ser `null` quando nenhum usuário foi identificado. Use‑o para buscar o usuário na sua aplicação, não como um ID de conta AIVAX ou prova de autorização. | | `_aiv_call_source` | `string` | Origem da inferência, não o transporte de ferramenta de saída. Uma ferramenta MCP chamada durante inferência de chat web ainda recebe `WebChatClient`, não `McpClient`. Veja os valores abaixo. | | `_aiv_conversation_token` | `string` ou `null` | Token de correlação de conversa transportado pela sessão ou requisição de inferência. Para conclusões de chat, vem de `idempotency_key` quando fornecido. Pode ser `null`; não é credencial de autenticação nem um ID único de chamada de ferramenta. Várias chamadas na mesma conversa podem compartilhá‑lo. | | `_aiv_moment` | `string` | Timestamp criado quando o AIVAX prepara esta chamada de ferramenta, no formato ISO 8601 round-trip com segundos fracionários e offset UTC. Usa o relógio local do servidor AIVAX, não o fuso horário do usuário ou o horário de início da conversa. Analise o offset e converta para o fuso horário da sua aplicação quando necessário. | ### Valores de origem da chamada Os mesmos valores de string são usados por funções de protocolo em `context.callSource`: | Valor | Origem da inferência | | --- | --- | | `WebChatClient` | Cliente de chat web AIVAX. | | `ChatCompletionsApi` | API de conclusões de chat compatível com OpenAI; a origem padrão para essa API. | | `FunctionsApi` | API de funções. | | `IntegrationBot` | Bot de integração de mensagens. | | `OpenWebUiClient` | Cliente Open WebUI. | | `McpClient` | Inferência iniciada através de um cliente MCP. | | `ValidationApi` | Validação de teste agenteico. | Trate a origem como contexto de roteamento e diagnóstico, não como um papel de autorização. Os consumidores devem tolerar valores de origem futuros. ### Metadados personalizados e segurança Metadados de inferência personalizados são um mapa de chaves string para valores string. Eles vêm do `metadata` da requisição para conclusões de chat ou dos metadados de sessão para clientes de chat. O AIVAX copia essas entradas diretamente para `params._meta`: no exemplo, `tenant_id` e `request_id` são definidos pela aplicação, não campos integrados do AIVAX. Não há objeto `metadata` aninhado no envelope MCP. Sem metadados personalizados, permanecem apenas os campos AIVAX. Não envie segredos em metadados personalizados: esses valores são encaminhados para o servidor de ferramentas remoto. Valide o acesso do locatário e do usuário contra seus próprios registros confiáveis antes de usar metadados para selecionar dados ou realizar gravações. Nem um ID de usuário externo, um token de conversa ou um rótulo de origem de chamada concede permissão por si só. O nonce autentica a chave de hook da conta configurada; não é uma assinatura dos argumentos, um ID de requisição único ou um mecanismo de prevenção de replay. Mantenha HTTPS e os cabeçalhos de autenticação configurados no servidor MCP, e aplique sua própria autorização e controles de operação duplicada. Se seu servidor exigir autenticação por nonce, rejeite um nonce ausente ou inválido. Para o envelope de callback HTTP equivalente, veja [contexto da função de protocolo](https://docs.aivax.net/pt-br/docs/tools/protocol-functions.md#context-fields). ## Resultados das ferramentas Os resultados das ferramentas podem incluir blocos de conteúdo de texto, imagem e áudio. O texto é adicionado diretamente ao resultado da ferramenta. Blocos de imagem e áudio são anexados de volta à conversa como conteúdo multimodal com IDs gerados. Tipos de bloco de conteúdo não suportados são relatados como texto não suportado. Quando uma ferramenta MCP não aparece para o modelo, verifique se o servidor remoto está acessível, se suporta HTTP transmissível, se os cabeçalhos de autenticação estão corretos e se o gateway está realmente configurado com a fonte MCP. Quando a ferramenta aparece mas não é chamada, revise o nome, a descrição e o esquema. Quando é chamada com argumentos incorretos, restrinja o JSON Schema e inclua descrições de propriedades. Quando a chamada falha, faça o servidor MCP retornar erros legíveis, pois o modelo precisa entender se deve tentar outro argumento, pedir informações ao usuário ou encerrar a ação. --- Source: https://docs.aivax.net/pt-br/docs/tools/protocol-functions.html # Funções de Protocolo Funções de protocolo são ferramentas do lado do servidor AIVAX. Elas permitem que um modelo solicite uma ação nomeada enquanto o AIVAX executa a ação do servidor chamando seu callback HTTP ou uma URL de callback interna do AIVAX. Use-as quando um assistente precisar de uma forma controlada de interagir com sua aplicação, como verificar um pedido, abrir um ticket de suporte, validar um cupom, registrar um lead ou consultar um serviço privado. O modelo vê o nome da ferramenta, a descrição e o esquema de argumentos JSON. Ele não vê a URL de callback ou os cabeçalhos. Uma função de protocolo tem dois contratos: - **Contrato do modelo:** o nome público da ferramenta, a descrição e o JSON Schema que orientam a chamada da ferramenta pelo modelo. - **Contrato do callback:** a URL oculta e os cabeçalhos opcionais que o AIVAX usa para executar a ferramenta após a chamada do modelo. Essa separação mantém os detalhes de implementação fora do prompt, ainda dando ao modelo uma capacidade precisa de uso. ## Quando usar funções de protocolo Use funções de protocolo quando quiser expor uma ação HTTP específica a um AI Gateway sem criar um servidor MCP completo. Elas são boas para integrações pontuais, como verificar um pedido, abrir um ticket, buscar um usuário, validar um cupom, registrar um lead ou invocar uma automação interna. O AIVAX mantém a URL invisível ao modelo, envia a requisição do lado do servidor e adiciona o resultado textual ao contexto da conversa. Se você tem muitas ferramentas, ferramentas dinâmicas ou um sistema que já implementa o Model Context Protocol, prefira [MCP](https://docs.aivax.net/pt-br/docs/tools/mcp.md). Se quiser usar recursos já mantidos pelo AIVAX, prefira [ferramentas embutidas](https://docs.aivax.net/pt-br/docs/tools/builtin-tools.md). Se precisar tomar decisões antes ou depois de eventos de inferência, prefira [workers](https://docs.aivax.net/pt-br/docs/inference/workers.md). Funções de protocolo ficam no meio: são mais simples que MCP e mais específicas que workers, mas ainda dão ao modelo uma ferramenta controlada para executar uma ação externa. Uma função de protocolo deve ter um nome de ferramenta, uma descrição, uma URL de callback e um esquema de argumentos. O nome ajuda o modelo a reconhecer a ação; a descrição explica quando chamar; o esquema limita o formato dos argumentos. Nomes de funções devem ser identificadores JavaScript válidos com pelo menos três caracteres. A URL de callback e os detalhes de autenticação não são visíveis ao modelo. Isso permite criar ferramentas especializadas sem expor endpoints internos, desde que seu serviço valide o `X-Request-Nonce`, valide os argumentos recebidos e aplique sua própria autorização quando a chamada depender do usuário. Use a seguinte regra prática: | Necessidade | Preferir | |---|---| | Um ou poucos callbacks HTTP estáveis pertencentes ao seu aplicativo | Funções de protocolo | | Um catálogo maior de ferramentas, descoberta padronizada ou um servidor MCP existente | [MCP](https://docs.aivax.net/pt-br/docs/tools/mcp.md) | | Busca na web, leitura de URL, execução de código, geração de imagens, memória, calendário ou ferramentas de requisição HTTP mantidas pelo AIVAX | [Ferramentas embutidas](https://docs.aivax.net/pt-br/docs/tools/builtin-tools.md) | | Política em tempo de evento, reescrita de mensagem, injeção dinâmica de ferramenta ou bloqueio de chamada de ferramenta antes da execução | [Workers](https://docs.aivax.net/pt-br/docs/inference/workers.md) | | Definições de ferramenta nativas do provedor que seu próprio cliente executará | `tools` brutos em uma requisição compatível com OpenAI | ### Escolhendo o nome da função O nome da função deve ser simples e específico sobre o que a função faz. Evite nomes difíceis de adivinhar ou que não reflitam o papel da função, pois o assistente pode não chamá‑la quando necessário. Por exemplo, considere uma função que consulta um usuário em um banco de dados externo. Bons nomes incluem: - `search_user` - `query_user` Nomes fracos incluem: - `search` (amplo demais) - `query_user_in_database_data` (longo e barulhento) - `pesquisa-usuario` (nome não em inglês) - `search user` (nome com caracteres inadequados) Com o nome da função definido, podemos pensar na descrição da função. ### Escolhendo a descrição da função A descrição da função deve explicar o que ela faz, quando o assistente deve chamá‑la e quando não deve. Boas descrições incluem a entrada esperada, o tipo de resultado retornado e qualquer regra de decisão que o assistente deve seguir antes de chamar a ferramenta. Por exemplo, uma descrição útil é: > Use esta ferramenta para buscar o perfil de um cliente pelo ID do cliente quando o usuário solicitar status de conta, pedidos recentes ou elegibilidade de suporte. Não a chame quando o usuário fornecer apenas nome ou e‑mail; peça primeiro o ID do cliente. Isso dá ao modelo uma ação clara, um gatilho e uma limitação. Uma descrição vaga como “Search customers” oferece ao modelo muito menos orientação. ## Definindo funções de protocolo Funções de protocolo são definidas no [AI Gateway](https://docs.aivax.net/pt-br/docs/inference/ai-gateway.md). Você pode declará‑las diretamente no gateway quando a lista for estável, ou fornecer uma fonte remota que retorne a lista de funções quando o catálogo for gerenciado por outro serviço. A forma direta é a opção mais simples. Use‑a quando a lista de funções mudar raramente e pertencer à própria configuração do gateway. Referência: [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Create%20AI%20Gateway) ```json { "name": "my-ai-gateway", "parameters": { "baseAddress": "@integrated", "modelName": "@openai/gpt-5-mini", "protocolFunctions": [ { "name": "list_clients", "description": "Use this tool to list and search for the user's clients.", "callbackUrl": "https://my-external-api.com/api/scp/users", "contentFormat": { "type": "object", "properties": {} } }, { "name": "view_client", "description": "Use this tool to obtain details and orders of a client via its ID.", "callbackUrl": "https://my-external-api.com/api/scp/users", "contentFormat": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" } }, "required": ["user_id"] } } ] } } ``` No trecho acima, o gateway expõe `list_clients` e `view_client` ao modelo. O modelo decide se chama uma delas durante a geração. Se chamar `view_client`, o AIVAX valida os argumentos contra `contentFormat` e então envia a requisição de callback ao seu serviço. ## Fontes de funções de protocolo Fontes de funções de protocolo permitem que um gateway carregue suas funções de protocolo a partir de um ou mais endpoints remotos, em vez de armazenar cada função inline. Na configuração do gateway, `protocolFunctionSources` é um array de strings de URL, não um array de objetos de origem. Use fontes quando o catálogo de funções pertencer a outro serviço, mudar independentemente do gateway ou precisar ser compartilhado por vários gateways. Cada URL de origem é um endpoint HTTP que retorna um objeto JSON com um array `functions`. O AIVAX busca a origem antes de preparar as opções de inferência, converte cada definição retornada em uma ferramenta do lado do servidor e armazena em cache por 10 minutos por conta e URL de origem. Durante a janela de cache, o AIVAX reutiliza as definições de função em vez de fazer outra requisição de listagem. Use `protocolFunctions` inline para ferramentas estáveis e controladas pelo gateway. Use `protocolFunctionSources` para catálogos gerenciados remotamente. Você pode usar ambos no mesmo gateway, mas os nomes das funções devem permanecer únicos após a combinação de funções inline, funções originadas, ferramentas MCP, ferramentas embutidas e ferramentas brutas. Defina os endpoints de listagem de funções no seu AI Gateway: ```json { "name": "my-ai-gateway", "parameters": { "baseAddress": "@integrated", "modelName": "@openai/gpt-5-mini", "protocolFunctionSources": [ "https://my-external-api.com/api/scp/listings" ] } } ``` O endpoint de origem de funções recebe uma requisição `GET`. Ele deve retornar um status HTTP de sucesso e um objeto JSON neste formato:
GET https://my-external-api.com/api/scp/listings
```json { "functions": [ { "name": "list_clients", "description": "Use this tool to list and search for the user's clients.", "callbackUrl": "https://my-external-api.com/api/scp/users", "contentFormat": { "type": "object", "properties": {} } }, { "name": "view_client", "description": "Use this tool to obtain details and orders of a client via its ID.", "callbackUrl": "https://my-external-api.com/api/scp/users", "contentFormat": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" } }, "required": ["user_id"] } } ] } ``` Os objetos de função retornados usam a mesma estrutura das `protocolFunctions` inline: `name`, `description`, `callbackUrl`, `headers` opcionais e `contentFormat`. Se o endpoint de origem retornar um status não‑de sucesso, o AIVAX registra o erro e a requisição de inferência falha ao preparar as ferramentas. Torne o endpoint de origem rápido, estável e pequeno o suficiente para retornar apenas as funções que o gateway deve expor. Se o catálogo for específico de usuário ou locatário, use o nonce da requisição e suas próprias regras de autorização para decidir quais funções retornar. ### Manipulando chamadas de função Funções são invocadas no endpoint fornecido em `callbackUrl` via requisição HTTP POST. O AIVAX envia `Content-Type: application/json` e um corpo equivalente a: ```json { "type": "tool_call", "function": { "name": "view_client", "content": { "user_id": "example-user-id" } }, "context": { "externalUserId": "", "metadata": { "tenant_id": "", "request_id": "" }, "callSource": "WebChatClient", "conversationToken": "", "moment": "2025-05-18T03:36:27+00:00" } } ``` A resposta a essa ação deve retornar um status HTTP de sucesso (2xx), mesmo para erros que o assistente possa ter cometido. Uma resposta não‑de sucesso é registrada e o modelo recebe um erro genérico de chamada de ferramenta em vez do corpo da sua resposta. #### Campos de contexto O AIVAX constrói `context` separadamente dos argumentos gerados pelo modelo em `function.content`. Seu callback deve validar os argumentos contra o esquema da função e usar o contexto para correlacionar a requisição com sua aplicação. O contexto não é um conjunto adicional de argumentos selecionados pelo modelo. | Campo | Tipo JSON | Significado e disponibilidade | | --- | --- | --- | | `context.externalUserId` | `string` ou `null` | Identificador externo do usuário a partir do contexto de inferência. Para uma [sessão de chat](https://docs.aivax.net/pt-br/docs/features/chat-clients.md), este é o ID externo do usuário da sessão; para completions de chat, vem do campo `user` da requisição. Pode ser `null` quando nenhum usuário foi identificado. Não é um ID de conta AIVAX nem credencial de autenticação. | | `context.metadata` | `object` | Parâmetros de chave/valor de string fornecidos pela aplicação a partir da requisição de inferência ou sessão de chat. Para completions de chat, são as entradas `metadata` da requisição. O objeto está vazio (`{}`) quando nada é fornecido. O `tenant_id` e `request_id` do exemplo são campos personalizados, não nomes gerados pelo AIVAX. | | `context.callSource` | `string` | Origem da inferência, como `WebChatClient`, `ChatCompletionsApi` ou `IntegrationBot`. Não descreve o transporte do callback: chamar uma função de protocolo não define automaticamente o valor `FunctionsApi`. Consulte os valores compartilhados de [fonte de chamada](https://docs.aivax.net/pt-br/docs/tools/mcp.md#call-source-values) para todos os valores atuais. | | `context.conversationToken` | `string` ou `null` | Token de correlação da conversa transportado pela sessão ou requisição de inferência. Para completions de chat, vem de `idempotency_key` quando fornecido. Pode ser `null`, e múltiplas chamadas de função podem compartilhá‑lo. Não o trate como um ID de callback único, credencial ou garantia de que uma operação já foi executada. | | `context.moment` | `string` | Timestamp de data‑hora JSON criado quando o AIVAX prepara o callback, usando o relógio local do servidor. Não é a hora local do usuário nem o horário de início da conversa. Analise como data‑hora com seu deslocamento UTC em vez de depender de precisão fracionária fixa; converta para o fuso horário da sua aplicação quando necessário. | Metadados personalizados permanecem aninhados em `context.metadata`; não são mesclados em `context`. Isso difere dos [metadados MCP](https://docs.aivax.net/pt-br/docs/tools/mcp.md#metadata-sent-with-tool-calls), onde as mesmas entradas personalizadas ficam ao lado dos campos reservados `_aiv_*` em `params._meta`. O nonce de autenticação **não** é um campo `context` ou `metadata`. Funções de protocolo recebem-no no cabeçalho HTTP `X-Request-Nonce` quando a conta tem uma chave de hook. Chamadas de ferramenta MCP carregam o valor equivalente em `params._meta._aiv_nonce`. Esses campos de contexto descrevem requisições POST de execução; não presuma que requisições de listagem de funções tenham esse corpo JSON. #### Formato da resposta Respostas bem‑sucedidas devem ser textuais e serão anexadas como resposta da função da que o endpoint retornar. Não há formato ou estrutura JSON para essa resposta, mas é recomendável fornecer uma resposta simples e legível para que o assistente possa ler o resultado da ação. Erros podem ser comuns, como não encontrar um cliente por ID ou um campo não estar no formato desejado. Nesses casos, responda com status OK e inclua uma descrição humana do erro no corpo da resposta e como o assistente pode contorná‑lo. Os argumentos são validados contra o JSON Schema antes da execução. Seu callback ainda deve validar os argumentos recebidos, pois os esquemas podem limitar a estrutura, mas não substituem autorizações de negócio ou verificações de consistência. Funções que não esperam argumentos devem usar um esquema de objeto vazio. A resposta da função deve ser escrita para o modelo, não para o usuário final. Ela pode conter dados, avisos e instruções curtas sobre como usar o resultado. Por exemplo, se uma busca de pedido encontrar o status, responda com o status, data esperada e restrições relevantes. Se não for encontrado, indique que o pedido não foi localizado e indique quais dados o assistente deve solicitar ao usuário. Evite retornar objetos enormes, HTML, logs brutos ou mensagens internas, pois esse conteúdo entra no contexto e pode confundir a próxima resposta. > [!IMPORTANT] > > Quanto mais funções você definir, mais tokens de entrada consumirá no processo de raciocínio. A definição da função, assim como seu formato, consomem tokens do processo de raciocínio. #### Autenticação A autenticação da requisição é feita via cabeçalho `X-Request-Nonce` enviado em chamadas de funções de protocolo e requisições de listagem de origem. Consulte o manual de [autenticação](https://docs.aivax.net/pt-br/docs/authentication.md) para entender como autenticar requisições reversas do AIVAX. #### Autenticação do usuário Use `context.externalUserId` para localizar o chamador em sua aplicação e, em seguida, verifique se esse usuário pode acessar o recurso solicitado ou executar a ação requerida. Se uma função exigir um usuário identificado, rejeite chamadas sem um identificador utilizável em vez de conceder acesso anônimo silenciosamente. Valide o nonce e aplique suas próprias regras de autorização de usuário e locatário. Metadados de requisição e sessão podem conter valores fornecidos pelo chamador: um `tenant_id`, `callSource` ou `conversationToken` não são prova de permissão. Evite colocar segredos em metadados porque eles são encaminhados ao seu callback. O nonce verifica a chave de hook da conta, não as permissões individuais do usuário, e não assina o corpo nem impede replay; use seus próprios controles de operação duplicada para gravações. #### Considerações de segurança Para o modelo de IA, apenas o nome, a descrição e o formato da função são visíveis. Ele não pode ver o endpoint para o qual a função aponta. Também não recebe os cabeçalhos de callback configurados para a função. Trate todas as requisições de callback como chamadas privilegiadas de servidor‑para‑servidor: valide o nonce, valide os argumentos, aplique autorização e evite expor ações de gravação amplas a menos que sua aplicação tenha suas próprias regras de aprovação. ## Funções especializadas Além das [funções embutidas](https://docs.aivax.net/pt-br/docs/tools/builtin-tools.md), você pode definir funções especializadas que executam tarefas específicas em sua conta AIVAX. Você define funções especializadas usando o esquema de URL `aivax://`, conforme o exemplo abaixo: ```json { "name": "my-ai-gateway", "parameters": { "baseAddress": "@integrated", "modelName": "@openai/gpt-5-mini", "protocolFunctions": [ { "name": "search_disease", "description": "Use this tool to search for diseases, treatments, and symptoms.", "callbackUrl": "aivax://query-collection?collection-id=your-collection-id&top=5&min=0.4", "contentFormat": { "type": "object", "properties": { "query": { "type": "string", "description": "Name of the disease, treatment, or symptoms." } }, "required": [ "query" ] } } ] } } ``` A função acima cria uma ferramenta para que a IA consulte uma [coleção de documentos](https://docs.aivax.net/pt-br/docs/rag/collections.md) específica, orientando o assistente sobre o que buscar nessa coleção e o que esperar da resposta. Dessa forma, você pode vincular várias coleções RAG para que um assistente recupere conteúdo especializado. Você pode personalizar a descrição das propriedades do JSON Schema para funções especializadas, mas sua estrutura é fixa. Os parâmetros da função especializada são fornecidos na URL via parâmetros de consulta. Atualmente, existe apenas uma função especializada: - `query-collection`: realiza uma busca RAG em uma coleção especificada. Parâmetros de consulta: - `collection-id`: o UUID da coleção a ser pesquisada. - `top`: número indicando quantos documentos devem ser retornados na busca. - `min`: decimal indicando a pontuação mínima de similaridade da busca. - `refs`: quando presente, inclui documentos pai referenciados no resultado RAG. Formato JSON da função: ```json { "type": "object", "properties": { "query": { "type": "string", "description": "Search content." } }, "required": [ "query" ] } ``` --- Source: https://docs.aivax.net/pt-br/docs/tools/shell.html # Shell AIVAX oferece um ambiente de shell virtual que pode ser usado por assistentes de agente para executar comandos de terminal durante a inferência. Esse recurso é especialmente útil para tarefas como manipulação de dados, chamadas de API, execução de scripts e fluxos de trabalho que são mais fáceis de expressar como operações de linha de comando. O ambiente de shell permite mover ferramentas selecionadas do modelo para o lado do shell, transformando-as em comandos CLI. Isso é útil quando você tem muitas ferramentas e não quer expor todas diretamente ao modelo, ou quando uma ferramenta é mais fácil de usar através de argumentos de linha de comando e pipes. Quando habilitado em um AI Gateway, o modelo vê uma ferramenta `shell` com um argumento: `command`. Os comandos são executados em um shell isolado com módulos de rede, padrões de sistema de arquivos e um workspace montado em `/home/workspace`. Cada comando tem limite de 60 segundos e devolve até 4.096 caracteres de saída ao modelo. ## Design for the limits O limite de tempo de 60 segundos e o teto de saída de 4.096 caracteres definem como as ferramentas de shell devem se comportar. Mantenha os comandos rápidos e a saída enxuta: filtre no servidor com `grep`, `awk` ou bandeiras de consulta antes de imprimir, e prefira ferramentas que retornem CSV ou linhas delimitadas que o modelo possa fatiar com pipes. Quando um resultado ultrapassa legitimamente o limite, divida o trabalho — um comando para listar ou contar, sequenciais para buscar fatias — ou grave a saída completa em um arquivo de workspace e leia a parte relevante de volta através da API de arquivos do Shell abaixo. Operações de longa duração não pertencem a um comando de inferência. Mova exportações, transformações em lote e loops de polling para [Batch](https://docs.aivax.net/pt-br/docs/features/batch.md) ou um job externo, e deixe o shell lidar com as fatias interativas. ## Adapting tools for shell Na interface de shell virtual, utilitários de linha de comando padrão e módulos de shell registrados estão disponíveis. Dessa forma, você pode adaptar suas ferramentas para devolver saídas brutas ou longas, e o modelo pode usar as ferramentas de manipulação de texto do shell para extrair a informação relevante, por exemplo: ```bash get-users --filter active --format csv | grep "John Doe" | awk -F, '{print $1, $2}' ``` Na linha acima, `get-users` é uma ferramenta personalizada que devolve uma lista de usuários em formato CSV. O comando `grep` filtra os resultados para encontrar "John Doe", e `awk` extrai e formata as colunas desejadas. Essa ferramenta pode ter sido definida por [MCP](https://docs.aivax.net/pt-br/docs/tools/mcp.md), [built-in tools](https://docs.aivax.net/pt-br/docs/tools/builtin-tools.md) ou ser uma [protocol tool](https://docs.aivax.net/pt-br/docs/tools/protocol-functions.md). Ferramentas movidas para o shell não são mais expostas como funções diretas do modelo, exceto ferramentas reservadas como `shell` e `read_skill`. Configure a lista de ferramentas do shell como: - `WhiteList`: apenas as ferramentas listadas são expostas como comandos de shell. - `BlackList`: as ferramentas listadas permanecem como funções diretas do modelo, e as demais ferramentas não reservadas são expostas como comandos de shell. Use o nome da função em tempo de execução ao listar ferramentas, como `web_search`, `open_url`, `request`, ou um nome de função de protocolo/MCP. Cada comando de shell gerado a partir de uma ferramenta suporta `--help` e mapeia propriedades do JSON Schema para opções de linha de comando. Prefira a whitelist quando o modelo precisar de um conjunto pequeno e previsível de comandos — caso contrário, cada nova ferramenta vaza automaticamente para o shell. Prefira a blacklist quando a maioria das ferramentas for amigável ao shell e apenas algumas precisam permanecer como funções diretas por motivos de latência ou confiabilidade. ## Data persistence É possível definir persistência de dados para o ambiente de shell. Quando `allowDataPersistence` está habilitado e o contexto de inferência possui um ID externo de usuário, AIVAX monta um workspace persistente escopoado à conta e ao usuário. Isso permite que o agente mantenha arquivos entre conversas e sessões para aquele usuário identificado. Se a persistência estiver desativada, ou o contexto de inferência não tiver ID externo de usuário, o shell usa um sistema de arquivos em memória e o workspace é descartado após a iteração de inferência. Habilite a persistência apenas para dados que o usuário espera que sobrevivam — documentos de trabalho, relatórios gerados, configurações que ele gerencia. Mantenha segredos, credenciais e dados de outros usuários fora do workspace persistente: tudo o que for escrito lá persiste além da sessão que o criou. ## Shell file API AIVAX também expõe endpoints de I/O do Shell em `/api/v1/shell/io` para contas autenticadas. Esses endpoints utilizam o cabeçalho obrigatório `X-Shell-User-Id` para delimitar o sandbox de sistema de arquivos e suportam listagem de diretórios, download de arquivos, inspeção de metadados, criação de endereços públicos temporários, upload de arquivos, criação de diretórios e exclusão de arquivos ou diretórios. Uploads são documentados com um corpo de requisição máximo de 100 MB. Reference: [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=List%20Directory) [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Download%20File) [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Get%20File%20Details) [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Get%20File%20Public%20Address) [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Upload%20File) [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Create%20Directory) [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Delete%20File) [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Delete%20Directory) --- Source: https://docs.aivax.net/pt-br/docs/mcp-utilities/collections-mcp.html # Coleções MCP O Collections MCP expõe uma ou mais coleções AIVAX RAG como ferramentas para clientes MCP compatíveis. Use-o quando um modelo externo, agente, IDE ou assistente de desktop deve decidir quando pesquisar uma base de conhecimento AIVAX. Para informações sobre como criar coleções, preparar documentos e melhorar a qualidade da recuperação, veja [Collections and Documents](https://docs.aivax.net/pt-br/docs/rag/collections.md) e [Semantic Search](https://docs.aivax.net/pt-br/docs/rag/semantic-search.md). ## Endpoint ```text https://inference.aivax.net/v1/mcp/collections ``` ## Headers | Header | Description | Default | | --- | --- | --- | | `Authorization` | Token Bearer da sua chave de API. | Required | | `X-Mcp-Collection-Id` | Um ou mais IDs de coleção. Use vírgulas para múltiplas coleções. | Required | | `X-Mcp-Collection-Name` | Nome da coleção usado para gerar nomes de ferramentas. | `collection` | | `X-Mcp-Reranker` | Seleciona o ranqueador usado para ordenar os resultados da pesquisa. Use um `@provider/name` canônico, `lexical`, `rrf`, `smart` ou `none`. | `@aivax/reflex-v1` | | `X-Mcp-Top-K` | Número máximo de resultados a retornar. | `5` | | `X-Mcp-Min-Score` | Pontuação mínima de relevância maior que 0 e até 1.0. | `0.4` | | `X-Mcp-Use-References` | Defina como `none` para habilitar referências nos resultados da pesquisa; omita o cabeçalho para desativá‑las. | disabled | | `X-Mcp-Allow-Write` | Use `yes` para expor ferramentas de escrita e exclusão de documentos. | disabled | | `X-Mcp-Naming-Convention` | Controla como as ferramentas geradas são nomeadas. Use `default` ou `agent`. | `default` | ## Exemplo de configuração Visual Studio Code: ```json { "servers": { "my-rag-collection-mcp": { "type": "http", "url": "https://inference.aivax.net/v1/mcp/collections", "headers": { "Authorization": "Bearer ", "X-Mcp-Collection-Id": "", "X-Mcp-Collection-Name": "my_collection", "X-Mcp-Top-K": "5", "X-Mcp-Min-Score": "0.4", // Habilita referências nos resultados da pesquisa. "X-Mcp-Use-References": "none" } } } } ``` ## Ferramentas geradas Com a convenção de nomeação padrão, a ferramenta de leitura recebe o nome: ```text {collection_name}_search ``` Ela aceita: - `search_terms` (`string[]`): um ou mais termos de pesquisa. A ferramenta de leitura MCP impõe dois limites de model de requisição: - No máximo 10 termos de pesquisa por chamada. - No máximo 500 caracteres no total em todos os termos de pesquisa. Quando `X-Mcp-Allow-Write` está desativado, apenas a ferramenta de pesquisa é exposta. Este é o modo recomendado para assistentes que precisam apenas ler uma base de conhecimento. Quando `X-Mcp-Allow-Write: yes` é enviado, o servidor também expõe ferramentas de criação/atualização e exclusão de documentos. Habilite isso apenas para clientes confiáveis, pois um modelo com acesso de escrita pode alterar o conteúdo da coleção. Use Collections MCP quando um modelo externo ou cliente MCP deve decidir quando pesquisar. Para um cliente de chat típico da AIVAX, costuma ser mais simples anexar a coleção diretamente a um [AI Gateway](https://docs.aivax.net/pt-br/docs/inference/ai-gateway.md) e deixar que o pipeline RAG do gateway recupere os documentos automaticamente. --- Source: https://docs.aivax.net/pt-br/docs/mcp-utilities/documentation-mcp.html # Documentação MCP O MCP de documentação da AIVAX expõe a documentação da AIVAX, o conteúdo de referência da API e os metadados do modelo para clientes compatíveis com MCP. É projetado para assistentes, IDEs, agentes internos e fluxos de implementação que precisam do contexto atual da AIVAX antes de responder, escrever código, configurar um gateway ou solucionar problemas de integração. Este MCP é orientado à leitura. Não expõe uma ferramenta genérica de invocação de API de conta. Use‑o quando um agente precisa entender os recursos da AIVAX, encontrar a rota correta da API, comparar capacidades dos modelos ou basear sua resposta no manual do produto. Use o [account management MCP](https://docs.aivax.net/pt-br/docs/mcp-utilities/account-management-mcp.md) apenas quando o cliente também precisar inspecionar ou alterar recursos de conta autenticados por meio de chamadas de API. > [!NOTE] > Não configure o MCP de documentação junto com o [account management MCP](https://docs.aivax.net/pt-br/docs/mcp-utilities/account-management-mcp.md) no mesmo cliente, a menos que tenha um motivo específico para duplicar ferramentas. O account management MCP já inclui funções de busca na documentação, portanto, adicionar ambos os servidores geralmente cria ferramentas de documentação redundantes e pode tornar a seleção de ferramentas menos previsível. ## Endpoint ```text https://inference.aivax.net/v1/mcp/documentation ``` Autentique‑se com uma chave de API de conta AIVAX: ```text Authorization: Bearer ``` Para tipos de chave e opções de autenticação, veja [Authentication](https://docs.aivax.net/pt-br/docs/authentication.md). ## Exemplo de configuração A configuração exata depende do cliente MCP. Para clientes que aceitam uma entrada de servidor HTTP streamable, configure o endpoint de documentação da AIVAX e passe a chave de API como cabeçalho. ```json { "servers": { "aivax-docs": { "type": "http", "url": "https://inference.aivax.net/v1/mcp/documentation", "headers": { "Authorization": "Bearer " } } } } ``` Após a conexão do cliente, ele pode descobrir as ferramentas expostas pelo servidor. Os nomes das ferramentas são prefixados com `aivax_` para que permaneçam claros quando o cliente também possui ferramentas de projeto, banco de dados, navegador ou código disponíveis. ## Ferramentas disponíveis ### `aivax_search_documentation` Busca a documentação da AIVAX e o conteúdo de referência da API. Use esta ferramenta quando o assistente precisa de contexto do produto antes de responder ou agir. A ferramenta aceita: | Argumento | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `search_terms` | `string[]` | Sim | Termos de busca a consultar na documentação da AIVAX e na referência da API. | | `search_type` | `string` | Não | Escopo da busca. Use `documentation-manual`, `api-function-reference` ou `all`. | A busca pode consultar o manual de documentação, a referência de funções da API ou ambos. Ela devolve trechos relevantes da documentação em formato de texto para que o cliente possa usá‑los diretamente como contexto. A busca é limitada a 10 termos por chamada e 500 caracteres no total entre todos os termos. Argumentos de exemplo: ```json { "search_terms": [ "cabeçalhos de origem do AI Gateway MCP", "metadados da ferramenta" ], "search_type": "all" } ``` Use frases mais completas quando a pergunta tem uma intenção clara, como `configurações de reordenador de busca semântica` ou `restrições de conclusão de chat com chave pública`. Use múltiplos termos quando quiser cobrir conceitos vizinhos, nomes alternativos ou termos prováveis de referência da API. As chamadas de busca utilizam as cotas por conta documentadas em [Plans and limits](https://docs.aivax.net/pt-br/docs/limits.md#plan-limits). ### `aivax_list_models` Lista os modelos de chat integrados da AIVAX e devolve um resumo legível por modelo para cada correspondência. Use‑o quando o assistente precisa escolher um modelo, explicar se um modelo está disponível no plano atual, comparar capacidades ou entender preços e rotas de provedores. A ferramenta aceita: | Argumento | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `name_filter` | `string` | Não | Filtro difuso opcional para nomes de modelo, como `gpt 5`, `sonnet`, `qwen coder` ou `@openai/gpt-5-mini`. | A resposta inclui descrição do modelo, estabilidade, tipo, capacidades, flags, grupo de limite de taxa, modelo de roteamento, multiplicador de assinatura, metadados técnicos, preço por token e provedores. A disponibilidade é avaliada com base no plano da conta autenticada. Argumentos de exemplo: ```json { "name_filter": "gemini flash" } ``` As chamadas de listagem de modelos utilizam as cotas por conta documentadas em [Plans and limits](https://docs.aivax.net/pt-br/docs/limits.md#plan-limits). ## Quando usar Use o MCP de documentação quando quiser que um assistente responda a perguntas da AIVAX a partir de contexto baseado em fonte ao invés de memória. Isso é útil em IDEs, ferramentas de suporte, agentes de integração, copilotos de implementação internos e fluxos de avaliação onde o assistente deve buscar no manual antes de recomendar uma rota, parâmetro, recurso, modelo ou passo de depuração. Também é útil para fluxos de construção de agentes. Antes de criar ou editar um [AI Gateway](https://docs.aivax.net/pt-br/docs/inference/ai-gateway.md), um assistente pode buscar o recurso relevante, verificar capacidades do modelo e então explicar qual configuração deve ser usada e por quê. Por exemplo, ele pode comparar ferramentas embutidas, funções MCP, funções do lado do servidor, workers, coleções RAG, respostas estruturadas e pré‑processamento multimodal antes de sugerir um design. Para solução de problemas, o MCP de documentação ajuda o assistente a passar de uma mensagem de erro para o provável limite do produto. Ele pode buscar regras de autenticação, limites de plano, requisitos de equilíbrio multimodal, parâmetros de busca RAG, comportamento do gateway ou restrições de chave pública, e então gerar um checklist focado que reflita o comportamento da AIVAX. Para seleção de modelo, combine `aivax_search_documentation` com `aivax_list_models`. Busque no manual o requisito de recurso, como chamada de ferramenta, entrada de vídeo, saída estruturada ou contexto longo, então liste os modelos correspondentes e escolha um que esteja disponível no plano da conta. ## Escolhendo termos de busca Bons termos de busca devem descrever o objetivo do usuário, não apenas uma palavra‑chave. Prefira: ```text restrições de conclusão de chat com chave pública pesquisa semântica inclui referências cabeçalhos de origem do AI Gateway MCP pré-processamento multimodal de vídeo ``` Em vez de: ```text chave pesquisa cabeçalhos vídeo ``` Quando o assistente não souber qual página contém a resposta, use `search_type: "all"`. Quando precisar de nomes de rotas, corpos de requisição ou comportamento de endpoint, use `api-function-reference`. Quando precisar de orientação conceitual, trade‑offs ou explicações de fluxo de trabalho, use `documentation-manual`. ## Orientação de segurança O MCP de documentação é mais seguro que uma ferramenta de gerenciamento porque é orientado à leitura, mas ainda se autentica como uma conta AIVAX e pode expor disponibilidade de modelo sensível ao plano da conta. Conecte‑o apenas a clientes que devam conhecer os modelos disponíveis da conta e o contexto da documentação. Use uma chave de API dedicada para cada cliente MCP. Armazene‑a no mecanismo de segredo do cliente ou em um armazenamento de configuração local, não no controle de versão. Se um cliente precisar apenas de documentação pública e não necessitar de disponibilidade de modelo específica da conta, prefira vincular diretamente ao site de documentação pública ao invés de conectar a um servidor MCP autenticado. --- Source: https://docs.aivax.net/pt-br/docs/mcp-utilities/account-management-mcp.html # Gerenciamento de conta MCP O gerenciamento de conta MCP expõe operações selecionadas de conta AIVAX para um cliente compatível com MCP, como um IDE, assistente de desktop, agente interno ou ambiente de automação. Ele foi projetado para operadores confiáveis e fluxos de trabalho de back‑end que precisam inspecionar capacidades de conta, descobrir documentação ou chamar rotas de API AIVAX autenticadas sem sair do cliente MCP. Esse ponto de término é diferente de configurar uma fonte MCP externa dentro de um [AI Gateway](https://docs.aivax.net/pt-br/docs/tools/mcp.md). Nesse fluxo, AIVAX é o cliente MCP e seu gateway chama outro servidor durante a inferência. Com o gerenciamento de conta MCP, AIVAX é o servidor MCP. Seu cliente MCP se conecta ao AIVAX e recebe ferramentas para operar a conta autenticada. Use este MCP quando um agente precisar de contexto de conta antes de agir: quais modelos estão disponíveis no plano atual, como um recurso é documentado, o que uma rota de API retorna ou se um recurso de conta pode ser criado, atualizado ou inspecionado através da API AIVAX existente. É especialmente útil para assistentes de suporte interno, ambientes de desenvolvimento, copilotos de administração de conta e agentes de implementação que precisam combinar consulta de documentação com chamadas reais de API. Como o MCP pode invocar funções AIVAX autenticadas, conecte‑o apenas a partir de clientes confiáveis e use uma chave de API privada. Não exponha este servidor a usuários finais ou aplicações no lado do navegador. > [!NOTE] > Não configure o gerenciamento de conta MCP junto com o [documentation MCP](https://docs.aivax.net/pt-br/docs/mcp-utilities/documentation-mcp.md) no mesmo cliente, a menos que tenha um motivo específico para duplicar ferramentas. O gerenciamento de conta MCP já inclui funções de busca de documentação, portanto adicionar ambos os servidores geralmente cria ferramentas de documentação redundantes e pode tornar a seleção de ferramentas menos previsível. ## Endpoint ```text https://inference.aivax.net/v1/mcp/account-management ``` A solicitação deve autenticar com uma chave de API de conta. Use uma chave privada no cabeçalho `Authorization`: ```text Authorization: Bearer ``` Para tipos de chave e opções de autenticação, veja [Authentication](https://docs.aivax.net/pt-br/docs/authentication.md). ## Exemplo de configuração A forma exata da configuração do MCP depende do cliente. Para clientes que aceitam uma entrada de servidor HTTP Streamable, configure o endpoint AIVAX e envie a chave privada como cabeçalho. ```json { "servers": { "aivax-account": { "type": "http", "url": "https://inference.aivax.net/v1/mcp/account-management", "headers": { "Authorization": "Bearer " } } } } ``` Depois que o cliente se conectar, ele pode listar as ferramentas expostas pelo servidor de gerenciamento de conta. Os nomes das ferramentas são estáveis e intencionalmente prefixados com `aivax_` para que permaneçam claros quando misturados com ferramentas de outros servidores MCP. ## O que você pode usar O gerenciamento de conta MCP é útil quando o assistente precisa raciocinar sobre a própria conta, não apenas responder a um prompt de usuário final. Ele fornece ao cliente MCP uma forma controlada de combinar documentação AIVAX, metadados de modelo e chamadas de API de conta autenticadas. Isso o torna adequado para agentes operacionais, copilotos de implementação e assistentes internos que precisam inspecionar como um workspace AIVAX está configurado antes de recomendar ou alterar algo. ### Criar e manter agentes Um agente de desenvolvimento interno pode usar o MCP para ajudar a criar, revisar e ajustar [AI Gateways](https://docs.aivax.net/pt-br/docs/inference/ai-gateway.md). Antes de mudar um gateway, o agente pode buscar no manual AIVAX o recurso relevante, listar modelos disponíveis para a conta atual, comparar capacidades de modelo e disponibilidade de plano, e então invocar a rota de API de conta apropriada. Isso é útil quando equipes criam assistentes para diferentes departamentos, locatários ou produtos com frequência. O MCP permite que o operador peça um agente em termos de produto, como “criar um assistente de suporte para políticas de reembolso com o CRM MCP habilitado”, enquanto o assistente de implementação verifica quais modelos, ferramentas, coleções RAG e opções de gateway estão disponíveis na conta. Para fluxos de trabalho de produção, mantenha uma etapa de aprovação humana antes de gravações. O MCP pode ajudar a preparar a configuração, explicar os trade‑offs e mostrar a ação de API que pretende executar antes de modificar o estado da conta. ### Monitorar custos e escolhas de modelo O MCP pode ajudar um assistente de operações a investigar padrões de custo e seleção de modelo. Listando modelos e invocando rotas de API de conta para uso, faturamento, gateway ou informações de chave, o assistente pode explicar quais modelos são caros, quais rotas usam um multiplicador de assinatura e se um modelo mais barato poderia lidar com parte da carga de trabalho. Isso é especialmente útil quando uma equipe tem muitos gateways ou jobs em lote e quer entender por que o gasto mudou. Em vez de olhar apenas para os totais, um assistente pode conectar uso a metadados de modelo, disponibilidade de plano, configuração de gateway e escolhas de recurso como RAG, ferramentas, lote ou entrada multimodal. Use isso para verificações recorrentes como “quais gateways provavelmente gerarão custo esta semana?”, “quais famílias de modelo estão sendo mais usadas?” ou “podemos mover este fluxo de trabalho de baixo risco para um modelo menor sem perder capacidades necessárias?” ### Entender erros e melhorar observabilidade Quando uma integração falha, o gerenciamento de conta MCP pode ajudar um assistente a passar de um erro genérico para um diagnóstico útil. O assistente pode buscar documentação para a rota ou recurso que falhou, inspecionar recursos de conta através de chamadas de API e comparar a resposta observada com o comportamento esperado. Por exemplo, um assistente de suporte pode investigar se uma falha foi causada por uma chave de API expirada, saldo insuficiente, restrições de plano, coleção ausente, rota de provedor desativada, configuração de gateway inválida ou problema de esquema de ferramenta. O resultado é uma explicação mais clara: o que falhou, onde provavelmente falhou, quais evidências sustentam essa conclusão e o que o operador deve verificar em seguida. Esse tipo de observabilidade é mais valioso quando o assistente tem permissão para ler o estado relevante da conta, mas não para alterá‑lo automaticamente. Conceda acesso de escrita apenas a fluxos de manutenção confiáveis. ### Meta‑prompting e revisão de conversas O MCP pode suportar fluxos de meta‑prompting onde um assistente revisa conversas anteriores, comportamento de gateway e documentação para sugerir melhorias. O objetivo não é responder novamente ao usuário original; é inspecionar como o agente se comportou e identificar o que pode ser melhorado em prompts, instruções, ferramentas, escolha de modelo ou configuração RAG. Um agente de revisão pode procurar padrões como respostas excessivamente longas, perguntas ausentes, seleção de ferramenta errada, ciclos de clarificação repetidos, suposições inseguras ou respostas que ignoram o contexto recuperado. Em seguida, pode propor mudanças concretas: uma instrução de sistema melhor, uma descrição de ferramenta mais restrita, um esquema de saída estruturada mais forte, um modelo diferente ou uma fonte de recuperação adicional. Isso é útil para equipes que tratam assistentes como produtos. Em vez de ajustar prompts apenas por intuição, elas podem revisar interações reais e transformar os achados em mudanças menores de gateway ou de base de conhecimento. ### Identificar por que modelos falham em situações específicas Algumas falhas de modelo não são causadas apenas pelo modelo. Uma resposta errada pode vir de contexto ausente, prompt fraco, resultado de recuperação ruim, ferramenta indisponível, capacidade de modelo incompatível ou esquema que permite ao modelo gerar saída ambígua. Com o contexto de conta disponível via MCP, um assistente pode investigar essas camadas em conjunto. Ele pode verificar qual modelo foi selecionado, se esse modelo suporta a capacidade necessária, qual configuração de gateway estava ativa, se a coleção RAG relevante existe e qual documentação explica o comportamento esperado. Isso ajuda a responder perguntas como “por que o assistente falha quando usuários perguntam sobre reembolsos?”, “por que este modelo ignora uma ferramenta?” ou “por que as respostas pioram quando a solicitação inclui um arquivo?”. O resultado deve ser uma explicação baseada em evidências e um conserto focado, como mudar o modelo, melhorar a descrição da ferramenta, adicionar material de recuperação ou reescrever a instrução do gateway. ### Melhorar a qualidade do RAG O gerenciamento de conta MCP também é útil para manter sistemas RAG. Um assistente pode inspecionar o comportamento da API de coleções, buscar na documentação AIVAX orientações de recuperação e ajudar a comparar a configuração do gateway com o fluxo de recuperação pretendido. Use-o para investigar recuperação fraca, citações ausentes, trechos irrelevantes, buscas muito amplas, documentos de baixa qualidade ou casos em que um gateway deveria usar uma coleção mas não o faz. Um assistente de manutenção RAG pode sugerir melhor formulação de consultas, mudanças de chunking, organização de coleções, configurações de reranker, ajustes de `top` e `minScore`, ou quando expor uma coleção através do [collection MCP](https://docs.aivax.net/pt-br/docs/mcp-utilities/collections-mcp.md). O melhor fluxo de trabalho é iterativo: inspecionar uma resposta que falhou, identificar qual contexto deveria ter sido recuperado, testar ou revisar o caminho de recuperação, atualizar documentos ou configurações do gateway e, em seguida, re‑verificar o mesmo padrão de conversa. ## Orientação de segurança Trate este servidor MCP como uma integração administrativa. Uma chave privada conectada a ele pode ser capaz de ler ou mutar recursos de conta dependendo das rotas que o agente invoca. Use uma chave de API dedicada para cada cliente ou automação MCP. Rotule-a claramente, defina uma expiração quando possível e rotacione‑a se o cliente for compartilhado, comprometido ou não mais necessário. Armazene a chave no mecanismo de segredos do cliente MCP ou em armazenamento de configuração local, não no controle de versão. Não conecte o gerenciamento de conta MCP a agentes não confiáveis, clientes de chat públicos ou sessões de navegador controladas por usuário. Se um fluxo de trabalho precisar apenas de recuperação de uma coleção RAG, use o [collection MCP](https://docs.aivax.net/pt-br/docs/mcp-utilities/collections-mcp.md) com configuração somente leitura. Se um gateway precisar chamar suas ferramentas externas durante a inferência, configure [MCP functions](https://docs.aivax.net/pt-br/docs/tools/mcp.md) ou [server‑side functions](https://docs.aivax.net/pt-br/docs/tools/protocol-functions.md) em vez disso. --- Source: https://docs.aivax.net/pt-br/docs/mcp-utilities/web-utilities-mcp.html # Utilitários da Web MCP O utilitário da Web MCP expõe as ferramentas de recuperação web da AIVAX para qualquer cliente compatível com MCP. Use-o quando um agente, IDE, assistente de desktop ou ambiente de automação precisar de busca web e obtenção de URLs da AIVAX sem executar essas ferramentas por meio de inferência de modelo da AIVAX. A AIVAX hospeda este servidor MCP e realiza as operações web para a conta autenticada. As ferramentas usam as mesmas respostas, faturamento e limites aplicáveis que suas contrapartes internas. ## Endpoint ```text https://inference.aivax.net/v1/mcp/web-utilities ``` O servidor usa HTTP Streamable. Autentique as solicitações com uma chave de API da conta: ```text Authorization: Bearer ``` Para tipos de chave e opções de autenticação, veja [Autenticação](https://docs.aivax.net/pt-br/docs/authentication.md). ## Exemplo de configuração A forma exata da configuração depende do cliente MCP. O exemplo a seguir habilita ambas as ferramentas: ```json { "servers": { "aivax-web": { "type": "http", "url": "https://inference.aivax.net/v1/mcp/web-utilities", "headers": { "Authorization": "Bearer ", "X-Mcp-Enabled-Tools": "fetch_url, web_search" } } } } ``` Depois que o cliente se conecta, ele pode descobrir e chamar as ferramentas habilitadas através dos métodos padrão do MCP `tools/list` e `tools/call`. ## Selecione quais ferramentas são expostas Use o cabeçalho de solicitação opcional `X-Mcp-Enabled-Tools` para controlar quais ferramentas o servidor expõe ao cliente. Forneça uma lista de permissão separada por vírgulas contendo `fetch_url`, `web_search` ou ambos: ```text X-Mcp-Enabled-Tools: fetch_url ``` ```text X-Mcp-Enabled-Tools: web_search ``` ```text X-Mcp-Enabled-Tools: fetch_url, web_search ``` Os nomes das ferramentas não diferenciam maiúsculas de minúsculas, e os espaços ao redor dos valores separados por vírgulas são ignorados. - Se o cabeçalho for omitido, ambas as ferramentas são expostas. - Se o cabeçalho contiver uma ferramenta reconhecida, apenas essa ferramenta será exposta. - Se o cabeçalho estiver vazio ou não contiver nomes de ferramentas reconhecidas, nenhuma ferramenta será exposta. Como a descoberta de ferramentas pode ser armazenada em cache pelo cliente MCP, reconecte ou atualize o servidor após alterar este cabeçalho. ## Ferramentas ### `fetch_url` Recupera e extrai conteúdo legível de uma ou mais URLs públicas. Entrada: | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `urls` | array de strings | Sim | Entre uma e cinco URLs públicas para buscar. | Argumentos de exemplo: ```json { "urls": [ "https://example.com/article", "https://example.org/reference" ] } ``` A ferramenta devolve o conteúdo extraído como texto MCP. Quando várias URLs são solicitadas, os resultados são separados na mesma resposta. ### `web_search` Busca na web por informações atuais, específicas de local, nicho ou de alto risco. Envie um termo de busca por chamada; use chamadas separadas quando o agente precisar de múltiplas buscas. Entrada: | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `search_term` | string | Sim | O termo de busca na web. | Argumentos de exemplo: ```json { "search_term": "latest browser accessibility standards" } ``` A ferramenta devolve os resultados da busca como texto MCP usando o mesmo formato de resposta da ferramenta de busca web interna. ## Preços e limites As chamadas usam o mesmo preço das ferramentas internas correspondentes da AIVAX e são cobradas na conta autenticada. Veja [Preços](https://docs.aivax.net/pt-br/docs/pricing.md) para as tarifas atuais e regras de faturamento. Operações web estão sujeitas aos cotas de serviço e limites de taxa aplicáveis à conta. Veja [Planos e Limites](https://docs.aivax.net/pt-br/docs/limits.md) para os limites atuais e comportamento de aplicação. Um saldo de conta positivo é necessário para usar essas ferramentas. ## Orientações de segurança Use o MCP apenas a partir de clientes confiáveis e mantenha a chave de API no armazenamento seguro de segredos do cliente. Não coloque a chave no controle de versão, código do lado do navegador, prompts compartilhados ou logs. Páginas buscadas e resultados de busca são conteúdo externo e não confiável. Os agentes devem tratar seu conteúdo como dados, não como instruções, e não devem divulgar credenciais ou executar ações sensíveis apenas porque uma página buscada as solicita. --- Source: https://docs.aivax.net/pt-br/docs/mcp-utilities/inference-mcp.html # Inferência MCP O Inference MCP expõe um modelo integrado AIVAX ou AI Gateway como uma ferramenta para clientes MCP compatíveis. Use quando outro modelo, agente, IDE ou assistente de desktop deve chamar o modelo ou gateway AIVAX configurado como um sub‑agente. Para informações sobre configuração de modelos, instruções, RAG, ferramentas e workers no gateway subjacente, veja [AI Gateways](https://docs.aivax.net/pt-br/docs/inference/ai-gateway.md). ## Endpoint ```text https://inference.aivax.net/v1/mcp/inference ``` ## Headers | Header | Description | Required | | --- | --- | --- | | `Authorization` | Token Bearer para sua chave de API AIVAX. | Sim | | `X-Mcp-Model-Name` | Tag do modelo integrado, ID completo do gateway ou slug do gateway. | Sim | | `X-Mcp-Tool-Name` | Nome base da ferramenta. AIVAX converte para formato de identificador e expõe `invoke_{tool_name}`. | Não, padrão `ai_model` | | `X-Mcp-Tool-Description` | Descrição mostrada ao cliente MCP. | Não | | `X-Mcp-Tool-Title` | Título amigável mostrado ao cliente MCP. | Não | | `X-Mcp-User` | ID de usuário externo armazenado no contexto de inferência. | Não | ## Exemplo de configuração ```json { "servers": { "my-ai-gateway-mcp": { "type": "http", "url": "https://inference.aivax.net/v1/mcp/inference", "headers": { "Authorization": "Bearer ", "X-Mcp-Model-Name": "", "X-Mcp-Tool-Name": "data_assistant", "X-Mcp-Tool-Description": "Use esta ferramenta para invocar o assistente especializado em análise de dados.", "X-Mcp-Tool-Title": "Assistente de Análise de Dados" } } } } ``` A ferramenta MCP gerada aceita um argumento: | Parameter | Type | Description | | --- | --- | --- | | `prompt` | string | Prompt enviado ao modelo ou gateway configurado. | A ferramenta MCP retorna a resposta do gateway como texto e compartilha o mesmo caminho de faturamento e limite de taxa de inferência da conclusão de chat subjacente. --- Source: https://docs.aivax.net/pt-br/docs/legal/privacy-policy.html # Política de Privacidade Revisão: 1.4 Data de vigência: 1 de agosto de 2026 Atualização anterior: 20 de julho de 2026 Última atualização: 26 de setembro de 2026 --- Bem‑vindo à AIVAX. Esta Política de Privacidade descreve como a AIVAX coleta, usa, armazena, compartilha e protege informações em seus serviços de inferência de IA. Foi escrita para transparência e clareza técnica, e não constitui aconselhamento jurídico. Gerentes de Conta devem revisá‑la com seu próprio assessor jurídico quando necessário. Ao usar os serviços da AIVAX, o Gerente de Conta reconhece e concorda com os termos desta política. ### 1. Definições - **AIVAX:** Empresa que fornece a plataforma e serviços de orquestração de modelos de IA. - **AIVAX Account Manager ("Account Manager"):** Pessoa física ou jurídica que cria e administra a conta e integra a API. - **End User:** Indivíduo que interage com a aplicação do Gerente de Conta que consome a API AIVAX. - **Account Data:** Dados de registro e administrativos, como nome, e‑mail, empresa, função, identificadores internos, preferências e configurações de chave de API. - **Billing Data:** Dados necessários para faturas, recibos, saldo da conta, créditos, eventos de pagamento e processamento de pagamento por processadores terceirizados. - **Inference Data:** Entradas enviadas aos modelos e saídas resultantes. Nos Termos de Uso, isso corresponde a Conteúdo de Entrada e Conteúdo Gerado. - **Semantic Training Data:** Dados de treinamento semântico: conteúdo RAG e de reclassificação elegíveis anonimizado coletado após o Gerente de Conta habilitar a coleta de dados semânticos, conforme descrito em [Data Collecting](https://docs.aivax.net/pt-br/docs/data-collecting.md). Indexação e armazenamento de documentos são excluídos. - **Conversations:** Sequências armazenadas de interações de inferência, incluindo mensagens, metadados, nome do modelo, objeto de uso, ferramentas, recursos e informações de erro quando o registro de conversas está habilitado. - **Technical Metadata:** Registros de inferência e acesso, endereços IP ou informações de encaminhamento, strings de agente de usuário, carimbos de tempo, latência, identificadores de sessão, uso de tokens, códigos de resposta, identificadores de solicitação e sinais de segurança ou abuso. - **Processor:** Processador: AIVAX quando processa dados de acordo com as instruções do Gerente de Conta. - **Controller:** Controlador: AIVAX quando define finalidades para dados de conta, faturamento, segurança e conformidade. - **Subprocessor:** Subprocessador: Terceiro contratado ou configurado pela AIVAX para apoiar o processamento, como infraestrutura, e‑mail, faturamento, provedores de modelo, provedores de busca ou armazenamento de objetos. --- ### 2. Funções de Processamento | Tipo de Dados | Função AIVAX | Função do Gerente de Conta | | --- | --- | --- | | Account Data | Controlador | Titular dos dados ou controlador de seu próprio relacionamento interno | | Billing Data | Controlador para fins legais, contratuais e operacionais de faturamento | Fornece e verifica | | Inference Data / Conversations | Processador para processamento direcionado ao cliente; Controlador para segurança, prevenção de abuso e logs operacionais quando aplicável | Controlador de conteúdo e finalidade | | Semantic Training Data | Controlador para desenvolvimento de modelo e sistema semântico com base no consentimento do Gerente de Conta | Controlador do conteúdo original e responsável pela base legal e avisos necessários aos usuários finais | | Technical Metadata | Controlador para segurança, confiabilidade, prevenção de abuso e operações da plataforma; Processador quando gerado como parte da execução do serviço | Controlador do contexto da aplicação de origem | Ao atuar como Processador, a AIVAX segue as instruções do Gerente de Conta expressas por meio de chamadas de API, configurações do painel, seleção de modelo e integrações configuradas. Para consistência contratual, Dados de Inferência nesta política correspondem a Conteúdo de Entrada e Conteúdo Gerado nos Termos de Uso. --- ### 3. Categorias de Dados Coletados 1. **Fornecido diretamente pelo Gerente de Conta:** Dados da Conta, preferências, configurações da conta, informações da organização, chaves de API geradas e credenciais armazenadas como hashes ou tokens quando aplicável. 2. **Gerado pelo uso:** Metadados técnicos, registros de uso, contagem de tokens, latência, uso do modelo, recursos de solicitação, informações de erro e eventos de faturamento. 3. **Dados de Inferência e Conversas:** Texto e outros conteúdos enviados aos modelos e as saídas dos modelos são processados para executar solicitações. O conteúdo da conversa e o histórico de mensagens são coletados e registrados apenas quando o Gerente de Conta habilita o recurso de observabilidade (“Conversas”) para a solicitação ou globalmente para a conta, conforme descrito na Seção 5. 4. **Dados de Treinamento Semântico:** Termos de consulta RAG anonimizados, conteúdos e pontuações de relevância de documentos retornados por uma busca, reclassificador selecionado, consultas de reclassificação, documentos enviados e resultados de classificação coletados enquanto a coleta de dados semânticos está habilitada. Indexação e armazenamento de documentos não são coletados. Esses registros anonimados excluem identificadores de conta, chave de API, solicitação, coleção e documento, nomes de documentos, dados de faturamento e carimbos de tempo da coleta. 5. **Suporte e Comunicação:** Mensagens de tíquetes, e‑mails enviados ao suporte ou canais de contato e comunicações operacionais. 6. **Faturamento:** Dados fiscais, de pagamento, fatura, crédito, saldo da conta, intenção de pagamento e webhook de pagamento. 7. **Dados Agregados ou Anonimizados:** Métricas derivadas que não identificam o Gerente de Conta ou os usuários finais. A AIVAX não exige categorias especiais de dados pessoais sensíveis. Se o Gerente de Conta enviar dados pessoais sensíveis em Dados de Inferência, ele será responsável por possuir a base legal e os avisos adequados. --- ### 4. Finalidades, Bases Legais e Retenção | Categoria | Finalidade Primária | Base Legal (LGPD) | Retenção Técnica ou Limite | | --- | --- | --- | --- | | Account Data | Criação de conta, autenticação, gerenciamento de conta, comunicações operacionais | Execução de contrato / interesse legítimo | Enquanto a conta estiver ativa; contas desativadas ou inativas podem ser excluídas por limpeza programada conforme regras da plataforma | | Billing Data | Faturas, créditos, confirmação de pagamento, prevenção de fraude, registros fiscais e contábeis | Obrigações legais / execução de contrato | De acordo com exigências legais, contábeis e contratuais | | Technical Metadata | Segurança, prevenção de abuso, depuração, confiabilidade, limitação de taxa, contabilização de custos | Interesse legítimo / execução de contrato | Registros de inferência e acesso e metadados, incluindo endereços IP e strings de agente de usuário, são retidos por até 1 ano | | Inference Data | Execução da inferência solicitada e integrações configuradas | Execução de contrato | Processado para a solicitação e pode ser armazenado em Conversas quando o registro de conversas está habilitado | | Semantic Training Data | Desenvolver, treinar, ajustar, avaliar, testar e melhorar modelos e sistemas de recuperação ou classificação semântica | Consentimento | Retido em forma anonimizada enquanto razoavelmente necessário para essas finalidades, obrigações legais, segurança e auditorias; depois excluído | | Conversations | Monitoramento, suporte, exportação, depuração, revisão de uso e histórico visível ao usuário | Interesse legítimo / execução de contrato | Visível/exportável conforme retenção do plano: Gratuito até 2 horas, Pro até 2 dias, Max até 30 dias | | Support | Resolver dúvidas, incidentes e solicitações de conformidade | Execução de contrato / interesse legítimo | Retido conforme necessário para resolver a solicitação e manter registros comerciais | | Aggregated or Anonymized Data | Planejamento de capacidade, confiabilidade, prevenção de abuso, melhoria de serviço | Fora do escopo da LGPD quando anonimizado irreversivelmente | Indeterminado enquanto anonimizado | Os períodos de exportação de conversas são 2 horas, 1 dia, 7 dias e 30 dias, limitados pelo período de retenção do plano da conta. --- ### 5. Registro e Exclusão de Conversas A AIVAX coleta e registra conversas apenas quando o Gerente de Conta habilita o recurso de observabilidade (“Conversas”), seja para a solicitação individual ou globalmente para a conta. Se não estiver habilitado para a solicitação ou por meio da configuração global da conta, a AIVAX não coleta, registra nem armazena o conteúdo da conversa dessa solicitação. Processar entradas e saídas para executar inferência não cria um registro de conversa armazenado. A AIVAX não pode recuperar ou fornecer conversas que não foram coletadas porque esse recurso não foi habilitado, inclusive em resposta a ordem judicial. Logs técnicos e metadados descritos na Seção 4 são independentes do conteúdo da conversa. A divulgação de conversas armazenadas às autoridades está sujeita aos requisitos de ordem judicial na Seção 7.1. O Gerente de Conta autenticado pode listar, visualizar, exportar e excluir conversas armazenadas por meio da API de conversas, sujeito a autorizações e janelas de retenção. Excluir uma conversa remove o registro correspondente para aquela conta do armazenamento de produção. --- ### 6. RAG, Memórias e Armazenamento A AIVAX pode armazenar coleções RAG, documentos, embeddings, metadados de documentos, memórias de usuário, descrições de mídia, dados de sessão de chat web e arquivos de workspace de shell quando esses recursos são usados. A contagem de armazenamento atual inclui: - Texto de documentos RAG e bytes de embedding. - Informações persistentes do usuário. - Descrições de mídia. - Mensagens de sessão de chat web, contexto extra e metadados. - Arquivos de shell da conta. As cotas de armazenamento são baseadas no plano. O armazenamento incluído atual é 30 MB para Gratuito, 2 GB para Pro e 20 GB para Max. --- ### 7. Coleta Opcional de Dados Semânticos e Treinamento de Modelo Por padrão, a AIVAX não usa Dados de Inferência ou Conversas do Gerente de Conta para treinar modelos proprietários da AIVAX. Quando um Gerente de Conta autorizado habilita a coleta de dados semânticos, a AIVAX pode usar registros RAG e de reclassificação anonimados elegíveis gerados enquanto a configuração está habilitada para os fins descritos em [Data Collecting](https://docs.aivax.net/pt-br/docs/data-collecting.md). Indexação e armazenamento de documentos RAG não são incluídos e não recebem desconto no programa. Antes do armazenamento, a AIVAX anonimiza esses registros removendo o relacionamento da conta e excluindo identificadores operacionais, nomes de documentos, dados de faturamento e carimbos de tempo da coleta. A conta é consultada apenas para verificar o consentimento e aplicar o desconto elegível. A AIVAX não retém um mapeamento conta‑para‑registro. A configuração está desabilitada por padrão. Desabilitá‑la interrompe a nova coleta, mas não exclui automaticamente os registros coletados enquanto o consentimento estava ativo nem reverte o treinamento já concluído. Como os mapeamentos conta‑para‑registro não são armazenados, a AIVAX não pode localizar um registro de treinamento apenas pelo ID da conta. O Gerente de Conta continua responsável pela base legal, avisos e permissões necessários para os dados pessoais enviados por seus usuários finais. Solicitações relacionadas a dados pessoais presentes em conteúdo semântico podem ser enviadas para **privacy@aivax.net** ou **wm@aivax.net** com informações suficientes para localizar o conteúdo quando aplicável. Provedores de modelo e agregadores terceirizados podem ter seus próprios termos de processamento, prazos de retenção e políticas de melhoria de modelo, independentes deste programa opcional. O Gerente de Conta deve revisar a política do provedor selecionado antes de enviar dados pessoais ou sensíveis. --- ### 7.1. Ordens Judiciais e Solicitações de Autoridades Estrangeiras Para divulgação judicial de dados de conta, a AIVAX executa apenas ordens emitidas por tribunais brasileiros competentes. Ordens emitidas em outros países devem ser submetidas através dos tribunais brasileiros e resultar em uma ordem judicial brasileira antes que a AIVAX divulgue dados. Uma ordem estrangeira por si só não autoriza a divulgação. Autoridades judiciais estrangeiras podem solicitar a preservação de logs existentes por até 1 ano enquanto conduzem os processos aplicáveis através dos tribunais brasileiros. A preservação não é divulgação e não autoriza a coleta ou reconstrução de conteúdo de conversa que não foi registrado. Para cumprir uma ordem judicial brasileira, a AIVAX pode fornecer os seguintes dados, limitados ao escopo da ordem e aos registros realmente disponíveis: - **Logs e metadados técnicos:** Até 1 ano de registros de inferência e acesso e metadados, incluindo endereços IP e strings de agente de usuário. Esses registros não implicam que o conteúdo da conversa foi coletado. - **Conversas armazenadas:** Apenas conversas coletadas enquanto o Gerente de Conta havia habilitado “Conversas” para a solicitação ou globalmente para a conta, e que permanecem disponíveis. A AIVAX fornece essas conversas às autoridades somente sob ordem judicial brasileira; não pode fornecer conversas que nunca foram coletadas. - **Outras informações da conta e recursos armazenados:** Informações da conta, memórias de usuário, gateways de IA e suas configurações, coleções e documentos RAG e outros recursos de conta armazenados. Registros disponíveis podem incluir backups com até 3 meses, conforme descrito na Seção 21. Esses períodos descrevem os limites da retenção disponível, não uma garantia de que todo registro exista durante todo o período. Uma solicitação de preservação não restaura registros que nunca foram coletados ou que não estão mais disponíveis. --- ### 8. Direitos do Titular dos Dados (Art. 18, LGPD) Quando a AIVAX atua como Controlador, os titulares dos dados podem solicitar confirmação de tratamento, acesso, correção, anonimização, bloqueio ou exclusão, portabilidade, informações sobre compartilhamento, revogação de consentimento quando aplicável, oposição ao tratamento baseado em interesse legítimo e revisão de decisões automatizadas quando aplicável. Canal: **privacy@aivax.net** ou **wm@aivax.net** (Encarregado de Proteção de Dados). Podemos solicitar verificação de identidade. Para dados em que a AIVAX atua como Processador, a AIVAX pode direcionar o titular ao Gerente de Conta Controlador. --- ### 9. Encarregado de Proteção de Dados (DPO) Encarregado de Proteção de Dados (Art. 41): **(Identidade anonimizada)** Contato: **wm@aivax.net** Funções incluem comunicação com titulares e a ANPD, orientação interna de conformidade e apoio a avaliações de impacto de privacidade. --- ### 10. Subprocessadores e Provedores Terceirizados A AIVAX utiliza serviços terceirizados para infraestrutura, armazenamento de objetos, e‑mail transacional, faturamento, busca na web, geração de imagens, reclassificação e inferência de modelo de IA. A lista técnica atual é mantida em [Data Processors](https://docs.aivax.net/pt-br/docs/legal/third-party-processors.md). Ao selecionar um modelo ou habilitar uma ferramenta, o Gerente de Conta pode fazer com que o conteúdo seja enviado ao provedor de modelo, agregador ou provedor de ferramenta selecionado. A AIVAX não controla as políticas de terceiros e recomenda revisão prévia. --- ### 11. Transferências Internacionais de Dados Os dados podem ser processados ou armazenados fora do Brasil dependendo da infraestrutura, provedor de modelo, provedor de busca, provedor de armazenamento de objetos ou provedor de pagamento selecionados. A AIVAX aplica salvaguardas técnicas e contratuais adequadas ao serviço, incluindo controles de acesso, criptografia em trânsito, minimização e segregação lógica quando aplicável. --- ### 12. Segurança da Informação - Criptografia em trânsito com HTTPS/TLS. - Autenticação de chave de API e autorização escopo de conta. - Acesso administrativo baseado em funções. - Limitação de taxa para inferência, busca RAG, inserção de documentos, ferramentas e operações de pagamento. - Verificações de saldo, saldo mínimo e cota de armazenamento antes de operações que geram custos. - Logs operacionais e relatórios de erro para solução de problemas e prevenção de abuso. - Separação entre recursos de propriedade da conta, como coleções, documentos, conversas, memórias e arquivos de shell. - Configuração segura de credenciais por parâmetros de inicialização da aplicação ao invés de segredos codificados. Nenhuma medida de segurança é absoluta; a AIVAX mantém um processo de melhoria contínua. --- ### 13. Gestão de Incidentes Incidentes de segurança relevantes são avaliados com base no impacto, natureza dos dados e risco para os titulares. Quando necessário, a AIVAX notificará os Gerentes de Conta afetados e as autoridades competentes com as informações disponíveis sobre o evento, categorias de dados afetadas, medidas de mitigação e ações recomendadas. --- ### 14. Decisões Automatizadas A AIVAX usa automação para limitação de taxa, verificações de saldo, verificações de cota de armazenamento, prevenção de abuso, prevenção de fraude, indexação, roteamento e monitoramento operacional. Essas automações podem restringir temporariamente solicitações ou chaves. O Gerente de Conta pode solicitar revisão por meio dos canais de suporte. --- ### 15. Cookies e Tecnologias de Rastreamento Interfaces do painel podem usar cookies estritamente necessários ou armazenamento equivalente no navegador para sessões, autenticação e preferências. A AIVAX não usa cookies de publicidade comportamental no fluxo de plataforma documentado. --- ### 16. Crianças, Adolescentes e Menores Emancipados Os serviços não são destinados a pessoas menores de 18 anos, exceto menores emancidados legalmente com 16 anos ou mais conforme a lei brasileira. O Gerente de Conta é responsável por implementar verificações adequadas quando seu caso de uso puder envolver menores. --- ### 17. Dados Sensíveis A AIVAX não exige dados sensíveis para usar a plataforma. O Gerente de Conta deve evitar enviar dados de saúde, biométricos, genéticos, crenças religiosas, opiniões políticas ou outros dados sensíveis, a menos que possua a base legal adequada e avisos claros para os titulares. --- ### 18. Limitações de Uso e Conteúdo Proibido É proibido usar a plataforma para armazenar ou processar conteúdo ilegal, material que viole direitos, malware, material difamatório ou conteúdo que infrinja direitos de terceiros. A AIVAX pode suspender, restringir ou bloquear chaves ao suspeitar razoavelmente de violação, preservando logs necessários para investigação. --- ### 19. Dados Agregados A AIVAX pode gerar estatísticas agregadas como volume de tokens, taxa de erro, distribuição de modelos, uso de armazenamento e latência. Estatísticas agregadas são usadas para planejamento de capacidade, confiabilidade, faturamento e prevenção de abuso. --- ### 20. Exportação e Portabilidade A AIVAX fornece APIs para exportar histórico de conversas em JSON ou JSONL dentro da janela de retenção configurada. Documentos de coleta podem ser exportados em formato JSONL. A disponibilidade de exportação está sujeita à autenticação, autorização, retenção e estado da conta. --- ### 21. Backups e Recuperação de Desastres A AIVAX mantém backups para continuidade operacional e recuperação de desastres, com cópias históricas de até 3 meses. Esses backups podem conter informações da conta e recursos armazenados, incluindo memórias de usuário, gateways de IA e coleções e documentos RAG. Dados de produção excluídos podem permanecer em backups dentro desse período até que a rotação de backups seja concluída. Dados de backup disponíveis podem ser fornecidos para cumprir uma ordem judicial brasileira sob a Seção 7.1. Backups não contêm conversas que nunca foram coletadas porque “Conversas” não foi habilitado. --- ### 22. Alterações a Esta Política Alterações materiais podem ser notificadas por e‑mail, aviso no painel ou publicação de política atualizada. O uso continuado após a data de vigência constitui aceitação onde permitido por lei e contrato. --- ### 23. Canal de Contato e Reclamações Dúvidas, solicitações de direitos ou reclamações: **privacy@aivax.net** / **wm@aivax.net**. Se insatisfeito, o titular pode recorrer à **ANPD** (Autoridade Nacional de Proteção de Dados). --- ### 24. Histórico de Revisões | Versão | Data de Vigência | Principais Alterações | | --- | --- | --- | | 1.0 | 30/07/2025 | Versão inicial publicada | | 1.1 | 05/10/2025 | Adicionadas bases legais, direitos, retenção detalhada, subprocessadores, transferências, segurança expandida, incidentes, decisões automatizadas, cookies, dados sensíveis, versionamento | --- ### 25. Contato Geral Legal / Privacidade: **legal@aivax.net** Encarregado de Proteção de Dados: **wm@aivax.net** Sempre use canais oficiais para evitar engenharia social. --- ### 26. Disposições Finais Se qualquer cláusula desta política for considerada inválida, as demais disposições permanecem em pleno vigor. Em caso de conflito entre esta política e termos específicos de produto, a disposição mais protetiva para os titulares prevalecerá, salvo obrigação legal diferente. > Observação: Esta política pode ser complementada por um Acordo de Processamento de Dados (DPA) específico entre a AIVAX e o Gerente de Conta, quando aplicável. --- Source: https://docs.aivax.net/pt-br/docs/legal/terms-of-service.html # Termos de Uso Revisão: 1.4 Data de vigência: 1 de agosto de 2026 Atualização anterior: 20 de julho de 2026 Última atualização: 26 de setembro de 2026 --- Bem‑vindo à AIVAX. Estes Termos de Uso ("Termos") regulamentam seu acesso e uso de nossos serviços de inferência de IA, APIs, site e quaisquer softwares associados (coletivamente, os "Serviços"). Estes Termos não constituem aconselhamento jurídico. Ao criar uma conta, acessar ou usar nossos Serviços, você ("Gerente de Conta AIVAX") concorda em ficar vinculado a estes Termos e à nossa [Política de Privacidade](https://docs.aivax.net/pt-br/docs/legal/privacy-policy.md). Se você não concordar com estes Termos, não use nossos Serviços. ### 1. Definições - **AIVAX:** A empresa que fornece os Serviços. - **Gerente de Conta AIVAX:** A pessoa física ou jurídica que cria e gerencia uma conta na plataforma AIVAX e aceita estes Termos. - **Conteúdo de Entrada:** Dados, texto, prompts, arquivos, mensagens, metadados ou qualquer outra informação que o Gerente de Conta AIVAX envia aos Serviços para processamento. - **Conteúdo Gerado:** Respostas, texto, imagens, arquivos ou quaisquer outros dados gerados por modelos de IA ou ferramentas da plataforma como resultado do processamento do Conteúdo de Entrada. - **Conversas:** Sequências armazenadas de Conteúdo de Entrada, Conteúdo Gerado, metadados, informações do modelo, dados de uso, ferramentas e informações técnicas relacionadas quando o registro de conversas está habilitado. - **Dados RAG:** Coleções, documentos, metadados de documentos, referências, tags e vetores de incoro armazenados para geração aumentada por recuperação. - **Dados de Treinamento Semânticos:** Conteúdo RAG e de reclassificação anonimizado elegível coletado após o Gerente de Conta AIVAX habilitar a coleta de dados semânticos, conforme descrito em [Coleta de Dados](https://docs.aivax.net/pt-br/docs/data-collecting.md). Indexação e armazenamento de documentos são excluídos. Na Política de Privacidade, "Dados de Inferência" cobre conjuntamente Conteúdo de Entrada e Conteúdo Gerado. --- ### 2. Uso dos Serviços e Responsabilidades #### 2.1. Uso Responsável e Conduta Você concorda em usar os Serviços da AIVAX de forma ética e responsável. É proibido: - Abusar, interferir, interromper, sobrecarregar ou prejudicar os Serviços, servidores, redes ou integrações de terceiros. - Tentar contornar autenticação, autorização, limites de taxa, controles de faturamento, cotas de armazenamento ou controles de segurança. - Investigar, explorar ou divulgar vulnerabilidades sem autorização. - Usar os Serviços para assediar, ameaçar, difamar, enganar ou violar os direitos e a dignidade de terceiros. - Armazenar, gerar ou distribuir conteúdo ilegal, malware ou material que infrinja direitos. #### 2.2. Conformidade Legal Você é o único responsável por garantir que seu uso dos Serviços esteja em conformidade com todas as leis e regulamentos aplicáveis, incluindo a legislação brasileira, obrigações internacionais que se a ao seu caso de uso, regras de propriedade intelectual, normas de privacidade e regras setoriais específicas. Seu uso deve respeitar os princípios estabelecidos pelo Marco Civil da Internet (Lei nº 12.965/2014) e pela Lei Geral de Proteção de Dados (LGPD - Lei nº 13.709/2018), quando aplicável. #### 2.3. Dados Pessoais O Gerente de Conta AIVAX é o controlador dos dados inseridos nos Serviços. Se o Conteúdo de Entrada incluir dados pessoais de terceiros, você declara que: - Possui a base legal adequada para coletar, processar e enviar esses dados à AIVAX para a finalidade configurada. - É responsável por avisos, consentimentos quando necessários, solicitações de titulares, escolhas de retenção e uso subsequente do Conteúdo Gerado. - A AIVAX atua como processadora para o processamento de inferência direcionado ao cliente, sujeito à Política de Privacidade e aos acordos aplicáveis. #### 2.4. Elegibilidade Para usar os serviços da AIVAX, você deve ser legalmente capaz, ter pelo menos 18 anos, ou 16 anos se emancipado legalmente conforme a lei brasileira. Ao usar nossos serviços, você declara que: - Não foi previamente suspenso, removido ou banido dos Serviços; - Sua conta está vinculada a pessoa ou organização em conformidade com as leis e obrigações de conta aplicáveis; - Atende aos requisitos mínimos de idade e capacidade. Se você usar os Serviços em nome de outra pessoa, organização ou empresa, declara que tem autoridade para vincular essa entidade a estes Termos. #### 2.5. Saldo, Créditos, Armazenamento e Reembolsos A maioria dos serviços da AIVAX requer saldo pré‑pago ("créditos"). Operações que geram custos podem ser bloqueadas quando o saldo da conta é zero ou negativo, quando a conta não possui o saldo mínimo exigido para um recurso, ou quando o uso de armazenamento ultrapassa a cota do plano. A plataforma atual aplica cotas de armazenamento baseadas em plano a recursos armazenados, como documentos e embeddings RAG, memórias de usuário, descrições de mídia, dados de sessões de chat web e arquivos de shell. O armazenamento incluído atualmente é de 30 MB para o plano Free, 2 GB para o Pro e 20 GB para o Max. Provedores de pagamento podem coletar e processar informações de faturamento e pagamento necessárias para adicionar créditos. Os fluxos de pagamento da AIVAX atualmente incluem InfinitePay para criação de faturas, e a plataforma também contém suporte a webhooks Stripe para tratamento de eventos de pagamento. Antes de pagar pelos créditos, você pode visualizar as taxas aplicáveis e recusar o pagamento antes da adição ao saldo. Créditos adicionados expiram um ano após a adição. Crédito expirado não conta mais para o saldo da sua conta. **Política de Reembolso:** De acordo com o Art. 49 do Código de Defesa do Consumidor (Lei nº 8.078/1990), você pode exercer o direito de arrependimento dentro de 7 (dias) corridos a partir da data de adição do saldo, solicitando reembolso via legal@aivax.net. Do valor reembolsável, podem ser deduzidos: - custos correspondentes a serviços de computação, inferência, processamento, dados RAG, vetores, memórias, armazenamento ou outros recursos efetivamente consumidos até o momento da solicitação; - taxas não reembolsáveis do provedor de pagamento. O reembolso será processado usando o mesmo método de pagamento em até 15 (dias) úteis após a aprovação. O saldo restante da conta pode ser deduzido ou zerado. **Interrupção de serviço por saldo ou armazenamento insuficiente:** A plataforma pode negar novas solicitações que gerem custos quando a conta tem saldo insuficiente ou ultrapassa a cota de armazenamento. Você é responsável por exportar ou excluir dados armazenados conforme necessário e por manter saldo e cota suficientes para a operação contínua do serviço. --- ### 3. Conteúdo Gerado e Propriedade Intelectual #### 3.1. Propriedade e Responsabilidade pelo Conteúdo Gerado Sujeito a estes Termos, a AIVAX concede a você todos os direitos, título e interesse que possa ter sobre o Conteúdo Gerado. Em outras palavras: o que você cria é seu, sujeito à lei aplicável e aos direitos de terceiros. Você é o único responsável pelo Conteúdo Gerado e seu uso subsequente, incluindo legalidade, precisão, adequação e possíveis infrações a direitos de terceiros. A AIVAX não se responsabiliza por como você usa o Conteúdo Gerado. **Não exclusividade e semelhança:** Devido à natureza estatística dos modelos de IA, conteúdo semelhante pode ser gerado para usuários diferentes sem acesso cruzado aos inputs originais. A AIVAX não garante exclusividade absoluta de expressões ou ideias geradas pelos modelos. Você não adquire direitos sobre pesos de modelo, prompts internos, técnicas, código da plataforma ou segredos comerciais da AIVAX. **Licença limitada concedida à AIVAX:** Ao enviar Conteúdo de Entrada, você concede à AIVAX uma licença mundial, não exclusiva e livre de royalties limitada ao que é necessário para processar inferências, fornecer ferramentas e integrações configuradas, manter logs técnicos e de segurança, detectar abusos, calcular faturamento e cumprir obrigações legais. Esta licença está sujeita aos limites de coleta, retenção e divulgação judicial de conversas na Seção 3.4 e à Política de Privacidade; não autoriza o registro de conversas quando "Conversas" não está habilitado. Por padrão, a AIVAX não usa Conteúdo de Entrada ou Conteúdo Gerado para treinar modelos próprios da AIVAX. O programa opcional de coleta de dados semânticos descrito abaixo é a exceção a essa regra padrão. **Setores de alto risco:** O Conteúdo Gerado não deve ser usado como base única para decisões médicas, legais, financeiras, de engenharia de segurança crítica ou outras decisões de alto risco sem validação humana qualificada. #### 3.2. Coleta Opcional de Dados Semânticos Quando um Gerente de Conta autorizado habilita a coleta de dados semânticos, o Gerente de Conta: - autoriza a AIVAX a coletar registros RAG e de reclassificação anonimizado elegíveis gerados enquanto a configuração está habilitada; - concede à AIVAX uma licença mundial, não exclusiva e livre de royalties para armazenar, reproduzir, transformar, anotar, combinar, analisar e usar Dados de Treinamento Semânticos para desenvolver, treinar, ajustar, avaliar, testar e melhorar modelos e sistemas relacionados a embeddings, recuperação, classificação, reclassificação e outros processamentos semânticos; - declara que possui a autoridade, base legal, avisos e permissões necessários para esse uso, inclusive para dados pessoais submetidos por usuários finais; e - reconhece que operações RAG e de reclassificação elegíveis recebem o desconto documentado de 10 %, enquanto indexação de documentos, armazenamento e serviços não relacionados permanecem com seus preços regulares. A AIVAX anonimiza esses registros antes do armazenamento, removendo a relação da conta e excluindo identificadores operacionais, nomes de documentos, dados de faturamento e timestamps de coleta. A configuração está desabilitada por padrão. Desativá‑la tem efeito prospectivo: interrompe nova coleta e encerra o desconto para operações elegíveis futuras, mas não exclui automaticamente registros já coletados nem exige que a AIVAX reverta treinamentos concluídos. Como a AIVAX não mantém um mapeamento conta‑registro, os registros não podem ser localizados ou excluídos seletivamente apenas pelo ID da conta. Solicitações de exclusão permanecem sujeitas à Política de Privacidade e à lei aplicável. Os termos operacionais completos estão documentados em [Coleta de Dados](https://docs.aivax.net/pt-br/docs/data-collecting.md). #### 3.3. Conteúdo Adulto, Explícito e Sensível A AIVAX é uma ferramenta que pode ser usada para gerar diversos tipos de conteúdo. Conteúdo adulto ou explícito é permitido apenas quando todas as condições a seguir são atendidas: 1. Você assume total responsabilidade por criar, armazenar e distribuir o material. 2. O material não viola nenhuma lei aplicável, com tolerância zero para conteúdo envolvendo exploração infantil, conteúdo sexual não consensual, violência não consensual ou abuso ilegal. 3. Se o material envolver representações de pessoas reais, você tem consentimento explícito e verificável dessas pessoas. 4. Você implementa seus próprios mecanismos de controle de acesso e verificação de idade se disponibilizar esse conteúdo a terceiros. A AIVAX não endossa esse tipo de conteúdo e pode investigar ou suspender contas que violem essas condições. #### 3.4. Registro de Conversas, Retenção e Divulgação Judicial A AIVAX coleta e registra o conteúdo de conversas somente quando o Gerente de Conta habilita o recurso de observabilidade ("Conversas") para a solicitação individual ou globalmente para a conta. Se nenhum habilitar o registro para a solicitação, seu conteúdo de conversa não é coletado, registrado ou armazenado. Processar Conteúdo de Entrada e Conteúdo Gerado para executar uma solicitação não cria um registro de conversa armazenado. A AIVAX não pode recuperar ou fornecer conversas que nunca foram coletadas, mesmo sob ordem judicial. Logs técnicos e metadados são separados do conteúdo de conversa. A AIVAX retém logs de inferência e acesso e metadados, incluindo endereços IP e strings de agente de usuário, por até 1 ano. Informações de conta e recursos armazenados, incluindo memórias de usuário, gateways de IA e suas configurações, e coleções e documentos RAG, podem permanecer em backups de até 3 meses. Esses períodos não garantem que todo registro permaneça disponível; a retenção de conversas e outros limites aplicáveis são descritos na [Política de Privacidade](https://docs.aivax.net/pt-br/docs/legal/privacy-policy.md). Para divulgação judicial de dados de conta, a AIVAX executa somente ordens emitidas por tribunais brasileiros competentes. Ordens de outros países devem ser submetidas através de tribunais brasileiros e resultar em ordem judicial brasileira antes que os dados sejam divulgados. Autoridades judiciais estrangeiras podem solicitar a preservação de logs existentes por até 1 ano enquanto conduzem esses processos. A preservação por si só não autoriza a divulgação, restauração de registros indisponíveis ou coleta de conteúdo de conversa que não foi registrado. Sob ordem judicial brasileira, a AIVAX pode fornecer logs e metadados disponíveis, conversas armazenadas e outras informações e recursos de conta, incluindo dados de backup disponíveis, limitados ao escopo da ordem. Conversas armazenadas são fornecidas às autoridades apenas sob tal ordem. Consulte a Seção 7.1 da Política de Privacidade para as regras de divulgação e a Seção 21 para backups. --- ### 4. Provedores de Modelos de Terceiros, Ferramentas e BYOK #### 4.1. Traga Sua Própria Chave (BYOK) A AIVAX pode oferecer funcionalidade BYOK (Bring Your Own Key), permitindo que você use suas próprias chaves de API de provedores externos para inferência ou serviços relacionados. Ao usar BYOK, você concorda que: - Você é responsável por obter, armazenar, rotacionar e usar suas próprias chaves de provedor. - A AIVAX não tem controle sobre as políticas, limites de uso, banimentos, suspensões, preços ou termos do provedor original. - Se sua chave externa for bloqueada, revogada, limitada por taxa ou esgotada, os Serviços que dependem dela podem falhar. - Serviços periféricos da AIVAX, incluindo armazenamento, processamento RAG, gerenciamento de vetores, memórias de usuário, orquestração de agentes e ferramentas auxiliares, podem continuar sendo cobrados contra seu saldo AIVAX de acordo com a precificação atual. - BYOK não o exime destes Termos, da conformidade legal, regras de abuso ou políticas de uso aceitável. #### 4.2. Modelos e Ferramentas de Terceiros Fornecidos pela AIVAX Os Serviços da AIVAX podem encaminhar Conteúdo de Entrada para modelos de IA, reclassificadores, provedores de busca, provedores de geração de imagens, provedores de pagamento, provedores de armazenamento de objetos, provedores de mensagens ou outros processadores. O provedor específico depende do modelo selecionado, provedor configurado, ferramenta, gateway ou integração. Ao usar um modelo, provedor ou ferramenta específicos, você também pode estar sujeito aos termos desse provedor. Você é responsável por revisar a adequação do provedor antes de enviar dados pessoais, confidenciais, regulados ou sensíveis. --- ### 5. Suspensão e Rescisão A AIVAX pode suspender, restringir, encerrar ou banir o acesso aos Serviços por violações destes Termos, riscos de segurança, exigências legais, não pagamento repetido, abuso, fraude ou risco à plataforma ou a terceiros. Suspensões podem ser temporárias ou permanentes, dependendo da gravidade do problema. --- ### 6. Limitação de Responsabilidade e Isenção de Garantias OS SERVIÇOS SÃO FORNECIDOS "NO ESTADO EM QUE ESTÃO" E "COM DISPONIBILIDADE", SEM GARANTIAS DE QUALQUER TIPO, EXPRESSAS OU IMPLÍCITAS. A AIVAX NÃO GARANTE QUE OS SERVIÇOS SERÃO ININTERRUPTOS, SEGUROS, ISENTOS DE ERROS OU ADEQUADOS PARA UM PROPÓSITO ESPECÍFICO. NA MÁXIMA EXTENSÃO PERMITIDA PELA LEI, A AIVAX NÃO SERÁ RESPONSÁVEL POR DANOS INDIRETOS, INCIDENTAIS, ESPECIAIS, CONSEQUENCIAIS, EXEMPLARES OU PUNITIVOS RESULTANTES DO SEU ACESSO OU USO DOS SERVIÇOS. O CONTEÚDO GERADO PODE CONTER INACURÁCIAS, OMISSÕES OU ALUCINAÇÕES E É FORNECIDO APENAS PARA FINS INFORMATIVOS. VOCÊ É RESPONSÁVEL POR REVISÃO HUMANA ANTES DO USO CRÍTICO. --- ### 7. Indenização Você concorda em indenizar, defender e isentar a AIVAX, suas afiliadas, administradores, colaboradores e parceiros de reivindicações, perdas, danos, responsabilidades, custos e despesas resultantes de: (i) Conteúdo de Entrada; (ii) uso indevido dos Serviços; (iii) violação destes Termos ou da lei aplicável; (iv) violação de propriedade intelectual, privacidade ou direitos de personalidade de terceiros; (v) uso inadequado ou exposição de chaves de API ou credenciais associadas à sua conta. ### 8. Rescisão e Pós‑Rescisão Após rescisão ou suspensão: (a) acesso e chaves podem ser desativados; (b) exportação de dados disponíveis pode ser limitada por janelas de retenção, estado da conta e requisitos de segurança; (c) dados podem ser excluídos ou anonimados de acordo com a Política de Privacidade e procedimentos operacionais; (d) valores pendentes permanecem a pagar. ### 9. Força Maior Nenhuma parte será responsável por falhas ou atrasos causados por eventos fora de seu controle razoável, incluindo desastres naturais, ações governamentais, falhas generalizadas de infraestrutura, ciberataques, pandemias, guerras ou apagões amplos. Obrigações de pagamento por serviços consumidos não são extintas por força maior. ### 10. Controle de Exportação e Sanções Você declara que não está localizado em, nem age em nome de, nenhuma entidade ou pessoa sujeita a sanções ou restrições comerciais aplicáveis. Você não usará os Serviços para fins proibidos por leis de exportação, anticorrupção ou antiterrorismo. Violação desta cláusula pode resultar em suspensão ou rescisão imediata. ### 11. Confidencialidade e Segurança de Credenciais Você deve manter chaves de API, tokens e credenciais confidenciais e implementar controles de acesso adequados. Atividades realizadas com suas credenciais podem ser presumidas como autorizadas até que uma violação seja reportada. Você deve notificar prontamente a AIVAX sobre suspeita de uso não autorizado. ### 12. Feedback e Melhorias Qualquer comentário, sugestão, ideia ou feedback que você fornecer pode ser usado pela AIVAX para melhorar ou desenvolver produtos e serviços, sem compensação, crédito ou obrigações adicionais de confidencialidade. ### 13. Funcionalidades Beta e Descontinuação de Modelos Funcionalidades identificadas como "Beta", "Experimental" ou equivalentes podem ser instáveis, mudar de comportamento ou ser removidas. A AIVAX pode descontinuar modelos, provedores ou limites técnicos por motivos de desempenho, custo, conformidade, disponibilidade ou segurança. ### 14. Procedimento de Remoção Se você acredita que a saída ou uso dos Serviços infringe direitos autorais, marcas registradas, privacidade, personalidade ou outros direitos, envie um aviso para legal@aivax.net contendo: (i) identificação precisa do material; (ii) base da reivindicação; (iii) suas informações de contato; (iv) declaração de boa‑fé e veracidade. A AIVAX pode remover ou limitar o acesso preventivamente e encerrar contas reincidentes. ### 15. Cessão Você não pode ceder ou transferir estes Termos sem consentimento prévio por escrito da AIVAX. A AIVAX pode ceder estes Termos, total ou parcialmente, inclusive em transações corporativas, fusões, aquisições ou reorganizações, mediante aviso quando exigido. ### 16. Persistência As seguintes disposições sobrevivem à rescisão: Propriedade Intelectual, Limitação de Responsabilidade, Indenização, Confidencialidade, Rescisão, Cessão, Lei Aplicável e Jurisdição, e quaisquer outras que, por sua natureza, devam persistir. ### 17. Acordo Integral Estes Termos, juntamente com a Política de Privacidade e quaisquer documentos adicionais expressamente referenciados, constituem o acordo integral entre você e a AIVAX em relação aos Serviços. ### 18. Avisos Avisos formais podem ser entregues por e‑mail registrado, aviso no painel ou publicação na página oficial de Termos. Um aviso enviado por e‑mail é considerado recebido após 24 horas, salvo erro técnico comprovado. ### 19. Atualizações de Preço e Limites A AIVAX pode ajustar preços, modelos de faturamento, limites de uso, cotas de armazenamento ou políticas de limite de taxa. Mudanças materiais que afetem custos futuros podem ser comunicadas com aviso prévio razoável, salvo exigência legal, de segurança ou condições de emergência. O uso continuado após a entrada em vigor das mudanças implica aceitação onde permitido. ### 20. Idioma A versão em português destes Termos prevalece sobre traduções fornecidas apenas para conveniência. ### 21. Modificações dos Termos A AIVAX pode modificar estes Termos. Mudanças materiais podem ser notificadas por publicação, e‑mail ou aviso no painel e podem exigir aceitação adicional. O uso continuado após a data de vigência constitui aceitação onde permitido. ### 22. Disposições Gerais Estes Termos são regidos pelas leis da República Federativa do Brasil. O tribunal da Comarca de São Paulo, Estado de São Paulo, Brasil, é eleito para resolver disputas, com renúncia a qualquer outra jurisdição, por mais privilegiada que seja. A invalidez de qualquer cláusula não afeta a validade das disposições restantes. Para dúvidas sobre estes Termos de Uso, entre em contato: **legal@aivax.net**. --- Source: https://docs.aivax.net/pt-br/docs/legal/third-party-processors.html # Processadores de Dados AIVAX utiliza serviços de terceiros para operações específicas, como infraestrutura, armazenamento de objetos, entrega de e‑mail, processamento de pagamentos, pesquisa na web, inferência de IA, reclassificação e geração de imagens. Os provedores envolvidos em uma solicitação dependem do modelo selecionado, gateway, ferramenta e integração. Esta página é um inventário técnico divulgado, não um aconselhamento jurídico. Não lista todos os provedores que podem estar disponíveis através de catálogos de modelos ou agregadores. As políticas dos provedores podem mudar, e os Gerentes de Conta devem revisar os termos do provedor que se aplicam aos seus modelos e ferramentas selecionados antes de enviar informações pessoais, confidenciais, reguladas ou sensíveis. A coluna de lei de proteção de dados resume os principais marcos identificados na política de privacidade atual ou no adendo de processamento de dados de cada provedor. A aplicabilidade pode variar conforme a entidade contratante, a localização do titular dos dados e a região de processamento. ## Operações, Serviços e Infraestrutura | Provedor | Usado para | Lei de proteção de dados | | --- | --- | --- | | [Cloudflare](https://www.cloudflare.com/) | Proxy reverso/segurança onde implantado e serviços de incorporação | [EU/UK GDPR, Swiss FADP, and CCPA/CPRA](https://www.cloudflare.com/cloudflare-customer-dpa/) | | [Hetzner](https://www.hetzner.com/) | Infraestrutura de computação e hospedagem | [GDPR and BDSG](https://docs.hetzner.com/general/company-and-policy/data-protection-at-hetzner/) | | [netcup](https://www.netcup.com/) | Infraestrutura de computação e hospedagem | [GDPR and BDSG](https://www.netcup.com/en/contact/data-privacy) | | [Backblaze](https://www.backblaze.com/) | Armazenamento de objetos e arquivos para mídia gerada, mídia enviada, documentos gerados, arquivos expostos e artefatos de erro | [EU/UK GDPR and CCPA/CPRA](https://www.backblaze.com/company/privacy) | | [Brevo](https://www.brevo.com/) | E‑mail transacional e notificações | [GDPR, French Data Protection Act, CCPA/CPRA, PIPEDA, and LGPD](https://www.brevo.com/legal/privacypolicy/) | | [InfinitePay](https://infinitepay.io/) | Criação de fatura de pagamento e confirmação de pagamento | [LGPD (Brazilian Law No. 13,709/2018)](https://www.infinitepay.io/legal/aviso-de-privacidade) | | [Stripe](https://stripe.com/) | Processamento de eventos de pagamento onde o checkout Stripe está configurado | [EU/UK GDPR, Irish Data Protection Act 2018, and CCPA/CPRA](https://stripe.com/privacy) | | [Twitter/X](https://developer.x.com/) | Ferramentas integradas de pesquisa e leitura de postagens do X/Twitter | [EU/UK GDPR, Swiss FADP, CCPA, and LGPD](https://x.com/en/privacy) | | [Linkup](https://www.linkup.so/) | Pesquisa na web para enriquecimento de contexto | [GDPR, French Data Protection Act, ePrivacy Directive, and CCPA/CPRA](https://www.linkup.so/privacy-policy) | | [Tavily](https://www.tavily.com/) | Pesquisa na web para enriquecimento de contexto | [GDPR, UK Data Protection Act 2018, and applicable U.S. state privacy laws](https://www.tavily.com/privacy) | | [Sinkin AI](https://sinkin.ai/) | Geração de imagens para modelos de imagem selecionados | [EU/UK GDPR, CCPA, and Virginia CDPA](https://sinkin.ai/privacy) | | [Pollinations](https://pollinations.ai/) | Geração de imagens para modelos de imagem selecionados | [GDPR](https://pollinations.ai/privacy) | ## Provedores de Inferência Direta, Incorporação e Reclassificação | Provedor | Usado para | Lei de proteção de dados | | --- | --- | --- | | [Groq](https://groq.com/) | Inferência LLM via um endpoint compatível com OpenAI | [EU/UK GDPR, Swiss FADP, CCPA/CPRA, and Saudi PDPL](https://console.groq.com/docs/legal/customer-data-processing-addendum) | | [Jina AI](https://jina.ai/) | Incorporações, reclassificação e pesquisa na web | [GDPR and BDSG](https://jina.ai/legal/) | | [OpenRouter](https://openrouter.ai/) | Roteamento de modelo, fallback e síntese de voz | [GDPR, CCPA/CPRA, and applicable U.S. state privacy laws](https://openrouter.ai/privacy/) | | [DeepInfra](https://deepinfra.com/) | Inferência de IA | [GDPR and CCPA/CPRA](https://deepinfra.com/privacy) | | [Xiaomi MiMo](https://platform.xiaomimimo.com/) | Inferência de modelo Xiaomi | [PIPL, EU/UK GDPR, and Swiss FADP](https://privacy.mi.com/all/en_US) | | [Inception Labs](https://www.inceptionlabs.ai/) | Inferência de modelo Mercury | [California Civil Code §§ 1798.83–1798.84 and Nevada Revised Statutes Chapter 603A](https://www.inceptionlabs.ai/docs/privacy-policy) | | [Cloudflare Workers AI](https://developers.cloudflare.com/workers-ai/) | Serviços de incorporação | [EU/UK GDPR, Swiss FADP, and CCPA/CPRA](https://www.cloudflare.com/cloudflare-customer-dpa/) | ## Famílias de Modelos e Provedores Subjacentes | Provedor | Usado para | Lei de proteção de dados | | --- | --- | --- | | [OpenAI](https://openai.com/) | Famílias de modelos OpenAI expostas no catálogo ou integrações compatíveis | [EU/UK GDPR, CCPA/CPRA, and applicable U.S. state privacy laws](https://openai.com/policies/privacy-policy/) | | [Google Vertex AI](https://cloud.google.com/vertex-ai) | Gemini e outras famílias de modelos Google | [EU/UK GDPR, Swiss FADP, and CCPA/CPRA](https://cloud.google.com/terms/data-processing-addendum/) | | [Anthropic](https://www.anthropic.com/) | Famílias de modelos Claude | [EU/UK GDPR, Swiss FADP, LGPD, and applicable U.S. state privacy laws](https://www.anthropic.com/legal/privacy) | | [AWS](https://aws.amazon.com/) | Famílias de modelos hospedados na AWS, como Amazon Nova ou provedores baseados em Bedrock | [EU/UK GDPR, Swiss FADP, and CCPA/CPRA](https://aws.amazon.com/privacy/) | | [Cohere](https://cohere.com/) | Famílias de modelos Cohere | [PIPEDA, GDPR, and CCPA/CPRA](https://cohere.com/privacy) | | [xAI](https://x.ai/) | Famílias de modelos Grok e Grok Voice através de rotas configuradas | [EU/UK GDPR, Swiss FADP, and CCPA/CPRA](https://x.ai/legal/data-processing-addendum) | | [Mistral AI](https://mistral.ai/) | Famílias de modelos Mistral | [GDPR, French Data Protection Act, and CCPA/CPRA](https://legal.mistral.ai/terms/privacy-policy) | | [DeepSeek](https://www.deepseek.com/) | Famílias de modelos DeepSeek | [PIPL, Data Security Law, and Cybersecurity Law of the People's Republic of China](https://cdn.deepseek.com/policies/en-US/deepseek-privacy-policy.html) | | [Z.ai](https://z.ai/) | Famílias de modelos GLM/Z.ai | [Singapore PDPA and GDPR/UK GDPR where applicable](https://docs.z.ai/legal-agreement/privacy-policy) | | [Alibaba Cloud](https://www.alibabacloud.com/product/modelstudio) | Famílias de modelos Qwen/Alibaba | [GDPR/UK GDPR and applicable regional laws, including PIPL](https://www.alibabacloud.com/help/en/legal/latest/alibaba-cloud-international-website-privacy-policy-history) | | [Cerebras](https://www.cerebras.ai/) | Famílias de modelos Cerebras | [GDPR and CCPA/CPRA](https://trust.cerebras.ai/) | | [Nebius](https://nebius.com/) | Famílias de modelos suportados por Nebius | [EU/UK GDPR, Dutch GDPR Implementation Act, and Swiss FADP](https://docs.nebius.com/legal/dpa) | | [Fireworks AI](https://fireworks.ai/) | Famílias de modelos suportados por Fireworks | [EU/UK GDPR, CCPA/CPRA, and applicable U.S. state privacy laws](https://fireworks.ai/privacy-policy) | | [Novita](https://novita.ai/) | Famílias de modelos suportados por Novita | [CCPA/CPRA](https://novita.ai/legal) | | [Azure](https://azure.microsoft.com/) | Famílias de modelos suportados por Azure | [EU/UK GDPR, CCPA/CPRA, and PIPEDA](https://www.microsoft.com/licensing/docs/view/Microsoft-Products-and-Services-Data-Protection-Addendum-DPA) | | [LongCat](https://longcat.chat/) | Metadados da família de modelos LongCat/Meituan | [PIPL, Data Security Law, and Cybersecurity Law of the People's Republic of China; GDPR and CCPA where applicable](https://longcat.chat/platform/private/) | ## Observações sobre Manipulação de Dados Por padrão, a AIVAX não utiliza o Conteúdo de Entrada do Gerente de Conta, Conteúdo Gerado ou Conversas para treinar modelos proprietários da AIVAX. Registros elegíveis de RAG anonimizado e de reclassificação são usados para desenvolvimento de modelo apenas quando um Gerente de Conta autorizado habilita o programa opcional descrito em [Coleta de Dados](https://docs.aivax.net/pt-br/docs/data-collecting.md). Indexação e armazenamento de documentos são excluídos. Provedores de terceiros e agregadores podem ter suas próprias regras de processamento, retenção, monitoramento de abuso e aprimoramento de modelo. O modelo, provedor, ferramenta ou integração selecionados determinam qual terceiro recebe os dados para uma solicitação específica. Evite enviar informações sensíveis, confidenciais, reguladas ou pessoais a um provedor a menos que você tenha revisado os termos atuais desse provedor e possua uma base legal adequada para o processamento.