> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiraa.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Tarefas

> Trabalho humano delegado pelo agente IA, por automação ou criado manualmente — vinculado ao cliente, com prazo e responsável

As **Tarefas** são a ponte entre IA e time humano. Quando o agente identifica algo que precisa de mão humana — uma pendência, uma confirmação, uma conferência — ele cria uma tarefa direto para o responsável daquele cliente, com prazo, descrição e contexto.

Saímos do mundo "IA conversa, humano descobre depois": agora a IA **despacha trabalho para a fila do humano** exatamente como um SDR despacha para um vendedor.

<Info>
  Acesse em **CRM > Tarefas**. Cada tarefa também aparece embutida na ficha do cliente vinculado.
</Info>

***

## Tarefa vs. Atividade vs. Agendamento

Confusão comum — a distinção é importante:

|                  | **Tarefa**                           | **Atividade**               | **Agendamento (Calendar)**                           |
| ---------------- | ------------------------------------ | --------------------------- | ---------------------------------------------------- |
| **O que é**      | Trabalho humano a fazer              | Evento que já aconteceu     | Compromisso no Google Calendar                       |
| **Executor**     | Pessoa do time                       | Histórico (ninguém executa) | Cliente / colaborador                                |
| **Estado**       | `aberta` / `concluída` / `cancelada` | Imutável                    | Calendar sync                                        |
| **Onde aparece** | `/tasks` + ficha do cliente          | Timeline do cliente         | Google Calendar + ferramenta `Agendamento` do agente |

<Tip>
  Regra simples: **tarefa = humano**. **Agendamento = compromisso no Calendar**. **Retorno = a IA volta a falar** (veja [Retornos](/callbacks)).
</Tip>

***

## Anatomia de uma tarefa

| Campo           | Tipo                                 | Obrigatório | Notas                                                         |
| --------------- | ------------------------------------ | ----------- | ------------------------------------------------------------- |
| **Título**      | texto (até 255)                      | ✓           | Renderizável (com `{{variavel}}`) quando criada por automação |
| **Descrição**   | texto (até 2000)                     |             | Idem                                                          |
| **Responsável** | pessoa do time                       | ✓           | Resolução automática em fallback (veja abaixo)                |
| **Cliente**     | vínculo                              |             | Habilita visibilidade na ficha + timeline                     |
| **Prazo**       | data/hora                            |             | Opcional; aparece como "Vence em..."                          |
| **Status**      | `aberta` / `concluída` / `cancelada` | ✓           | Pode ir e voltar livremente                                   |

Status flui em qualquer direção: `aberta` ⇄ `concluída` / `cancelada`. Reabrir uma tarefa concluída limpa a data de conclusão.

***

## Quatro formas de criar uma tarefa

<CardGroup cols={2}>
  <Card title="Manualmente" icon="hand-pointer">
    Botão **Nova tarefa** em `/tasks` ou na ficha do cliente. Você escolhe título, descrição, responsável, cliente e prazo.
  </Card>

  <Card title="Pelo agente de voz" icon="microphone">
    Durante uma chamada, o agente usa a tool `create_task` ([CRM Action](/tools)) quando identifica uma pendência humana.
  </Card>

  <Card title="Pelo agente WhatsApp" icon="whatsapp">
    Mesma tool `create_task` — funciona em chats por texto também.
  </Card>

  <Card title="Por automação" icon="diagram-project">
    Bloco **Criar tarefa** dentro de uma [automação](/automations). Renderiza variáveis do cliente nos campos.
  </Card>
</CardGroup>

### Exemplo: agente cria tarefa durante a conversa

> **Cliente** (na call): "Preciso ver com meu chefe e te retorno na sexta."
>
> **Agente** chama `create_task(title="Confirmar interesse com chefe — {{cliente_nome}}", due_in_seconds=259200)`.
>
> Resultado: aparece na fila do responsável do cliente, com prazo de 3 dias, vinculada ao cliente, registrada na timeline.

### Exemplo: bloco em automação

Numa régua de cobrança, quando o agente detecta promessa de pagamento:

```
... → Condicional (disposition == "promessa_pagamento")
      └─ true → Criar tarefa
                  título: "Confirmar pagamento amanhã - {{cliente_nome}}"
                  descrição: "Cliente prometeu pagar via {{custom.forma_pagamento}}"
                  prazo: 24h
```

***

## Resolução do responsável (fallback automático)

Em todas as origens, o sistema tenta na ordem:

<Steps>
  <Step title="Responsável informado explicitamente">
    Se o usuário/agente/automação especificou um `responsável`, usa esse.
  </Step>

  <Step title="Responsável padrão da tool">
    Se a tool `create_task` foi configurada com **responsável padrão**, usa esse (criação por agente).
  </Step>

  <Step title="Responsável do cliente">
    Usa o campo `assigned_to` do cliente (configurado na ficha).
  </Step>

  <Step title="Falha ou skip">
    Se nada resolve:

    * Por **agente** → erro retornado para o agente.
    * Por **automação** → step marca `skipped` (run continua o fluxo).
  </Step>
