> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Funcionalidades de IA

Chat, tarefas, política de modelos e bring-your-own-key.

## Experimente uma IA falsa e escolha um provedor real

Para obter seu primeiro resultado, siga a tarefa /dashboard do tutorial da Web: inicie o fluxo local, coloque um prompt na fila, execute-o e visualize o resultado. AI_PROVIDER=fake retorna uma resposta de demonstração repetível sem enviar dados para um modelo externo ou usar uma chave API paga.

Para geração real, primeiro configure contas persistentes, escolha um provedor de IA e siga a configuração de IA abaixo. Adicione um modelo e seu preço ao catálogo do banco de dados, escolha os modelos permitidos para cada alias e conceda ao espaço de trabalho o acesso necessário. Um alias como fast é uma escolha amigável mostrada ao usuário; ele próprio não é um ID de modelo de provedor externo.

Um AI task em segundo plano também precisa do serviço de trabalhos configurado. Se nenhuma opção de modelo for mostrada, inspecione o catálogo e a política de alias antes de tentar novamente. Se o acesso for negado, inspecione o direito do espaço de trabalho ativo. Mantenha todas as chaves API do provedor na configuração do servidor Web, não no navegador, aplicativo móvel ou janela da área de trabalho.

[Experimente a demonstração de IA sem credenciais](https://supastack.dev/pt/docs/web/ship-in-5-minutes.md)

[Configurar geração de IA real](https://supastack.dev/pt/docs/modules/ai-configuration.md)

[Adicionar modelos e preços permitidos](https://supastack.dev/pt/docs/web/setup-ai.md)

[Configurar execução de tarefa em segundo plano](https://supastack.dev/pt/docs/modules/jobs.md)


## Segue o ciclo de vida da tarefa

A API de tarefas de produção valida o workspace autenticado e a permissão antes de persistir uma tarefa e despachar o workflow ai.generate do Trigger.dev. O router aplica requisitos de capacidade e a política de modelo configurada.

```
POST /api/ai/tasks
  → authenticated workspace + entitlement
  → durable task record
  → Trigger.dev ai.generate
  → model routing + generation
  → usage record + result
  → transactional completion delivery
```


## Configura aliases e orçamentos

O utilizador escolhe um alias ativado: cheap, fast ou smart. O servidor controla os IDs de modelo subjacentes, as credenciais de fornecedor, a política do workspace e a aplicação de orçamentos. O suporte encriptado de chaves próprias deve preservar a mesma fronteira de servidor.


## Mantém a semântica de workflow explícita

O JobRunner só promete enqueue, status e cancel. A semântica de workflow do Trigger.dev é explícita, incluindo o comportamento de execução durável. Não deduzas retries nem garantias de agendamento do contrato genérico.

O caminho de submissão de produção usa idempotência e recuperação de tarefa guardada para lidar com dispatch ambíguo. A conclusão da geração é separada da entrega do email de conclusão.


## Instalação e configuração

AI_PROVIDER=fake mantém o desenvolvimento determinístico. Os providers de produção configuram-se no servidor (OpenAI, Anthropic ou um endpoint compatível com OpenAI) com chaves que nunca entram nos bundles do cliente. AI_MODEL_POLICY mapeia os aliases visíveis ao utilizador — cheap, fast, smart — para ids de modelo do catálogo; um alias vazio remove a escolha da interface.

O catálogo de modelos (ai-model-catalog) transporta metadados de capacidade e preços imutáveis para que os registos de utilização continuem explicáveis após alterações de preço.

```
POST /api/ai/tasks          → durable task + Trigger.dev dispatch
GET  /api/ai/tasks/{taskId}  → status + result
/chat                        → streaming assistant surface
```


## Fluxo de implementação

A superfície de chat mantém threads por membro do workspace e faz streaming de tokens através de chat-stream-runtime. As gerações mais longas correm como tarefas: autorizadas na fronteira da API, executadas pelo workflow ai.generate e recuperáveis através da store de submission idempotente.

O modo bring-your-own-key armazena chaves de provider como envelopes AES-GCM (CREDENTIAL_ENCRYPTION_KEY, byok-key-vault.ts); a desencriptação acontece apenas dentro do percurso de execução do servidor. Utilização e custo estimado são registados por pedido para os orçamentos do workspace.


## Verificação e resolução de problemas

Verifica que um alias desativado está ausente da interface, que as negações de entitlement e orçamento acontecem antes do dispatch, que uma submission repetida reutiliza a sua tarefa e que uma chave BYOK armazenada nunca regressa ao cliente. Mantém a aceitação com modelos reais no percurso smoke de provider documentado.


## Seguinte

[Jobs em segundo plano](https://supastack.dev/pt/docs/web/jobs.md)