Pular para o conteúdo
Triadeflow Docs

agent-agendamento

Especificação completa do agente de Agendamento.

Resumo executivo

Agenda, remarca, cancela e confirma compromissos via WhatsApp. Reduz no-show em 40-60% com lembretes ativos 24h e 2h antes. Integra com Google Calendar, Outlook ou sistemas verticais (Doctoralia, Trinks, AgendaPro). Usa modelo Haiku — barato e suficiente para tarefa estruturada.

Mercado e ICP

Setores ideais

  • Saúde (clínicas, terapeutas, dentistas, fisioterapeutas)
  • Beleza (salões, barbearias, esmalterias, clínicas de estética)
  • Fitness (personal trainers, pilates, crossfit)
  • Consultoria (agendamento de calls)
  • Educação presencial (aulas particulares)
  • Pet care (veterinários, banho/tosa)

Cliente NÃO ideal

  • Agendas extremamente complexas com múltiplos profissionais e regras especiais (mais barato custom)
  • Volume muito baixo (< 50 agendamentos/mês não justifica)

Casos de uso típicos

Caso 1: Clínica (Dra. Milena)

  • Paciente quer agendar consulta
  • Agente pergunta tipo (primeira vez ou retorno)
  • Consulta disponibilidade da Dra
  • Propõe 2-3 horários
  • Confirma e cria evento
  • Envia lembretes automáticos

Caso 2: Salão de beleza

  • Cliente quer hidratação
  • Agente pergunta dia preferido
  • Consulta disponibilidade da profissional preferida
  • Confirma e bloqueia slot
  • Cliente recebe lembrete 24h antes

Caso 3: Personal trainer

  • Aluno quer agendar próxima sessão
  • Agente já sabe preferência (manhã, terça/quinta)
  • Mostra slots disponíveis na próxima semana
  • Confirma

Estrutura específica do código

agent-agendamento/
├── src/
│   ├── prompts/
│   │   ├── system_base.md
│   │   └── fragments/
│   │       ├── tipos_servico.md
│   │       ├── politica_cancelamento.md
│   │       └── lembrete_preparo.md
│   │
│   ├── tools/
│   │   ├── consultar_disponibilidade.py
│   │   ├── agendar_compromisso.py
│   │   ├── remarcar_compromisso.py
│   │   ├── cancelar_compromisso.py
│   │   ├── confirmar_presenca.py
│   │   ├── enviar_lembrete_preparo.py
│   │   └── _registry.py
│   │
│   ├── flows/
│   │   ├── agendamento.py
│   │   ├── remarcacao.py
│   │   ├── cancelamento.py
│   │   ├── confirmacao_24h.py
│   │   └── confirmacao_2h.py
│   │
│   ├── jobs/                         ← Cron jobs
│   │   ├── lembrete_24h.py
│   │   ├── lembrete_2h.py
│   │   └── lembrete_preparo.py
│   │
│   └── config/
│       └── default_config.yaml
│
└── tenants/_template/
    ├── config.yaml                   ← Tem seção 'agendamento' detalhada
    └── knowledge/
        ├── profissionais.md          ← Lista, especialidades
        ├── servicos.md               ← Tipos de procedimento
        ├── localizacao.md            ← Endereço, instruções de chegada
        ├── preparos.md               ← Por tipo de serviço
        └── politicas.md              ← Cancelamento, atraso, etc

Tools específicas

src/tools/consultar_disponibilidade.py
@tool
@trace_tool("consultar_disponibilidade")
async def consultar_disponibilidade(
    profissional_id: Optional[str] = None,
    tipo_servico: Optional[str] = None,
    data_inicio: Optional[str] = None,
    dias_a_buscar: int = 7,
    *,
    tenant: dict
) -> str:
    """
    Consulta horários disponíveis.


    USE QUANDO: cliente quer agendar e precisa ver opções.
    """
    calendar = CalendarFactory.create(tenant)


    # Determina serviço (duracão e buffer)
    servico_config = tenant.agendamento.tipos_servico.get(tipo_servico, {})
    duracao = servico_config.get("duracao_minutos", 30)
    buffer = servico_config.get("buffer_minutos", 0)


    # Determina horário comercial
    horario = tenant.horario


    # Busca slots livres
    slots = await calendar.find_available_slots(
        calendar_id=tenant.agendamento.profissionais[profissional_id]["calendar_id"],
        duration_minutes=duracao + buffer,
        start_date=data_inicio or "today",
        days=dias_a_buscar,
        business_hours=horario,
        max_slots=5
    )


    if not slots:
        return "Nenhum horário disponível nos próximos {dias_a_buscar} dias. Posso verificar mais dias?"


    return format_slots_for_user(slots[:3])  # mostra apenas 3




