Tools do agente

Tools (ferramentas) são as ações que o agente IA executa no CRM durante a conversa. É o que diferencia agente IA de chatbot básico — em vez de só responder, o agente age: move lead pra etapa, adiciona tag, cria nota, transfere pra humano, agenda reunião.

O Syncro implementa isso via function calling — durante a resposta, o LLM decide se uma ação é apropriada e o sistema executa. Tudo é controlado: o agente só usa tools que você explicitamente habilitou.

Pré-requisitos

-Agente IA criado. -Permissão de admin ou manager.

Habilitar tools no agente

1.Acesse /ia/agentes/{id}/editar. 2.Localize a seção Ferramentas disponíveis (ou no Passo 4 do wizard). 3.Você vê toggles pra cada tool: -Mover leads entre etapas (enable_pipeline_tool) -Adicionar tags (enable_tags_tool) -Notificar intenção de compra (enable_intent_notify) -Agendar reuniões (enable_calendar_tool) -Catálogo de produtos (enable_products_tool) 4.Marque as desejadas. 5.Salve.

Tools disponíveis (8 principais)

1. set_stage — Mover lead entre etapas

Habilita por: toggle "Mover leads entre etapas" (enable_pipeline_tool).

O que faz: agente move o lead pra outra etapa do funil quando detecta avanço (qualificado, proposta enviada, fechou).

Exemplo de conversa: -Cliente: "Quero comprar! Aceita cartão?" -Agente: "Aceitamos sim! Pode parcelar em até 12x. Vou te enviar o link de pagamento." -Tool executada: set_stage(stage_id=4) — move lead pra "Negociação".

Configuração: precisa listar etapas no campo "Etapas da Conversa" (Passo 4 do wizard) com nomes e descrições. Agente usa isso pra decidir qual etapa.

2. add_tags — Adicionar tags

Habilita por: toggle "Adicionar tags" (enable_tags_tool).

O que faz: agente categoriza leads adicionando tags conforme detecta perfil/interesse.

Exemplo: -Cliente: "Sou empresa B2B, preciso emitir nota fiscal e ter contrato anual." -Tool executada: add_tags(tags=["b2b", "contrato-anual", "interesse-alto"]).

3. update_lead — Atualizar dados

Habilita por: implícito (sempre disponível em algumas configurações).

O que faz: atualiza campos do lead (nome, email, empresa, valor, aniversário) conforme cliente fornece informação.

Exemplo: -Cliente: "Sou João Silva, da empresa ACME, email [email protected]" -Tool: update_lead(field="email", value="[email protected]"), update_lead(field="company", value="ACME").

4. create_note — Criar nota

O que faz: agente registra observações importantes pra equipe humana ler depois.

Exemplo: -Cliente: "Preciso receber proposta até sexta-feira pra apresentar pro meu chefe." -Tool: create_note(body="Cliente precisa de proposta até sexta. Decisor: chefe dele.").

Nota fica visível no perfil do lead.

5. update_custom_field — Atualizar campo personalizado

O que faz: atualiza valores de campos personalizados que você criou. Útil pra capturar dados específicos do seu negócio.

Exemplo: campo personalizado "Setor" tipo Select com opções (Tecnologia, Saúde, Educação). -Cliente: "Trabalho em escola técnica" -Tool: update_custom_field(field="setor", value="Educação").

6. assign_human — Transferir pra humano

O que faz: termina o atendimento da IA e atribui a um usuário humano.

Quando o agente usa: -Cliente pediu falar com humano ("Quero falar com alguém"). -IA não consegue resolver (assunto fora do escopo). -Detectou alta intenção e quer fechar com humano. -Configuração transfer_to_user_id ou transfer_to_department_id define pra quem vai.

Exemplo: -Cliente: "Quero negociar desconto de 30%." -Agente: "Entendo! Vou te transferir pro nosso atendente que pode autorizar descontos especiais." -Tool executada: assign_human → conversa atribuída.

Dica: configure no agente os campos transfer_to_user_id ou transfer_to_department_id pra que a transferência vá pro lugar certo (não fica na fila genérica).

7. send_media — Enviar mídia

O que faz: envia arquivo do catálogo de mídia do agente (uploaded em /ia/agentes/{id}/editar → seção Mídias).

Exemplo: -Cliente: "Tem foto do produto?" -Tool: send_media(media_id=12) — envia a foto cadastrada como media_id=12.

Pra usar, suba mídias previamente no agente (PNG/JPG/PDF) e o agente consulta.

8. notify_intent — Notificar intenção de compra

Habilita por: toggle "Notificar intenção de compra" (enable_intent_notify).

O que faz: dispara notificação interna pra equipe quando detecta forte sinal de compra.

Exemplo: -Cliente: "Posso pagar por PIX agora? Quero finalizar." -Tool: notify_intent(intent="buy", context="Cliente quer pagar PIX agora"). -Equipe recebe alerta: " Lead pronto pra fechar — verificar".

