Skip to main content
As Integrações dão ao agente ações prontas de apps externos: criar um evento no Google Agenda, buscar um contato no HubSpot, gravar uma linha no Google Sheets, mandar um e-mail pelo Gmail. Você conecta a conta do app no projeto e escolhe quais ações o agente pode usar. Não há API para montar: o formato de cada ação vem pronto. São mais de mil apps, já integrados à Zatten, sem conta extra para criar. No editor do agente, esse tipo de ferramenta aparece como Aplicativos, e cada ação adicionada mostra Aplicativo conectado na lista de tools. Use um app integrado quando o app do cliente final está em Integrações. Quando não está, ou quando você precisa controlar exatamente o que é enviado e devolvido, use uma tool HTTP.

Onde fica no painel

Editor do agente → Tools → Adicionar → filtro Aplicativos (o filtro Tudo mostra os primeiros seis). Os apps conectados aparecem primeiro. A conexão da conta também pode ser feita antes, no menu Integrações.

Como configurar

1

Escolha o app

Busque pelo nome em Aplicativos.
2

Conecte a conta, se ainda não estiver conectada

O painel mostra “Conecte a conta para escolher quais ações a IA poderá executar.”
  • OAuth (Google, HubSpot e outros): Conectar abre a janela do próprio app para o dono da conta entrar e autorizar.
  • Credencial (chave de API, token ou usuário e senha): o painel pede para configurar na tela Integrações, em Abrir Integrações.
3

Escolha as ações

Com a conta conectada, aparece a lista de ações do app, com busca (Buscar ação) e marcar todas. Marque só as que o agente precisa e clique Salvar. Salvar troca as ações daquele app pelas marcadas.
4

Ensine no prompt quando usar

A descrição de cada ação vem pronta, em geral em inglês, e não é editável. A regra do negócio (“consulte a agenda antes de oferecer horário”) vai no prompt.
5

Publique

Teste no chat de teste e publique a versão.
Ao clicar numa ação já adicionada, o painel mostra os Parâmetros da ação (o que o modelo vai preencher) e, em Comportamento, a Mensagem para a IA se a chamada falhar (veja Quando a ação falha, abaixo). Se o app não estiver conectado neste projeto, a ação aparece marcada Não conectado na lista de tools, e o painel oferece Conectar ali mesmo.

O nome que o modelo vê

Cada ação vira uma tool com o nome APP_ACAO, em maiúsculas: o identificador do app, um _ e o identificador da ação. Exemplos: Use esse nome para citar a tool no prompt (“use GOOGLECALENDAR_FIND_FREE_SLOTS antes de oferecer horário”) e na lista always_include do filtro de tools, se ele estiver ligado (só pelo JSON do config). Confira o nome exato nos Parâmetros da ação.

A conta conectada fica presa ao projeto

  • A conexão é do projeto, não da agência. O agente de um projeto só usa as contas conectadas naquele projeto. Nunca usa a conta de outro projeto.
  • Uma conta por app em cada projeto. É a mesma para todos os leads.
  • Conecte com a conta do cliente final (a agenda da clínica), não com a da agência.
  • Se a ação está no agente mas a conta não está conectada (ou foi desconectada, ou o acesso foi revogado do lado do app), a tool continua visível ao modelo: o agente carrega as ações pelo nome, sem conferir a conexão. A chamada falha, a conversa segue e o modelo recebe o erro. Veja Quando a ação falha, abaixo.
  • Conecte a conta que tem o recurso. No Google, a conta escolhida na tela de autorização precisa ser a mesma onde está a agenda. Uma conta Google sem agenda conecta normalmente, mas toda chamada volta com o erro notACalendarUser (“The user must be signed up for Google Calendar”). Com várias contas logadas no navegador, confira o e-mail na tela do Google.

Quando a ação falha

Uma falha numa ação de app não derruba o atendimento: a conversa continua e o modelo recebe, como resultado da ação, o que deu errado. Vale para conta não conectada ou expirada, erro do app (ex.: 401, 403) e qualquer outra falha. O que o modelo faz depois depende do que você disser a ele. Há dois lugares:
  • Mensagem para a IA se a chamada falhar, na própria ação (Tools → clique na ação → Comportamento). Vale só para aquela ação e chega ao modelo junto com o erro. É o lugar certo para a regra de contingência. Ex. na ação de consultar a agenda: “Diga que a equipe vai confirmar o horário e transfira o atendimento.”
  • O prompt, para a regra geral do atendimento.
Sem mensagem configurada, o modelo recebe só o erro e a orientação de não inventar o resultado. Se a conta não está conectada, recebe também a orientação de não repetir a chamada na conversa. Cada ação tem a própria mensagem: configure em todas as ações do app que o agente usa (no Google Agenda, por exemplo, consultar, criar e apagar evento).

Como descobrir o que cada app faz

No painel: busque o app em Integrações e abra Lista de ferramentas no card, ou escolha o app em Aplicativos no editor do agente e veja a lista de ações. Para decidir se um app serve ao caso do cliente:
  1. Busque o app em Integrações.
  2. Procure a ação que faz o que você precisa (“find free slots”, “create contact”).
  3. Confira os parâmetros: o modelo vai precisar de tudo o que for obrigatório.

Apps que não aparecem no painel

O painel mostra só os apps que um projeto consegue conectar sozinho: O catálogo do painel é atualizado a cada hora. Se o app não aparece, use uma tool HTTP para a API dele.

Pelo MCP

A ação viaja no bloco langchain do template do projeto, com o on_error dela. A conexão não viaja: é uma autorização da conta do cliente final, presa ao projeto. Ao criar, duplicar ou aplicar um template num projeto sem o app conectado, as notes da resposta avisam: Integração não conectada neste projeto: <toolkit>. Uma pessoa precisa conectar a conta pela tela Integrações; o assistente só guia. Nunca tente “levar” a conexão trocando um id no template: não há id de conexão no config. A conta é sempre a do projeto que está atendendo.

Armadilhas

  • Marcar todas as ações. Um app pode ter dezenas de ações, e cada uma é uma tool no contexto. Marque só as necessárias.
  • Descrição em inglês e não editável. A regra de quando usar precisa estar no prompt.
  • Conta errada. A conta conectada é usada para todos os leads do projeto.
  • Duplicar ou importar o projeto leva as ações, não a conexão. Conecte de novo no projeto novo; até lá, toda chamada falha.
  • Sem regra para a falha. Sem a mensagem de erro na ação nem regra no prompt, o modelo improvisa quando o app cai. Configure a mensagem nas ações que o atendimento não pode perder (agenda, CRM).
  • Mensagem de erro e prompt dizendo coisas diferentes. Se o prompt manda transferir quando a agenda falha e a mensagem da ação manda seguir agendando, o modelo recebe as duas ordens. Mantenha uma só regra.
  • Parâmetros que o lead não sabe. Ações com muitos campos obrigatórios (ids internos, ids de agenda) fazem o modelo inventar. Diga no prompt de onde tirar cada valor, ou prefira uma tool HTTP com esses valores fixos.

Perguntas frequentes

App integrado quando o app está em Integrações e as ações prontas servem. Tool HTTP quando o app não está, quando você quer fixar valores (o id da agenda, o calendário certo) e só deixar o modelo preencher o essencial, ou quando a resposta precisa ser enxuta.
Não. As integrações já fazem parte da Zatten, sem custo nem limite para a agência. Só a conta do próprio app (Google, HubSpot…) é conectada, na tela Integrações.
Sim, conectando a conta em cada projeto. Cada projeto guarda a própria conexão.

Para saber mais