# src/tools/agendar_compromisso.py
@tool
@trace_tool("agendar_compromisso")
async def agendar_compromisso(
    cliente_telefone: str,
    cliente_nome: str,
    profissional_id: str,
    tipo_servico: str,
    data_hora_iso: str,
    observacoes: Optional[str] = None,
    *,
    tenant: dict
) -> str:
    """
    Cria evento na agenda do profissional.


    USE QUANDO: cliente confirmou horário específico.
    """
    calendar = CalendarFactory.create(tenant)
    profissional = tenant.agendamento.profissionais[profissional_id]
    servico = tenant.agendamento.tipos_servico[tipo_servico]


    # Valida que slot ainda está livre (race condition)
    is_available = await calendar.check_slot_available(
        calendar_id=profissional.calendar_id,
        start=data_hora_iso,
        duration_minutes=servico.duracao_minutos
    )


    if not is_available:
        return "Esse horário acabou de ser ocupado. Vou verificar outras opções."


    # Cria evento
    event = await calendar.create_event(
        calendar_id=profissional.calendar_id,
        title=f"{tipo_servico} — {cliente_nome}",
        description=f"Telefone: {cliente_telefone}\n{observacoes or ''}",
        start=data_hora_iso,
        duration_minutes=servico.duracao_minutos,
    )


    # Registra no CRM
    crm = CRMFactory.create(tenant)
    await crm.add_appointment(
        client_phone=cliente_telefone,
        appointment_id=event.id,
        date=data_hora_iso,
        service=tipo_servico
    )


    # Agenda lembretes (jobs)
    await schedule_reminder(event.id, tenant.tenant_id, hours_before=24)
    await schedule_reminder(event.id, tenant.tenant_id, hours_before=2)


    # Se houver preparo, agenda envio
    if servico.requer_preparo:
        await schedule_preparo_reminder(event.id, tenant.tenant_id, hours_before=48)


    return f"Agendado: {format_datetime_pt(data_hora_iso)} com {profissional.nome}."




# src/tools/cancelar_compromisso.py
@tool
@trace_tool("cancelar_compromisso")
async def cancelar_compromisso(
    appointment_id: str,
    motivo: Optional[str] = None,
    *,
    tenant: dict
) -> str:
    """
    Cancela compromisso, respeitando política de antecedência.
    """
    calendar = CalendarFactory.create(tenant)
    event = await calendar.get_event(appointment_id)


    # Verifica antecedência
    horas_ate_evento = (event.start - now()).total_hours()
    antec_minima = tenant.agendamento.politica_cancelamento.antecedencia_minima_horas


    if horas_ate_evento < antec_minima:
        return (
            f"Cancelamento com menos de {antec_minima}h. "
            f"Conforme política, pode haver cobrança. "
            f"Quer confirmar mesmo assim?"
        )


    await calendar.delete_event(appointment_id)


    return f"Cancelado. Quer reagendar para outro dia?"

Job: Lembrete 24h

src/jobs/lembrete_24h.py
"""
Cron job que roda a cada hora.
Encontra agendamentos para amanhã e dispara lembrete.
"""
async def run_lembrete_24h():
    """Roda a cada hora, busca agendamentos para 24h à frente."""


    for tenant_id in get_active_tenants():
        tenant = TenantLoader.load(tenant_id)


        if not tenant.features.lembrete_24h:
            continue


        calendar = CalendarFactory.create(tenant)
        appointments = await calendar.list_events(
            start=now() + timedelta(hours=23),
            end=now() + timedelta(hours=25)
        )


        for appt in appointments:
            # Skip se já foi lembrado
            if await was_reminded(appt.id, "24h"):
                continue


            telefone = extract_phone_from_event(appt)
            if not telefone:
                continue


            messaging = MessagingFactory.create(tenant)
            await messaging.send_text(
                to=telefone,
                text=tenant.agendamento.mensagens.lembrete_24h.format(
                    data=format_pt(appt.start),
                    profissional=appt.organizer.name,
                    endereco=tenant.endereco
                )
            )


            await mark_reminded(appt.id, "24h")