Útil pra gestores acompanharem leads quentes em tempo real.

Tools de Calendário (Google Calendar)

Se você ativa "Agendar reuniões" (enable_calendar_tool), o agente ganha 4 tools de calendário:

9. check_calendar_availability

Verifica slots livres na agenda em intervalo específico.

10. calendar_create

Cria evento no Google Calendar.

Exemplo: -Cliente: "Pode marcar uma reunião terça às 15h?" -Tool: check_calendar_availability(start="2026-05-13T15:00", end="2026-05-13T16:00") → vê se livre -Se sim: calendar_create(title="Reunião com João", start="2026-05-13T15:00", end="2026-05-13T16:00", attendees=["[email protected]"]).

11. calendar_reschedule

Move evento existente.

12. calendar_cancel

Cancela evento.

Dica: configure calendar_id no agente pra apontar qual agenda do Google usar. Veja Sincronizar Google Calendar.

Catálogo de Produtos (enable_products_tool)

Se você ativa, o agente pode consultar o catálogo do CRM (Configurações → Produtos):

-Buscar produto por nome. -Sugerir produtos relacionados. -Informar preço, descrição, estoque.

Útil pra agentes de vendas e-commerce que precisam recomendar produtos.

Como o agente decide usar tools

O LLM tem o system prompt com:

-Lista de tools disponíveis (apenas as habilitadas). -Schema de cada tool (parâmetros esperados). -Persona + base de conhecimento + contexto da conversa.

A cada mensagem do cliente, o LLM decide se alguma tool deve ser executada e com quais parâmetros. Resposta vem em formato JSON estruturado:

{
 "reply": "Texto que vai pro cliente",
 "actions": [
 {"type": "set_stage", "stage_id": 5},
 {"type": "add_tags", "tags": ["interessado", "vip"]}
 ]
}

Sistema processa cada action em paralelo após enviar reply pro cliente.

Verificar tools executadas

Toda tool execution é registrada na timeline do lead + na timeline da conversa:

-"Camila moveu lead pra Qualificação" -"Camila adicionou tags: vip, b2b" -"Camila criou nota: Cliente quer proposta até sexta" -"Camila transferiu pra Pedro"

Você consegue auditar tudo que a IA fez.

Tools que falham

Se uma tool falha (lead inválido, etapa inexistente, cliente bloqueou):

-Erro é logado mas não interrompe a resposta da IA. -Cliente recebe a mensagem texto normalmente. -Tool falhada aparece com badge na timeline.

Combinação de tools no mesmo turno

O agente pode executar múltiplas tools numa só resposta:

{
 "reply": "Que ótimo! Vou anotar tudo e te encaminhar pra equipe...",
 "actions": [
 {"type": "update_lead", "field": "email", "value": "[email protected]"},
 {"type": "add_tags", "tags": ["interessado", "decisor"]},
 {"type": "create_note", "body": "Decisor confirmou interesse, vai apresentar pro time hoje"},
 {"type": "set_stage", "stage_id": 4},
 {"type": "assign_human"}
 ]
}

5 ações executadas em sequência atomicamente.

Boas práticas

1. Habilite tools gradualmente

Não ative tudo de cara. Comece com:

-Update_lead + add_tags — capturam dados e organizam. -Set_stage quando o agente já entende seu funil. -Assign_human sempre habilite (importante).

Depois adicione Calendar e Notify_intent quando necessário.

2. Configure bem etapas e transferência

Tools dependem de dados configurados:

-set_stage precisa de etapas listadas no agente. -assign_human precisa de transfer_to_user_id ou departamento padrão. -calendar_create precisa de Google Calendar conectado.

3. Teste antes de ativar

Use o chat de teste lateral pra validar que o agente:

-Move pra etapa certa. -Adiciona tags relevantes. -Não executa tools demais (parando de responder com texto).

4. Monitore a timeline

Periodicamente, abra leads atendidos pela IA e veja a timeline. Se a IA está executando coisas estranhas, ajuste:

-Persona / Comportamento esperado (no agente). -Restrições explícitas ("NUNCA mude etapa sem antes confirmar com o cliente").

Limitações conhecidas

-Não há tool pra apagar lead (intencionalmente — perigoso). -Não há tool pra acessar dados de outros leads (privacy). -Tools são limitadas ao tenant — agente não vê dados de outros clientes. -Sem tool de busca interna complexa hoje (ex: "qual lead vendeu mais este mês").

Próximos passos

-Pra entender follow-up (que também usa tools), veja Follow-up smart/template/off. -Pra agendar reuniões, certifique Google Calendar conectado.

Artigos relacionados

-Criar um agente de IA -Base de conhecimento (RAG) -Follow-up smart/template/off -Sincronizar Google Calendar