Alterar o modelo de embeddings do Agent Zero significa editar o slot de embeddings dentro de um Model Preset e clicar em Save — e, quando essa edição altera o provedor ou o nome do modelo, o próximo acesso reindexa a memória, porque um índice FAISS é dimensionado para a largura de saída de um modelo e os vetores já armazenados em disco foram escritos pelo modelo antigo. O próprio guia de instalação do Agent Zero declara a consequência em uma única linha — "Changing the embedding_llm will re-index all of A0's memory" — e não oferece procedimento, duração nem caminho de volta. Esta página preenche essa lacuna a partir do código-fonte: o que a reconstrução automática realmente faz, os dois caminhos em que ela silenciosamente não é acionada, como verificar se as memórias antigas continuam sendo recuperadas e como retornar. A Kunavo não oferece nenhum modelo de embeddings, portanto esse slot é comprado em outro lugar; os slots que a Kunavo pode precificar são o principal e o utilitário.
Primeiro, mantenha separados estes dois números de versão. O framework está na v2.12, publicada em 9 de setembro de 2026, conforme o próprio artigo de lançamento do projeto. O número mais destacado no README é A0 Launcher v1.7, que é o instalador de desktop separado em agent0ai/a0-launcher; associá-lo ao framework está errado por uma linha principal inteira. E, na v2.x, os campos de modelo ficam em um preset, não em uma configuração global simples: o guia de model-presets diz que "every setup contains a main, utility, and embedding model", e Settings → Agent → Models é onde você escolhe qual preset os novos chats usarão. Observe que o guia de instalação ainda documenta uma seção "Embedding Model Settings" com os campos Provider e Model Name; portanto, um passo a passo escrito dessa forma não está automaticamente desatualizado — mas o valor digitado é aplicado ao slot de um preset, que é justamente o que torna importante o aviso de propagação abaixo.
Por que isso não é como trocar o modelo de chat
Uma alteração no modelo de chat entra em vigor na próxima solicitação e nada no disco precisa ser movido. Uma alteração em embeddings invalida o armazenamento. O Agent Zero dimensiona seu índice FAISS com base no que o modelo ativo retorna — faiss.IndexFlatIP(len(embedder.embed_query("example"))) em plugins/_memory/helpers/memory.py —, portanto a largura é uma propriedade do modelo, não de um valor de configuração. O padrão fornecido, sentence-transformers/all-MiniLM-L6-v2, mapeia texto para um espaço de 384 dimensões, conforme seu model card. O guia de embeddings da OpenAI define text-embedding-3-small como 1536 e text-embedding-3-large como 3072. Essa é a alteração de formato provocada pela troca.
Dois fatos de escopo determinam quantas reconstruções você realmente está comprando. Primeiro, trata-se de uma edição de preset, não global: o guia de model-presets diz que os escopos "store only the preset choice; editing a preset updates every scope that uses it", portanto uma edição pode se propagar mais do que você pretendia — e alternar entre presets também pode alterar o modelo de embeddings. Os presets selecionados Efficiency e Power são fornecidos sem um bloco próprio de embeddings, e o guia apenas diz que um preset existente que não seja o padrão may herdar valores avançados omitidos do Default; portanto, leia o resumo do preset em vez de presumir. Segundo, project_memory_isolation: true é o padrão fornecido em the memory plugin config, portanto uma instância com vários projetos mantém vários armazenamentos independentes, e cada um é reconstruído em seu próprio próximo uso — um projeto intocado por semanas paga sua reconstrução no dia em que alguém o abre.
Etapa 1: faça um backup e anote o que está deixando
O guia de uso do Agent Zero já nomeia este caso: os backups protegem "your chats, projects, knowledge, memory, settings, skills, and workspace files", e ele lista "bulk memory cleanup" entre as coisas para as quais fazer backup antes. Faça um backup em Settings → Backup & Restore ou use o Backup do Launcher de /a0/usr. Observe a própria ressalva do guia de que os segredos "may not always be included in backup archives"; portanto, mantenha as credenciais separadamente.
Depois, registre o modelo do qual você está migrando. Não presuma qual é — a coleção de presets selecionados é baixada de um repositório público na primeira inicialização e pode mudar depois da data da sua instalação.
# Read the CURRENT model off your own instance before you touch anything.
# The curated preset set is fetched from GitHub at first start, so the
# default you installed with is not necessarily today's default.
# Container name: take it from your own `docker ps`.
docker exec agent-zero ls -la /a0/usr/memory/default
docker exec agent-zero cat /a0/usr/memory/default/embedding.json
# -> {"model_provider": "huggingface",
# "model_name": "sentence-transformers/all-MiniLM-L6-v2"}
# Projects do not share that directory. With project isolation on (the
# shipped default) each project keeps its own store under its own meta
# directory, and each one rebuilds on its own next use.Etapa 2: faça a alteração
O fluxo documentado no guia de instalação tem três etapas: abra Settings na Web UI, escolha o provedor para cada função e escreva o nome do modelo; clique em Save. Quatro coisas que esse fluxo não informa, todas lidas do código-fonte em main:
| Armadilha | O que realmente acontece |
|---|---|
| Preencher uma URL base de API no slot padrão | Ela é ignorada. O provedor huggingface com um nome que começa com sentence-transformers/ faz um desvio imediato para um wrapper local que nunca toca na LiteLLM e filtra os parâmetros para uma lista de permissões exclusiva do ambiente local. Para alcançar um endpoint hospedado, é necessário sair desse caminho local — usar outro provedor ou um nome de modelo sem o prefixo sentence-transformers/. Qualquer um deles é um campo armazenado pelo metaarquivo e, portanto, qualquer um aciona a reconstrução. |
| Inserir o endpoint antes de trocar o provedor | Perdido. O menu suspenso do provedor carrega @change="model.api_base = ''; model.kwargs = {}; …"; portanto, alterá-lo apaga a URL base da API e todos os parâmetros adicionais. Troque o provedor primeiro e depois preencha Advanced. |
| Presumir que um gateway de chat compatível com OpenAI funcionará | O slot chama a função embedding() da LiteLLM, não o wrapper de chat. O endpoint precisa implementar POST /v1/embeddings. O provedor other é remapeado para o provedor openai da LiteLLM, e sua chave é gravada em .env como API_KEY_OTHER. |
Usar localhost para um servidor de modelos local | Dentro do Docker, isso significa o contêiner do Agent Zero. O guia de instalação orienta você a usar http://host.docker.internal:<port> ou o endereço do gateway de bridge. |
O que a reconstrução faz — e os dois caminhos em que ela não acontece
Ao salvar, model_config_set.py compara o provedor, o nome e os kwargs de embeddings anteriores e novos e, diante de qualquer diferença, inicia embedding_model_changed como uma tarefa em segundo plano adiada; a extensão acionada por ele faz uma coisa: recarrega a memória. O próximo acesso executa novamente Memory.initialize(), que verifica embedding.json ao lado do índice. Esse arquivo contém exatamente dois campos — model_provider e model_name. Quando há incompatibilidade, o código extrai todos os documentos do índice antigo com get_all_docs, cria um índice novo na largura nova e reinsere os mesmos documentos com os mesmos IDs. Esse caminho funciona e preserva suas memórias.
| O que você altera | O metaarquivo percebe? | Resultado |
|---|---|---|
| Provedor ou nome do modelo | Sim — ambos são armazenados | Documentos lidos e reinseridos na nova largura. O caminho pretendido. |
Somente um parâmetro adicional, por exemplo, reduzir vetores da OpenAI com dimensions | Não — kwargs não são armazenados | A memória é recarregada e depois carrega o índice antigo sem alterações. A incompatibilidade de largura aparece na recuperação, não no salvamento. |
| Somente a URL base da API, apontando para outro endpoint com o mesmo nome de modelo | Não — e o caminho de salvamento também não a compara | Nenhuma recarga é sequer agendada; o índice antigo simplesmente continua em uso. Se esse endpoint responder com uma largura diferente, a recuperação lançará uma asserção do FAISS. |
| Um arquivo de índice editado manualmente, truncado ou restaurado de fora | Uma verificação de hash separada falha primeiro | O índice antigo nunca é carregado, portanto seus documentos nunca são extraídos, e um índice novo vazio é escrito enquanto o console imprime um aviso de incompatibilidade de hash terminando com "index will be rebuilt" — nada sobre os documentos descartados. Um arquivo de hash ausente ou ilegível é tratado como válido. |
As linhas dois e três são a lacuna por trás da issue #759, "Errors after changed default Embedding Model", aberta em 13 de outubro de 2025 e encerrada, cujo traceback mostra assert d == self.d durante uma busca de similaridade da recuperação de memória; essa lacuna ainda está visível em main em 21 de setembro de 2026. Uma segunda issue encerrada, #1396, relata um erro 400 em /api/embed do Ollama que seu autor atribuiu a um índice obsoleto e fornece como solução alternativa a exclusão de index.faiss e index.pkl. Essa solução destrói o armazenamento; trate-a como uma redefinição, nunca como reparo ou reversão. Nenhuma das duas issues recebeu comentário de mantenedor — #1396 foi encerrada por um bot de issues obsoletas após noventa dias —, portanto ambos os diagnósticos são dos próprios autores e ambas as resoluções não foram verificadas.
Etapa 3: verifique a recuperação antiga, não uma chamada bem-sucedida
A falha produzida por essa alteração é silenciosa, portanto "o novo modelo respondeu" é o teste de aceitação errado. Abra o painel de memória e, conforme o guia de memória, filtre nas quatro áreas — main, fragments, solutions e skills — procurando algo que você saiba que é anterior à alteração. Faça isso uma vez por projeto, porque cada projeto tem seu próprio armazenamento. Depois, observe o limite de similaridade: o memory_recall_similarity_threshold fornecido é 0.7, um padrão por plugin, não uma propriedade de nenhum modelo, e um novo modelo de embeddings redistribui as pontuações de similaridade. A recuperação pode piorar sem que um único erro seja emitido; por isso, o controle do limite faz parte da verificação, e não é um detalhe.
Há uma coisa que esta página não pode informar: se a Web UI mostra algum sinal de progresso ou conclusão enquanto a reconstrução está em execução. Ela é executada como uma tarefa em segundo plano adiada, e nenhuma interface para isso foi confirmada. Presuma que não haverá confirmação e verifique manualmente.
Reversão e custo de uma reconstrução
Não existe uma reversão documentada pelo fornecedor. O que existe é o mecanismo de backup junto com o comportamento do metaarquivo descrito acima, e o caminho abaixo é montado a partir desses dois elementos, em vez de ser publicado pelo projeto. Restaure o backup anterior à alteração ou defina o slot novamente com o provedor e o nome do modelo anteriores exatos; isso faz a comparação do metaarquivo falhar na outra direção e reconstrói o índice. No mesmo contêiner, o cache de embeddings em tmp/ é separado por provedor e modelo; portanto, voltar a um modelo usado anteriormente pode reutilizar vetores armazenados em cache para textos inalterados — mas tmp/ fica fora do backup documentado, então recriar o contêiner o perde. O que o código faz se o novo provedor falhar no meio de uma reconstrução não foi testado e não é declarado aqui; verifique a partir do backup em vez de depender disso.
Quanto ao custo: a Kunavo não oferece nenhum modelo de embeddings, portanto todos os valores abaixo são pagos diretamente à OpenAI na sua própria conta, com as tarifas publicadas verificadas em 21 de setembro de 2026. Dimensione o trabalho por conta própria — conte os documentos armazenados no painel de memória, multiplique pelo comprimento médio e divida por aproximadamente quatro caracteres por token. Esse divisor é uma convenção, não uma medição.
| Destino da reconstrução | Tarifa publicada, cobrada diretamente pela OpenAI | 3M tokens reembutidos | 30M tokens reembutidos |
|---|---|---|---|
text-embedding-3-small (1536 dimensões) | $0.02 por 1M tokens, cobrado diretamente pela OpenAI | $0.06 | $0.60 |
text-embedding-3-large (3072 dimensões) | $0.13 por 1M tokens, cobrado diretamente pela OpenAI | $0.39 | $3.90 |
text-embedding-ada-002 | $0.10 por 1M tokens, cobrado diretamente pela OpenAI — mais caro que o 3-small, portanto não é um destino sensato hoje | $0.30 | $3.00 |
| O modelo local fornecido, na CPU | Nenhuma cobrança por token; em vez disso, tempo de CPU na sua própria máquina | Tempo de máquina | Tempo de máquina |
Isto é aritmética de tokens sob as premissas declaradas, não uma reconstrução medida nem um teto. Também é por armazenamento: com o isolamento de projetos ativado, multiplique pelo número de projetos que realmente serão abertos novamente e lembre-se de que uma reversão é uma segunda reconstrução à mesma tarifa.
Os dois slots que a Kunavo pode atender
Para deixar claro o limite: o slot de embeddings não é atendido aqui, e um gateway que implementa o formato de comunicação de chat não é um endpoint de embeddings. Restam os slots principal e utilitário, que são modelos de chat comuns. Nas tarifas atuais do catálogo, Claude Sonnet 4.6 lista $2.10 por milhão de tokens de entrada e $10.50 por milhão de tokens de saída, e Claude Haiku 4.5 lista $0.70 e $3.50.
Suponha um mês com 8M tokens de entrada e 0.4M de saída em um slot principal Claude Sonnet 4.6, além de 2M de entrada e 0.2M de saída em um slot utilitário Claude Haiku 4.5; o slot de embeddings não é atendido aqui e está excluído. Estimativa do catálogo: $23.10. Esses são volumes presumidos, não uma carga de trabalho medida nem um teto de cobrança — o Agent Zero não foi testado em tempo de execução com o endpoint da Kunavo, e a configuração descrita acima foi lida no código-fonte e na documentação do projeto, não executada. O valor do catálogo é um piso de cobrança: quando o upstream informa sua cobrança, a fatura é o maior valor entre o custo do catálogo e o custo do upstream multiplicado pela margem aplicável. O complemento mínimo é de $10 em crédito pré-pago, o que é um mínimo de financiamento, não uma assinatura — consulte detalhes de cobrança.
Se você ainda está escolhendo um framework, Agent Zero vs OpenClaw compara os modelos de execução e o layout de três slots. Para o formato do endpoint em si, a referência compatível com OpenAI e o guia de início rápido abrangem os slots de chat, e criar uma conta na Kunavo financia esses slots. Para trabalhos de recuperação de modo geral, implementação de RAG aborda a mesma separação entre um provedor de geração e uma etapa de recuperação comprada separadamente.
Perguntas frequentes
Como altero o modelo de embeddings no Agent Zero?
O fluxo documentado no guia de instalação do Agent Zero tem três etapas: abra a página Settings na Web UI, escolha o provedor do LLM para cada função (Main Model, Utility Model, Embedding Model) e escreva o nome do modelo; depois clique em Save. Na v2.x, essa edição é aplicada aos slots de um Model Preset, e não a uma configuração global simples, porque cada preset contém um modelo principal, um modelo utilitário e um modelo de embeddings; o guia de model-presets alerta que editar um preset atualiza todos os escopos que o utilizam. Há uma ressalva que a página de instalação não menciona: alterar o menu suspenso do provedor limpa a URL base da API e todos os parâmetros adicionais desse slot; portanto, insira um endpoint personalizado depois de trocar o provedor, nunca antes.
Alterar o modelo de embeddings do Agent Zero exclui minhas memórias?
Não no caminho documentado. O Agent Zero grava um pequeno metaarquivo, embedding.json, ao lado do índice, contendo o provedor de embeddings e o nome do modelo. Quando eles deixam de corresponder ao modelo configurado, memory.py lê todos os documentos do índice FAISS antigo com get_all_docs, cria um novo índice dimensionado pelo comprimento atual do vetor e reinsere os mesmos documentos com os mesmos IDs. As memórias são reembutidas, não descartadas. A etapa destrutiva é a solução alternativa descrita na issue #1396 para um índice corrompido — excluir index.faiss e index.pkl —, o que apaga a memória em vez de migrá-la e não é uma reversão.
Quanto tempo leva para reindexar a memória do Agent Zero?
O projeto não publica nenhum valor, e nada foi encontrado em outros lugares. O número mais parecido nas notas de versão v2.12 — uma redução do tempo mediano de salvamento relatado, de 1.171 ms para 52 ms — pertence à edição de presets, na qual as comparações de embeddings deixaram de fazer leituras redundantes. Ele mede o salvamento de um preset, não a reconstrução de um índice; não faça seu planejamento com base nele. O custo da reconstrução varia conforme a quantidade de documentos armazenados e a velocidade de resposta do modelo de destino; portanto, dimensione-o a partir da sua própria instância: conte os documentos armazenados no painel de memória e lembre-se de que, com o isolamento de projetos ativado no padrão fornecido, cada projeto paga sua própria reconstrução no dia em que for aberto novamente, em vez de todos ao mesmo tempo.
Por que recebo um erro de asserção do FAISS depois de alterar o modelo de embeddings?
Uma incompatibilidade de dimensão: o índice armazenado tem uma largura e o modelo ativo retorna outra. Uma issue encerrada no repositório do Agent Zero, "Errors after changed default Embedding Model" (#759, aberta em 13 de outubro de 2025), registra exatamente esse formato — um AssertionError de assert d == self.d emitido no armazenamento vetorial durante uma busca de similaridade pela extensão de recuperação de memória. Pela leitura do código em main, o mecanismo que o produz é uma lacuna entre duas verificações: o caminho de salvamento compara provedor, nome e kwargs antes de disparar seu evento de recarga, enquanto o metaarquivo em disco registra apenas provedor e nome. Assim, uma alteração somente em kwargs dispara a recarga e depois carrega o índice antigo sem alterações; já uma alteração somente na API base nem sequer é comparada, então nada é agendado e o índice antigo continua simplesmente em uso. Nenhum comentário de mantenedor estava visível nessa issue e a resolução não foi verificada; a lacuna ainda está visível em main em 21 de setembro de 2026.
Posso apontar o slot de embeddings do Agent Zero para a Kunavo?
Não. A Kunavo não oferece nenhum modelo de embeddings — a rota /v1/embeddings implementa o formato de comunicação, mas nenhum modelo habilitado disponibiliza esse endpoint, portanto uma chamada falha; a própria documentação legível por máquina da Kunavo diz para não recomendá-la para embeddings. Isso é mais importante que o habitual neste caso porque o slot de embeddings do Agent Zero não passa pelo wrapper de chat: models.py importa a função embedding() da LiteLLM para ele, uma superfície de API diferente; portanto, um gateway de chat compatível com OpenAI não é automaticamente um gateway de embeddings. Compre esse slot diretamente de um provedor que o ofereça ou mantenha o modelo local na CPU. O papel da Kunavo em um preset do Agent Zero é atender aos slots principal e utilitário.
Como reverto uma alteração do modelo de embeddings no Agent Zero?
O Agent Zero não publica nenhum procedimento de reversão para isso — a documentação oferece um aviso de uma linha de que a alteração reindexa a memória e um mecanismo geral de Backup and Restore, sem nada entre eles. O caminho montado a partir desses dois elementos é: restaure o backup feito antes da alteração ou defina o slot novamente com o provedor e o nome do modelo anteriores exatos, para que a comparação do metaarquivo falhe novamente na outra direção e faça a reconstrução. No mesmo contêiner, o cache local de embeddings em tmp/ é separado por provedor e modelo; portanto, voltar a um modelo usado anteriormente pode reutilizar vetores armazenados em cache para textos inalterados — mas tmp/ fica fora do backup documentado, então esse armazenamento desaparece quando o contêiner é recriado. Nunca faça a reversão excluindo os arquivos do índice.
Verificado em 21 de setembro de 2026 com base em agent0ai/agent-zero main — memory.py, model_config_set.py, models.py, os padrões do plugin de memória e a árvore de documentação — além do artigo de lançamento v2.12, da coleção a0-presets, das duas issues vinculadas e dos preços publicados pela OpenAI. Nada nesta página foi executado: as afirmações sobre o mecanismo foram verificadas nas fontes, não testadas em runtime, e a Kunavo não possui registro de execução do Agent Zero. As tarifas de tokens da Kunavo vêm do catálogo ativo.