SyncroCentral de Ajuda
Nenhum resultado encontrado
Acessar Syncro

Tools do agente

Atualizado em 14 de maio de 2026

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)

  1. Marque as desejadas.

  2. 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:

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

Artigos relacionados