Um agente de triagem no Zendesk com LangChain pode ler um ticket, consultar dados autorizados da operação e sugerir categoria, equipe responsável e próximo passo. A implementação mais controlável usa ferramentas pequenas, com entradas validadas, consultas previamente definidas e uma etapa separada para gravar a decisão no atendimento.
A proposta deste guia é construir uma integração própria usando as APIs do Zendesk e as ferramentas do LangChain. Não se trata de um recurso nativo que basta ativar. Comece com sugestões internas e revisão humana; depois, automatize somente ações cujo comportamento tenha sido observado em testes representativos.
Resumo rápido
- Receba eventos de ticket e processe em uma fila.
- Vincule o solicitante à conta antes de consultar pedidos.
- Exponha ferramentas de leitura específicas, sem SQL livre.
- Valide a classificação antes de atualizar o Zendesk.
- Trate repetição, concorrência e falhas como parte do fluxo.
Desenhe a triagem antes de escolher o modelo
Liste as categorias reais da operação: acesso, cobrança, entrega, dúvida de uso e outras que a equipe consegue distinguir. Para cada uma, documente quais evidências justificam o encaminhamento. Se dois supervisores classificam o mesmo chamado de maneiras incompatíveis, o primeiro problema está na definição do processo, não no modelo de linguagem.
Separe intenção, impacto e ação. Um cliente pode pedir cancelamento, relatar uma falha e mencionar uma cobrança na mesma mensagem. A categoria principal precisa refletir uma regra clara, enquanto intenções secundárias podem ficar em campos auxiliares. A prioridade deve seguir critérios definidos pela empresa, sem depender apenas do tom emocional do texto.
Escolha um contrato de saída limitado. Por exemplo: categoria de uma lista permitida, grupo sugerido, evidências utilizadas, informação faltante e necessidade de revisão. Não aceite nomes de equipes inventados. A aplicação transforma rótulos aprovados em identificadores válidos do Zendesk e rejeita qualquer valor fora do cadastro.
O LangChain documenta ferramentas como funções com entradas e saídas definidas que podem ser chamadas pelo modelo. Essa estrutura ajuda a disponibilizar consultas específicas, mas a autorização permanece no código da aplicação. Para entender essa separação, consulte o guia sobre permissões de agentes de IA.
Receba o evento e consulte o ticket atual
A documentação do Zendesk orienta conectar webhooks a gatilhos ou automações quando a atividade envolve tickets. O serviço receptor deve validar a origem da chamada e registrar o evento antes de iniciar o processamento demorado. O webhook sinaliza trabalho pendente; a consulta posterior ao ticket permite verificar o estado mais recente.
Use uma fila durável e um identificador de processamento. O Zendesk informa que a entrega de webhooks não oferece garantia absoluta de execução única. Por isso, desenhe as ações para que repetir o mesmo evento não acrescente notas duplicadas nem mova o chamado repetidamente. Também mantenha uma reconciliação para detectar itens que não chegaram ao processamento.
Não envie todo o histórico ao modelo por padrão. Selecione a mensagem relevante, campos necessários e contexto recente suficiente para entender a solicitação. Anexos exigem uma etapa própria de extração e validação. Um arquivo enviado pelo cliente não deve ganhar permissão para executar instruções só porque foi convertido em texto.
Defina quando a automação fica inelegível: chamado já assumido manualmente, classificação confirmada, conversa encerrada ou evento antigo. Essa checagem evita uma atualização tardia sobrescrever o trabalho do atendente. Uma alteração feita pelo próprio agente também precisa ser reconhecida para não disparar um ciclo interminável de triagem.
Crie ferramentas de banco com escopo restrito
Prefira funções como consultar_pedido, consultar_incidente e consultar_plano. Cada uma deve ter finalidade delimitada e retornar apenas os campos necessários. Uma ferramenta chamada executar_sql, que recebe qualquer texto produzido pelo modelo, amplia muito a superfície de erro. Mesmo uma credencial somente de leitura pode expor dados de outras pessoas se a consulta for irrestrita.
O vínculo entre solicitante e conta deve vir do serviço autenticado, a partir de dados confiáveis da operação. Um número de pedido escrito na mensagem não prova que o pedido pertence ao autor. A ferramenta verifica essa relação antes de retornar qualquer informação. Não peça ao modelo que decida se a identidade parece convincente.
| Ferramenta proposta | Entrada visível | Controle no servidor |
|---|---|---|
| consultar_pedido | Referência do pedido | Conta autorizada, consulta parametrizada e campos mínimos |
| consultar_incidente | Produto e sintoma | Somente incidentes publicáveis à equipe solicitante |
| consultar_plano | Identificador de serviço | Vínculo contratual e retorno sem dados financeiros desnecessários |
| sugerir_triagem | Categoria e evidências | Lista permitida e registro interno |
| aplicar_triagem | Proposta aprovada | Revalidação do ticket e permissão de escrita |
Use consultas parametrizadas, tempo máximo de execução e limite de linhas no adaptador de banco. A configuração da conexão deve restringir leitura às tabelas ou visões necessárias. Essas medidas se complementam: a validação do argumento não substitui permissões no banco, e permissões no banco não substituem o filtro por conta.
Retorne resultados estruturados que distingam encontrado, não encontrado, não autorizado e indisponível. Para o modelo, uma falha de conexão não pode parecer ausência de pedido. Preserve detalhes técnicos no registro operacional; a resposta entregue ao agente deve conter uma explicação curta e a próxima ação permitida.
Limite chamadas por execução e impeça consultas repetidas sem novo dado. Um agente que insiste na mesma ferramenta pode aumentar latência e carga sem melhorar a classificação. Ao atingir o orçamento operacional definido para o fluxo, encaminhe a sugestão incompleta para revisão, com os passos já executados.
Separe a sugestão da gravação no Zendesk
O modelo produz uma proposta, e um validador determinístico confere seu formato, campos e coerência mínima. Uma regra simples pode impedir encaminhamento automático quando o pedido não pertence à conta, quando há múltiplas intenções conflitantes ou quando uma consulta necessária falhou. A justificativa deve citar fatos retornados pelas ferramentas, não conhecimento presumido sobre o cliente.
O LangChain oferece mecanismos de revisão humana de chamadas a ferramentas. Na aplicação, configure quais ações exigem aprovação e como o estado será persistido para a retomada. A interface do revisor precisa mostrar proposta, argumentos, evidências e mudanças pretendidas. Um botão de aprovação sem esse contexto favorece confirmações mecânicas.
Restrinja inicialmente a gravação a campos internos e encaminhamento entre grupos permitidos. Publicar resposta ao cliente, emitir crédito ou cancelar serviço são capacidades diferentes, que exigem avaliação própria. Não coloque essas ações na mesma ferramenta genérica de atualização só por conveniência de implementação.
A documentação do Zendesk descreve atualizações seguras com safe_update e updated_stamp para detectar mudanças concorrentes. Releia o ticket antes de aplicar uma proposta aprovada e trate conflito como necessidade de reavaliar o estado. Repetir uma gravação antiga sem considerar a intervenção do atendente pode apagar uma decisão válida.
Depois da gravação, consulte o resultado e registre o identificador da execução. Diferencie proposta aprovada, atualização enviada e atualização confirmada. Essa separação permite recuperar falhas parciais sem inferir sucesso a partir da resposta do modelo. Guarde os dados estritamente necessários para auditoria e diagnóstico.
Exemplo: suporte de uma loja virtual de Curitiba
Imagine uma loja fictícia de Curitiba que recebe chamados de entrega e cobrança. Um cliente escreve que pagou, mas o acompanhamento do pedido não mudou. A mensagem pode indicar uma dúvida sobre prazo, uma inconsistência de pagamento ou simplesmente uma atualização ainda não exibida. O objetivo do agente é reunir contexto e encaminhar, sem prometer resolução.
O serviço recebe o evento, consulta o ticket e resolve o vínculo entre solicitante e conta. A ferramenta de pedido consulta somente registros dessa conta. Ela retorna o estado conhecido e o horário da última atualização. Se o número informado pertencer a outra conta, o fluxo não revela a existência do pedido e solicita revisão de identidade pelo processo normal.
Com um pedido autorizado, o agente pode consultar se existe um incidente operacional relacionado. Em seguida, sugere categoria e equipe. A evidência aparece como dado de sistema com horário de consulta, separada da alegação feita na mensagem. Isso ajuda o atendente a perceber quando o cliente e o cadastro relatam coisas diferentes.
No piloto, a sugestão fica numa fila interna. O supervisor aprova, corrige ou rejeita, registrando o motivo. Uma correção de categoria alimenta a análise da taxonomia; uma consulta ausente indica uma ferramenta insuficiente. Não transforme automaticamente toda correção em novo treinamento sem investigar a causa do erro.
O teste inclui mensagem sem referência, pedido duplicado, evento repetido, banco indisponível e atendimento alterado durante a análise. O comportamento esperado é explícito para cada cenário. Não há estimativa de ganho neste exemplo: a equipe precisa medir tempo de revisão, encaminhamentos corrigidos e falhas antes de decidir o alcance da automação.
Erros comuns
Confundir linguagem convincente com evidência. A justificativa pode parecer correta sem ter consultado a fonte necessária. Exija referências aos resultados das ferramentas e verifique se a classificação depende realmente dos fatos disponíveis. Quando faltar evidência, encaminhe com essa lacuna visível.
Permitir SQL livre para ganhar flexibilidade. Consultas abertas tornam mais difícil prever acesso e custo. Comece com funções de domínio pequenas. Uma nova pergunta recorrente deve resultar numa ferramenta revisada, com testes de autorização, e não numa permissão ampla de exploração do banco.
Tratar prioridade como sentimento. Uma mensagem agressiva não informa sozinha o impacto operacional. Defina critérios concretos, como serviço afetado e quantidade de usuários confirmada, e preserve uma rota de escalonamento humano. O agente pode pedir informação, mas não deve inventá-la.
Ignorar repetição e concorrência. Webhooks duplicados e alterações simultâneas são situações normais de integração. Teste idempotência, isto é, a repetição sem efeitos adicionais, e conflitos de gravação. Uma nota repetida pode parecer pequena, mas dificulta a leitura e pode disparar outras regras de atendimento.
Liberar produção apenas pela acurácia média. Separe resultados por categoria e risco. Um bom desempenho em dúvidas comuns pode esconder erros em acessos indevidos ou cobranças. Use o roteiro de testes de agentes antes da produção para organizar cenários e evidências.
Inclua uma chave operacional para suspender gravações preservando a entrada dos chamados. Defina quem responde por falhas e como recuperar a fila. Compare versões com os mesmos casos e acompanhe rejeições humanas após mudanças de prompt, ferramenta ou regras. Assim, o piloto continua avaliável durante a evolução do produto.
Perguntas frequentes
É obrigatório usar um agente com várias etapas?
Não. Se os dados já estão disponíveis e a tarefa é apenas classificar, um fluxo fixo pode ser suficiente. Use ferramentas quando a consulta adicional realmente depender do conteúdo do chamado.
O agente precisa acessar o banco principal?
Não necessariamente. Uma API interna ou visão de leitura pode oferecer os dados necessários com escopo menor. Escolha a alternativa que permita controlar acesso, atualização e disponibilidade sem expor tabelas inteiras.
Posso responder automaticamente ao cliente?
Essa é uma etapa distinta da triagem. Primeiro valide fatos, autorização, tom e consequências da resposta. O piloto descrito prioriza sugestões internas; qualquer comunicação automática precisa de critérios próprios e monitoramento.
Como lidar com baixa confiança?
Use sinais verificáveis, como falta de dados, conflito de categorias ou ferramenta indisponível. A confiança declarada pelo próprio modelo não basta. Encaminhe ao humano com o motivo e as evidências já coletadas.
