Pular para o conteúdo principal

Como configurar o Assistente de IA

Ligue o Agon a um provedor de IA à sua escolha e o Assistente de Suporte de IA, o Modo de Ações da IA e as respostas de aconselhamento de negócio começam a funcionar. A forma mais rápida é uma chave de API gratuita do Google Gemini, e demora cerca de 3 minutos.

Como funciona o Assistente de IA no Agon​

O Agon funciona no seu próprio computador, e a configuração do Assistente de IA também. O assistente utiliza uma chave de provedor de IA que pertence ao seu estúdio: cria a chave junto do provedor, cola-a no Agon, e o Agon comunica diretamente com esse provedor. O Agon não gere nenhum serviço de IA próprio, e nenhum serviço de IA vem incluído no Agon.

Tem três opções:

OpçãoO que precisaIndicado para
Google Gemini (recomendado para começar)Uma conta GoogleComeçar em poucos minutos
GroqUma conta GroqUm provedor alternativo com respostas rápidas
Um modelo local com o OllamaUm computador razoavelmente potenteManter todos os prompts na sua própria máquina

Se não configurar nada, o assistente continua a funcionar em modo básico (ver abaixo).

O que é o modo básico?​

Sem um provedor de IA, o painel do assistente transforma-se numa pesquisa na documentação. Escreve algumas palavras-chave e o Agon mostra os artigos de ajuda que melhor correspondem, diretamente desta documentação. O modo básico:

  • funciona inteiramente no seu computador, sem ligação à Internet e sem IA;
  • não consegue responder a perguntas livres, executar ações de IA nem dar conselhos de negócio;
  • mostra um botão Configurar a IA nas Configurações que o traz de volta a esta configuração.

Configurações → Assistente de IA mostra Não configurado · modo básico enquanto nenhum provedor estiver ligado.

Antes de começar​

  • Só a conta de gestor do estúdio pode configurar o Assistente de IA.
  • Leia Privacidade: para onde vão os seus prompts abaixo, sobretudo se pretende mencionar dados de clientes no chat.
  • Trate uma chave de API como uma palavra-passe. Quem a tiver pode utilizar a sua conta no provedor.

Criar uma chave de API do Gemini em 3 minutos​

  1. Abra a página de chaves de API do Google AI Studio no seu navegador e inicie sessão com a sua conta Google.
  2. Clique em Create API key (a Google pode chamar-lhe Get API key; com a interface em português, o nome aparece traduzido). Se a Google pedir para escolher ou criar um projeto, aceite a predefinição.
  3. Clique no ícone de copiar junto à nova chave. É uma sequência longa de letras e números.
  4. No Agon, abra Configurações → Assistente de IA. [SCREENSHOT: Configurações → Assistente de IA com a lista de provedores e o campo Chave de API]
  5. Em Provedor de IA, escolha Google Gemini.
  6. Cole a chave no campo Chave de API e clique em Verificar e salvar.
  7. O Agon testa a chave com a Google de imediato. Quando funciona, vê Chave de API salva e verificada. e um distintivo Chave ativa · Google Gemini.

Já está: abra o assistente e faça-lhe uma pergunta.

Os ecrãs da Google mudam de vez em quando. Se um botão tiver outro nome, procure "API keys" no menu do Google AI Studio. A ligação Obter uma chave de API do Google Gemini junto à lista de provedores no Agon abre sempre a página certa.

Utilizar o Groq em alternativa​

  1. Abra a página de chaves de API da consola da Groq e inicie sessão ou crie uma conta.
  2. Clique em Create API Key, dê-lhe um nome (por exemplo, "Agon") e copie a chave. A Groq só a mostra uma vez.
  3. No Agon, abra Configurações → Assistente de IA, escolha Groq em Provedor de IA, cole a chave em Chave de API e clique em Verificar e salvar.

Um distintivo Chave ativa · Groq confirma que está a funcionar.

Utilizar um modelo local com o Ollama​

Com o Ollama, o modelo de IA funciona no seu próprio computador, pelo que os prompts nunca saem dele. Precisa de um computador com memória suficiente para executar um modelo. As respostas costumam ser mais lentas do que as de um provedor na nuvem, e a qualidade depende do modelo que escolher. Esta é uma opção avançada.

  1. Transfira e instale o Ollama a partir de ollama.com e depois transfira um modelo, por exemplo executando ollama pull llama3.1 num terminal. O Ollama tem de estar em execução sempre que utilizar o assistente.

  2. Feche o Agon.

  3. Abra a pasta de dados do Agon:

    • macOS: ~/Library/Application Support/Agon
    • Windows: %APPDATA%\Agon

  4. Abra o ficheiro chamado .env num editor de texto simples (no macOS está oculto: prima Cmd + Shift + . no Finder para o mostrar). Não altere nem apague as linhas que já lá estão: contêm as chaves secretas que protegem os dados do seu estúdio. Acrescente estas duas linhas no fim, com o nome do modelo que transferiu:

    LLM_PROVIDER=ollama
    LLM_MODEL=ollama_chat/llama3.1

  5. Guarde o ficheiro e volte a abrir o Agon.

Configurações → Assistente de IA mostra agora Ativo · modelo local. Se mais tarde guardar uma chave de provedor com Usar a chave do seu próprio provedor, essa chave tem prioridade sobre o modelo local.

