> ## 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

# Configurar IA

Modelos reais atrás dos aliases cheap / fast / smart — as chaves ficam no servidor.

## Instalação e configuração

Antes de qualquer etapa, leia [Antes de começar](https://supastack.dev/pt/docs/web/before-you-start.md) e [Noções básicas sobre terminal](https://supastack.dev/pt/docs/web/terminal-basics.md). Estas instruções presumem que você abriu o monorepo supastack completo no VS Code; sua raiz package.json marca a raiz do repositório. Nos comandos pnpm, um pacote de espaço de trabalho é um aplicativo ou uma pasta de código compartilhado; no produto, um espaço de trabalho é o contêiner de dados e o limite de segurança de uma equipe. corepack pnpm --filter ... seleciona um pacote do monorepo enquanto os comandos são executados a partir de sua raiz. Se você abriu apenas uma pasta móvel ou desktop sincronizada, ela não contém o back-end da Web, a configuração do Docker ou os scripts raiz: execute o back-end deste monorepo ou de um servidor hospedado acessível e use os próprios scripts da pasta da plataforma. Uma variável de ambiente é uma configuração nomeada armazenada em um arquivo .env local ou no painel de hospedagem; reinicie o aplicativo relevante após alterá-lo e mantenha os segredos do servidor fora dos valores NEXT_PUBLIC_ e EXPO_PUBLIC_.

1. Abra apps/web/.env.local para o servidor Web local e apps/web/src/agent-runtime.ts para seleção do provedor; .env.example é a lista de nomes de configurações suportadas.

2. Mantenha AI_PROVIDER=fake para trabalho de interface local, a menos que você tenha sua própria conta de provedor e queira testar a geração real; nunca coloque chaves de provedor em uma configuração NEXT_PUBLIC_ ou EXPO_PUBLIC_.

3. Inicie o aplicativo Web a partir da raiz do repositório com corepack pnpm --filter @supastack/web dev. Esperado: telas locais podem ser exploradas sem configuração de provedor pago; a geração real requer um provedor de servidor válido e opções de modelo habilitadas no catálogo do banco de dados.

O AI_PROVIDER=fake predefinido suporta trabalho local determinista. A configuração de fornecedores reais pertence ao ambiente de servidor. As chaves de fornecedor listadas em .env.example incluem OpenAI, Anthropic e um endpoint compatível com OpenAI.

AI_MODEL_POLICY contém IDs de modelo ordenados para os aliases cheap, fast e smart. Uma lista de aliases vazia desativa essa escolha. Os IDs de modelo devem corresponder a linhas de catálogo ativadas na base com preços imutáveis efetivos.

```
AI_MODEL_POLICY='{"cheap":[],"fast":["catalog-model-id"],"smart":["catalog-model-id"]}'
AGENT_FRAMEWORK=ai-sdk    # ai-sdk | mastra | langgraph | openai-agents
```


## Comandos para copiar

Siga os comentários para ver em qual pasta um comando é executado. Se dois terminais estiverem rotulados, abra duas janelas de terminal e mantenha o primeiro comando em execução enquanto usa o segundo.

```
corepack pnpm --filter @supastack/web dev
```


## Fluxo de implementação

Configura o catálogo e a política do workspace antes de aceitar tarefas de produção. O browser recebe os aliases ativados, enquanto a correspondência de capacidade, a escolha de modelo, as verificações de permissão e a aplicação de orçamentos ficam no servidor.

Mantém credenciais fora das variáveis NEXT_PUBLIC_ e EXPO_PUBLIC_. Para o modo chave própria, usa o envelope encriptado existente e a fronteira de desencriptação do servidor; nunca devolvas uma chave de fornecedor guardada à interface.


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

Se o aplicativo relatar que nenhum modelo de IA está disponível, verifique o AI_PROVIDER do servidor, os modelos e preços habilitados no catálogo do administrador e a política de alias barato/rápido/inteligente. Se um provedor real retornar um erro de autenticação, verifique sua chave em apps/web/.env.local e reinicie o servidor. Uma chave com o prefixo NEXT_PUBLIC_ ficaria visível para os navegadores e deveria ser removida.

Verifica aliases desativados, capacidades em falta, permissão inativa e orçamentos esgotados. Usa uma execução de smoke de fornecedor autorizada à parte para geração real. Se nenhum alias estiver disponível, inspeciona a política do servidor e a configuração do catálogo em vez de expor um seletor de modelo cru.


Para continuar a configuração, leia [Configurar jobs em segundo plano](https://supastack.dev/pt/docs/web/setup-jobs.md).


## Seguinte

[IA e jobs em segundo plano](https://supastack.dev/pt/docs/modules/ai.md)