</Steps>

<Warning>
  O comportamento de **skip em vez de falhar** no automation é proposital: workflow não pode parar porque uma delegação não tem dono. A run loga e segue.
</Warning>

***

## A página `/tasks`

Kanban com 3 colunas:

| Coluna         | O que mostra                                                |
| -------------- | ----------------------------------------------------------- |
| **Abertas**    | Tarefas pendentes (com badge de prazo se vencendo/atrasada) |
| **Concluídas** | Tarefas finalizadas — com data de conclusão                 |
| **Canceladas** | Tarefas explicitamente canceladas                           |

**Ações disponíveis:**

* Drag-and-drop entre colunas para mudar status.
* Filtros: busca textual (título/descrição/cliente), responsável, cliente.
* Editar inline: título, descrição, responsável, prazo.

***

## Embed na ficha do cliente

Toda ficha de cliente (`/clients/[id]`) tem uma seção **Tarefas** que mostra as últimas 50 tarefas vinculadas:

* **Ordenação**: abertas primeiro, depois por prazo.
* **Ações inline**: marcar concluída, cancelar, reabrir, editar prazo.
* **Sincronizado** com `/tasks`: mudanças refletem nas duas telas em tempo real.
* **Botão "Nova tarefa"**: cria já vinculada ao cliente atual.

Eventos de criação e conclusão também aparecem na **timeline** e no **calendário** do cliente como atividades `task_created` / `task_completed`.

***

## Permissões

| Ação                                  | Quem pode                                  |
| ------------------------------------- | ------------------------------------------ |
| **Criar tarefa com cliente**          | Quem tem permissão para ver o cliente      |
| **Criar tarefa sem cliente**          | Auto-atribuição apenas (a menos que admin) |
| **Atualizar/fechar/cancelar/reabrir** | Admin OR responsável OR criador            |
| **Reatribuir tarefa sem cliente**     | Apenas para si mesmo (a menos que admin)   |
| **Reatribuir tarefa com cliente**     | Quem tem permissão de ver o cliente        |

***

## Como configurar o agente para criar tarefas

<Steps>
  <Step title="Crie a tool create_task">
    Em **Studio de IA > Tools**, clique em **Nova tool** e escolha tipo **CRM Action**.
  </Step>

  <Step title="Selecione a action create_task">
    No painel de configuração, escolha a action `create_task`.
  </Step>

  <Step title="Defina quando o agente deve usar">
    Campo **Quando usar**: descreva os cenários em que o agente deve abrir tarefa (ex: "use sempre que o cliente disser que precisa confirmar com terceiros, mencionar uma pendência ou pedir conferência humana").
  </Step>

  <Step title="(Opcional) Responsável padrão">
    Configure um `default_assignee_user_id` para usar quando o agente não conseguir determinar o responsável.
  </Step>

  <Step title="Vincule a tool ao agente">
    Em **Studio de IA > Agentes**, abra o agente e adicione a tool em **Recursos vinculáveis**.
  </Step>
</Steps>

<Tip>
  Funciona igual para agente de voz e agente WhatsApp — a mesma tool serve aos dois.
</Tip>

***

## Como configurar uma automação que cria tarefa

Use o bloco **Criar tarefa** no [construtor visual](/automations):

| Campo                                     | Aceita                                   |
| ----------------------------------------- | ---------------------------------------- |
| **Título** (template)                     | Texto com `{{variaveis}}`                |
| **Descrição** (template)                  | Texto com `{{variaveis}}`                |
| **Responsável** (opcional)                | UUID de usuário — se vazio, usa fallback |
| **Prazo** (em segundos a partir de agora) | 60 a 2.592.000 (= 30 dias)               |

Variáveis suportadas: `{{cliente_nome}}`, `{{cliente_empresa}}`, `{{custom.cpf}}`, `{{context.disposition}}`, etc. Veja a [seção de templating](/automations#variáveis-em-parâmetros-templating).

***

## Próximos passos

<CardGroup cols={2}>
  <Card title="Automações" icon="diagram-project" href="/automations">
    Crie réguas que disparam tarefas automaticamente
  </Card>

  <Card title="Retornos" icon="arrow-rotate-left" href="/callbacks">
    A outra ponta: quando o "depois" é o próprio agente voltar
  </Card>

  <Card title="Tools (CRM Action)" icon="wrench" href="/tools">
    Configure `create_task` e outras ações que o agente pode usar
  </Card>

  <Card title="Cliente 360" icon="user" href="/clients">
    Veja onde as tarefas aparecem na ficha do cliente
  </Card>
</CardGroup>