Integração ServiceTitan com agente de IA: campos e aprovações
Quais campos do ServiceTitan expor primeiro a um agente de IA, quais escritas exigem aprovação do despachante e onde o acesso só de leitura deve parar.

Um agente de IA para o ServiceTitan funciona melhor quando lê um conjunto restrito de campos de serviços, agendamentos, clientes e técnicos, e quando cada alteração proposta espera numa fila até que um despachante aprove. Comece com acesso de leitura ao status do serviço, ao endereço de atendimento, às janelas de agendamento, aos técnicos atribuídos e aos tipos de serviço. Adicione ações de escrita uma de cada vez, cada uma ligada a um aprovador nomeado e a um motivo claro para existir.
Principais pontos
- Libere primeiro a leitura do status do serviço, das janelas de agendamento, dos endereços de atendimento e das atribuições de técnicos.
- Mantenha campos de pagamento, custo, margem, folha e valor-hora dos técnicos fora do alcance do agente na primeira versão.
- Exija aprovação do despachante para qualquer ação que mova um técnico, altere um horário confirmado, cancele um serviço ou envie mensagem ao cliente.
- Dê a cada chamada de criação uma chave de idempotência, para que uma nova tentativa nunca agende a mesma visita duas vezes.
- Avalie o agente por um resultado observável, como menos serviços sem técnico no início do dia, antes de ampliar o escopo.
Quais registros do ServiceTitan um agente deve ler primeiro?
Uma plataforma de serviço de campo guarda muitos tipos de registros, e um agente de despacho não precisa da maioria deles. Para o trabalho de agendamento, os objetos centrais são serviços, agendamentos, registros de cliente e de local, atribuições de técnicos, tipos de serviço e unidades de negócio. Orçamentos e faturas importam para o acompanhamento posterior, mas trazem campos financeiros que um agente de agendamento não deve manipular de forma alguma.
Antes de desenhar qualquer ferramenta, abra a documentação atual para desenvolvedores do ServiceTitan e liste os objetos que suas credenciais realmente expõem. A cobertura depende dos módulos da sua conta e de como o administrador delimita a integração. Por isso, qualquer lista publicada, inclusive este artigo, serve como ponto de partida e não como contrato. Peça uma identidade de integração dedicada, com o menor escopo que ainda funcione. A mesma lógica aparece em menor privilégio para agentes de IA.
Quais campos do ServiceTitan expor na primeira versão?
Exponha os campos de que o agente precisa para responder a uma pergunta de despacho, e nenhum campo que responda a uma pergunta financeira. Um primeiro conjunto de leitura razoável inclui:
- Identificador do serviço, nome do tipo de serviço, unidade de negócio e status atual
- Início e fim do agendamento, com o fuso horário da unidade de negócio
- Identificador e nome do técnico atribuído, mais um indicador de serviço sem técnico
- Endereço de atendimento e observações de acesso que a equipe já trata como compartilháveis
- Primeiro nome do cliente e canal de contato preferido, sem o histórico completo de contatos
- Data e hora da última mudança de status e o usuário que a fez
- Apenas observações do serviço visíveis ao despachante, filtradas pela configuração de visibilidade
Alguns campos devem ficar de fora até uma revisão posterior: status de pagamento, referências de cartão ou conta bancária, totais de fatura, linhas de custo e margem, valor-hora dos técnicos, gravações de ligações e observações em texto livre que possam conter dados financeiros, de saúde ou códigos de acesso. Os dados do cliente são dados pessoais, então o agente deve receber apenas o que a tarefa exige. Uma regra simples protege você: se um campo não muda a próxima decisão de despacho, deixe-o de fora.
Os campos de horário merecem cuidado extra. Uma janela de agendamento só é útil quando lida no horário local da unidade de negócio, por isso a resposta da ferramenta deve informar o fuso horário de forma explícita, em vez de esperar que o modelo o deduza. Fusos diferentes entre unidades de negócio são uma fonte comum de propostas de reagendamento erradas.
Quais ações de escrita devem exigir aprovação do despachante?
O acesso de leitura é o lugar seguro para começar. As escritas vêm em seguida, e a questão não é se o agente consegue executá-las, e sim quais delas uma pessoa precisa confirmar. Uma regra viável: o agente pode rascunhar, propor e enfileirar qualquer alteração, mas nunca efetiva uma mudança que afete o dia de um técnico, um horário confirmado de cliente ou dinheiro antes que um despachante nomeado aprove.
Escritas que devem sempre exigir aprovação na primeira versão:
- Reatribuir um técnico a um serviço que já tem agendamento
- Mover um agendamento confirmado para outra data ou janela
- Cancelar um agendamento ou marcar um serviço como cancelado
- Enviar qualquer mensagem ao cliente sobre mudança de horário, preço ou serviço
- Alterar o tipo de serviço ou a unidade de negócio de um serviço existente
- Criar um orçamento ou qualquer documento que o cliente vai ver
Algumas escritas podem passar para uma aprovação mais leve após um período de revisão, se a empresa quiser: adicionar uma observação interna a um serviço, preencher campos de modelo vazios em um serviço sem técnico ou criar um serviço em rascunho para um pedido sem agendamento conflitante. Mesmo estas devem ser registradas sob a identidade própria do agente.
Escritas que devem ficar fora do agente nesta etapa incluem emitir reembolsos, alterar valores de fatura, aplicar descontos, editar formas de pagamento e alterar pagamento ou permissões de técnicos. Essas decisões cabem a pessoas com autoridade e contexto para tomá-las.
A aprovação em si precisa ser específica. Aprove a mudança exata mostrada na tela, com o horário atual do agendamento e o horário proposto lado a lado, e não uma instrução genérica como cuidar da agenda. O fluxo de aprovação no Slack é um lugar prático para isso, desde que o canal esteja restrito às pessoas autorizadas a decidir.
Quais limites precisam valer antes de a integração entrar em produção?
Quatro limites importam mais em uma integração com o ServiceTitan.
O primeiro é a atualidade dos dados. O agente trabalha com a agenda como estava na última leitura, e um despachante pode ter movido um serviço minutos antes. Cada alteração proposta deve reler o agendamento alvo logo antes de entrar na fila, e a tela de aprovação deve mostrar o estado atual, e não o estado do pedido original.
O segundo são as escritas duplicadas. Tempos limite de rede acontecem, e uma chamada de criação repetida pode agendar a mesma visita duas vezes. Cada requisição de criação deve carregar uma chave derivada da própria requisição, para que o sistema receptor reconheça a repetição em vez de criar um segundo registro. A Stripe documenta esse padrão em sua própria API, e o mesmo desenho se aplica às escritas de serviço de campo. As orientações de idempotência para ações de agentes detalham o assunto.
O terceiro são os limites de taxa. Uma revisão da manhã pode ler muitos serviços de uma vez. Agrupe as leituras, mantenha os resultados durante a janela de planejamento e recue quando o fornecedor devolver uma resposta de limitação, em vez de repetir a chamada em laço apertado.
O quarto são identidade e auditoria. Cada ação deve registrar qual identidade de agente a propôs, qual pessoa a aprovou, os valores antes e depois e o horário. As orientações de autorização da OWASP tratam esse tipo de controle de acesso aplicado e revisável como base mínima. Sem um rastro, um reagendamento errado é difícil de explicar ao cliente e difícil de corrigir.
O desenho das ferramentas importa tanto quanto a conexão. Dê a cada ferramenta um nome ligado à tarefa de despacho que ela atende, tipifique as entradas e devolva erros que digam o que deu errado e o que o agente pode fazer a seguir. As orientações de engenharia da Anthropic sobre como escrever ferramentas para agentes são uma referência útil para esse trabalho.
Qual é um plano seguro para a primeira integração?
- Escolha uma unidade de negócio e uma decisão de despacho para apoiar, como sinalizar serviços sem técnico antes da reunião da manhã.
- Peça ao administrador uma identidade de integração dedicada, limitada aos objetos de leitura da sua lista de campos.
- Construa ferramentas de leitura para serviços, agendamentos e técnicos, cada uma com entradas tipificadas, fusos horários explícitos e mensagens de erro claras.
- Rode o agente somente de leitura sobre dias passados e compare os alertas dele com o que os despachantes de fato trataram.
- Adicione uma ferramenta de escrita, como propor uma reatribuição, que apenas cria um pedido de aprovação em uma fila.
- Conecte a fila ao canal onde os despachantes já trabalham e defina o aprovador de cada tipo de ação.
- Ative as escritas aprovadas com chaves de idempotência e registre quem propôs, quem aprovou e os valores antes e depois.
- Revise as permissões e o registro de falhas em um calendário fixo, e amplie o escopo somente quando o critério de sucesso se sustentar nesse período.
Como fica um pedido de reagendamento na prática?
Cenário ilustrativo: em uma manhã movimentada, um técnico termina um serviço mais tarde do que o previsto. O agente de agendamento lê os compromissos da tarde, encontra dois que começariam antes de o técnico chegar e rascunha duas opções: uma janela posterior para um cliente e uma troca com um serviço sem técnico próximo. Nada muda ainda no ServiceTitan. O despachante vê as duas opções com os horários atuais, escolhe uma, e a escrita aprovada roda uma única vez sob sua chave de idempotência. Uma mensagem ao cliente é rascunhada à parte, e o despachante aprova o texto antes do envio. O registro mostra quem propôs a mudança, quem a aprovou e a janela anterior.
A Be Human trata esse problema definindo o papel antes de qualquer conexão ser construída. Uma primeira contratação nomeia um papel de despacho, os objetos e campos do ServiceTitan que ele pode ler, as ações de escrita que pode propor, o aprovador de cada ação e um critério de sucesso observável. Depois, a operação gerenciada mantém a integração funcionando ao longo do tempo: monitorando chamadas com falha, executando avaliações recorrentes com decisões reais de despacho, revisando permissões quando módulos ou equipes mudam, respondendo a incidentes quando uma escrita dá errado e fazendo alterações controladas nas ferramentas. O serviço é entregue remotamente, em português ou em inglês.
Se você não tem certeza de qual tarefa de despacho deve vir primeiro, o diagnóstico gratuito de IA da Be Human pode ajudar a encontrar a primeira tarefa que vale entregar a um agente.
Perguntas frequentes
Um agente de IA pode escrever diretamente no ServiceTitan? Pode ser possível, dependendo das credenciais e dos módulos que sua conta expõe, mas o desenho mais seguro deixa o agente propor escritas em uma fila de aprovação. Escritas diretas podem vir depois, para ações de baixo risco, como observações internas, quando o rastro de auditoria e o critério de sucesso tiverem se sustentado durante um período de revisão.
Quais dados do ServiceTitan nunca devem ir para um agente na primeira versão? Dados de pagamento, referências de cartão ou conta bancária, valor-hora dos técnicos, linhas de margem e custo e observações em texto livre que possam conter informações privadas ou de acesso devem ficar de fora. Se um campo não muda a próxima decisão de despacho, deixe-o de fora. Adicione campos depois apenas com um motivo por escrito.
Quanto tempo leva a primeira integração? O prazo depende de quantas unidades de negócio e módulos estão envolvidos, da rapidez com que as credenciais internas são aprovadas e do histórico que você quer que o agente teste. Um piloto restrito, somente de leitura, em uma unidade de negócio costuma ser a forma mais rápida de entender como seus dados realmente são.
O que acontece se o agente propuser um reagendamento errado? Nada muda sem aprovação, então o despachante pode rejeitar a proposta antes que ela chegue à agenda. Se uma mudança aprovada ainda causar problema, o registro de auditoria mostra quem propôs e quem aprovou, e a resposta a incidentes pode reverter a mudança e corrigir a ferramenta que gerou o erro.
Seu próximo passo
Descubra primeiro onde um agente de IA cabe na sua empresa.
Faça o diagnóstico gratuito de IA da Be Human. Algumas perguntas sobre o seu trabalho mostram qual tarefa entregar primeiro a um agente, o que ele precisa saber e onde uma pessoa aprova.
Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.