Privacidade: para onde vão os seus prompts​

  • Diretamente do seu computador para o provedor que escolheu. Quando utiliza o Gemini ou o Groq, a sua pergunta e a informação de que o assistente precisa para responder viajam diretamente do computador onde o Agon está a funcionar para esse provedor. Nunca passam pelo programador do Agon nem por nenhum servidor gerido para o Agon.
  • Com o Ollama, nada sai do seu computador.
  • A sua chave fica no seu computador. O Agon guarda-a encriptada na base de dados local do seu estúdio e nunca a volta a mostrar depois de guardada. Remover chave em Configurações → Assistente de IA apaga-a a qualquer momento.
  • Os níveis gratuitos podem utilizar os seus dados. Os níveis gratuitos de alguns provedores podem utilizar os dados que envia para treinar ou melhorar os seus modelos. Para perguntas que incluam dados dos seus clientes, utilize um nível pago ou um modelo local. Os termos mudam com o tempo, por isso verifique os termos atuais e a política de privacidade do seu provedor antes de começar: termos da API do Gemini · política de privacidade da Groq.
  • O seu estúdio tem o controlo. É o seu estúdio que tem o acordo com o provedor, pelo que, ao abrigo do RGPD, esse provedor é um subcontratante do seu estúdio. O guia do RGPD explica o que isso significa para si.

Um bom hábito: não cole dados sensíveis de clientes (notas de saúde, por exemplo) no chat, a menos que esteja confortável com os termos do seu provedor.

Se prevê uma utilização intensiva​

Todos os provedores limitam quantos pedidos uma chave pode fazer por minuto e por dia. Os níveis gratuitos têm limites baixos. Se várias pessoas utilizarem o assistente ao mesmo tempo, ou se utilizar o Modo de Ações da IA em horas de maior movimento, poderá ver uma mensagem a indicar que o seu provedor de IA está a limitar os pedidos.

Para resolver, aumente os seus limites junto do provedor:

  • Google Gemini: ative a faturação no projeto Google Cloud a que pertence a sua chave. O Google AI Studio mostra o seu nível atual e como fazer o upgrade.
  • Groq: consulte os seus limites e as opções de upgrade na consola da Groq.

A mesma chave continua a funcionar no Agon depois do upgrade. Não precisa de uma chave nova e não há nada a alterar no Agon. O provedor fatura-lhe diretamente tudo o que ultrapassar o nível gratuito. Um nível pago é também a escolha recomendada para dados de clientes (ver a secção de privacidade acima).

E se algo correr mal?​

O Agon diz que a minha chave é inválida Verifique se copiou a chave completa sem espaços a mais e se o provedor escolhido corresponde à chave: uma chave da Groq não funciona como chave do Gemini. Confirme que a chave não foi apagada na consola do provedor. Uma chave acabada de criar pode demorar um minuto a começar a funcionar, por isso aguarde e clique em Verificar e salvar novamente.

O assistente diz que o meu provedor de IA está a limitar os pedidos Atingiu o limite do seu provedor. Aguarde um minuto e tente novamente, ou aumente os seus limites (consulte Se prevê uma utilização intensiva).

O assistente só mostra artigos de ajuda O assistente está em modo básico porque nenhum provedor está ligado. Siga os passos acima para adicionar uma chave. Configurações → Assistente de IA mostra Não configurado · modo básico quando nenhum provedor está ativo.

Recebo "Esta ação precisa do Agon AI, que está desativado" a meio de uma ação O Modo de Ações da IA não consegue concluir um pedido sem um provedor. Adicione uma chave em Configurações → Assistente de IA e volte a pedir.

A minha chave funcionava e agora o assistente falha A chave pode ter sido apagada, ter expirado ou ter esgotado a quota do lado do provedor. Crie uma chave nova e guarde-a com Alterar em Configurações → Assistente de IA.

Quero mudar de provedor ou substituir a minha chave Em Configurações → Assistente de IA, clique em Alterar junto ao distintivo Chave ativa, escolha o provedor, cole a chave nova e clique em Verificar e salvar.

Quero deixar de usar a minha chave Em Configurações → Assistente de IA, clique em Remover chave e confirme. O Agon apaga a chave da base de dados do seu estúdio e o assistente passa de imediato para o modo básico, sem reiniciar. Se achar que a chave pode ter sido divulgada, apague-a (revogue-a) também na consola do seu provedor (Google AI Studio ou a consola da Groq) para que mais ninguém a possa usar.

O modelo local não funciona Confirme que o Ollama está em execução e que o nome do modelo no ficheiro .env corresponde a um modelo que transferiu (ollama list mostra-os). Reinicie o Agon depois de qualquer alteração ao ficheiro .env.

Perguntas frequentes​

O Assistente de IA tem algum custo? O Agon não cobra por ele. O seu provedor pode cobrar: os níveis gratuitos têm limites de utilização, e o que os ultrapassar é faturado diretamente pelo provedor.

O programador do Agon pode ver as minhas perguntas? Não. Os prompts vão do seu computador diretamente para o provedor que escolheu, ou ficam no seu computador com o Ollama.

Que provedor devo escolher? O Gemini é o mais rápido de configurar. Para dados de clientes, um nível pago de qualquer provedor ou um modelo local é a escolha mais segura.