System prompt template

# Identidade
Você é {{agente_nome}}, {{agente_cargo}} da {{nome_empresa}}.
Atende clientes via WhatsApp para gerenciamento de agenda.


# Empresa
{{empresa_descricao}}


# Seu objetivo
Agendar, remarcar, cancelar ou confirmar compromissos com agilidade.
Sempre confirmar antes de criar/alterar/deletar.


# Como você atua


## Para agendamento novo:
1. Identifique tipo de serviço desejado
2. Pergunte preferência de profissional (se aplicável)
3. Pergunte preferência de dia/horário
4. Use consultar_disponibilidade para ver opções
5. Apresente 2-3 horários disponíveis
6. Confirme escolha
7. Use agendar_compromisso


## Para remarcação:
1. Identifique compromisso atual
2. Pergunte novo dia/horário
3. Verifique disponibilidade
4. Confirme antes de remarcar


## Para cancelamento:
1. Identifique compromisso
2. Avise sobre política de antecedência (se < {{antec_minima}}h, pode cobrar)
3. Confirme intenção
4. Cancele e ofereça reagendamento


## Para confirmação 24h/2h antes:
1. Pergunte: "Confirma sua presença?"
2. Se sim → marca confirmed
3. Se não consegue → oferece remarcar


# Suas ferramentas
- consultar_disponibilidade
- agendar_compromisso
- remarcar_compromisso
- cancelar_compromisso
- confirmar_presenca
- enviar_lembrete_preparo


# Regras invioláveis
- Sempre confirme antes de criar/alterar/cancelar
- Respeite buffer entre atendimentos ({{buffer_minutos}}min)
- Não sobreponha horários
- Política de antecedência: {{antec_minima}}h mínimas para cancelar sem custo
- Se cliente faltou (no-show), avise política e ofereça reagendamento
- Para emergências, sempre handoff humano


# Mensagens padrão


## Confirmação de agendamento
"Pronto! {data} às {hora} com {profissional}.
Endereço: {endereco}
Vou te lembrar 24h antes. Qualquer coisa, é só me avisar."


## Lembrete 24h
"Oi! Lembrando que amanhã ({data}) às {hora} você tem {servico} com {profissional}.
Endereço: {endereco}
Confirma sua presença?"


## Lembrete 2h
"Oi! Te esperamos em 2h ({hora}) com {profissional}.
Endereço: {endereco}
Já está vindo?"


# Tom
Profissional, ágil, organizado. Não enrole muito.
{{include: fragments/tom_direto.md}}

Configuração default

agent_type: agendamento
default_model: claude-haiku-4-5      # Tarefa estruturada, Haiku é suficiente
default_temperature: 0.3              # Baixa para previsibilidade


agendamento:
  duracao_padrao_minutos: 30
  buffer_padrao_minutos: 10


  politica_cancelamento:
    antecedencia_minima_horas: 24
    cobranca_no_show_percent: 50      # cobrar 50% se não comparecer


  lembrete_24h:
    enabled: true
    horario_envio_padrao: "18:00"     # noite anterior


  lembrete_2h:
    enabled: true


  preparo:
    enviar_h_antes: 48                # 2 dias antes


  confirmacao_ativa:
    requer_resposta_24h_antes: true
    se_nao_responder: "manter_agendamento"


response:
  delay_between_messages_ms: 1000     # Ágil
  max_messages_per_minute: 30

KPIs

MétricaMeta
Taxa de agendamento bem-sucedido> 90%
Redução de no-show-40 a -60%
Taxa de remarcação proativa> 80%
Ocupação da agendaCliente-dependente
Tempo médio de agendamento< 2 min

Pricing

ItemFaixa
SetupR$ 3.500 a R$ 5.500
MensalidadeR$ 900 a R$ 1.500
Volume APIBaixo (Haiku) + 30%

Tempo de implementação

FaseDuração
Levantamento de profissionais e serviços2 dias
Integração calendar3 dias
Customização prompts2 dias
Configuração de jobs (lembretes)3 dias
Testes com agendamentos reais3 dias
Calibração5 dias
Total primeiro cliente2-3 semanas
Clientes seguintes1 semana