# Operations Tasks — Master Implementation Guide (LLM-Ready) > O lugar onde os agentes trabalham. Cada agente tem instruções com versões, > um modelo (DeepSeek V4.1 Flash ou Qwen3.8 Flash, pela OpenRouter) e as > conexões MCP que pode usar, com uma regra por ferramenta: **Livre**, > **Confirma** ou **Só humano**. O que só uma pessoa decide vira um > **pedido**; cada execução fica registrada, com o custo medido pela OpenRouter; > os eventos das suas ferramentas viram painéis e conferências; um botão pausa > todos os agentes. > > Este arquivo é a documentação para agentes. **Leia a seção 11 antes de > prometer qualquer coisa**: ela diz o que o produto não faz. Worker (API, MCP, entrada de eventos): https://tasks.worker.myoperations.click Painel: https://tasks.dashboard.myoperations.click Servidor MCP: https://tasks.worker.myoperations.click/mcp — ver a seção 8. O mapa da linha (todos os produtos, login): https://myoperations.click/llms.txt ## 0. Estado e credenciais — leia antes de tudo - **No ar desde 07/10/2026.** `GET https://tasks.worker.myoperations.click/status` responde `{"service":"operations-tasks",…}` com o estado do banco, dos modelos, do WhatsApp e dos agentes. - **WhatsApp: construído, ainda não no ar.** Foi testado contra uma Meta simulada; só liga quando a Meta aprovar o aplicativo, verificar o negócio e aprovar o modelo de mensagem do Tasks. O `/status` mostra `whatsapp: not_configured` até lá. Seção 9. - **Login:** o Auth da linha (`https://auth.worker.myoperations.click`, aplicação Operations), com código por e-mail. Mesmo login, autorização por produto. Passo humano obrigatório: a pessoa lê um código no e-mail e o informa. Não tente contornar. - **Chave da conta:** `tk_…`, criada no painel (só pela sessão de uma pessoa) e mostrada uma vez. Vale para a API (`Authorization: Bearer tk_…`): criar pedidos, relatar execuções de agentes de fora, mandar números. **É recusada no `/mcp`**, e as rotas de responder, retomar e apagar um painel a recusam (403). Fica só no servidor: nunca no HTML, nunca num repositório. - **MCP:** OAuth, com o mesmo login (seção 8). Não usa a `tk_`. - **Preço:** não há preço público e nada é cobrado. Não cite valor, plano, franquia em minutos nem "grátis". Se perguntarem: "Ainda não há planos, e nada é cobrado." Sem credencial de verdade, **pare e peça**. Não gere código com `tk_xxx` de placeholder e diga que terminou. ## 1. Modelo mental - **Agente** — instruções em português (salvar cria uma versão nova; cada execução guarda a versão com que rodou), um **modelo**, as **conexões** que pode usar, **gatilhos** (um horário, um evento de entrada, à mão, ou a resposta a um pedido dele) e **limites**: passos por execução (de 1 a 200, padrão 30), teto de gasto por dia, uma execução por vez e uma na fila. No teto de gasto, o agente espera o dia seguinte. - **Modelo** — só dois, pela OpenRouter: `deepseek/deepseek-v4.1-flash` (padrão) e `qwen/qwen3.8-flash`. Um modelo fora da lista é recusado. - **Conexão** — um servidor MCP (endereço e OAuth, chave ou nenhum login). Ao conectar, o Tasks descobre as ferramentas. Cada ferramenta tem uma regra por conexão, que vale para todos os agentes: - **Livre** — o agente usa sozinho; - **Confirma** — a ação vira um pedido de aprovação e só executa depois que uma pessoa aprova; - **Só humano** — a ferramenta nunca é mandada ao modelo. Toda ferramenta nova chega como **Confirma**. A conexão do próprio Tasks vem pronta e não sai. - **Pedido** — o que só uma pessoa decide. Tipos: Gravar, Aprovar, Decidir, Revisar. Estados: Aguardando, Respondido, Recusado, Vencido. Sem prazo, vence em 7 dias. A resposta de um Gravar é um link `https://` colado. Um pedido pode ser uma fase de uma cadeia. Anexo: um link, um texto ou uma referência (não há envio de arquivo). - **Execução** — os passos, as saídas, o custo e o erro inteiro. Estados: na fila, rodando, esperando, concluída, falhou, parada. Uma execução que falhou ou parou pode ser tentada de novo uma vez. - **Pausa** — "Pausar todos os agentes" faz cada execução parar no passo seguinte. Retomar é só da sessão de uma pessoa. ## 2. Custo — medido, não informado - O custo de cada passo é o `usage.cost` que a OpenRouter devolveu na própria chamada, guardado em milionésimos de dólar. Nunca uma estimativa. - Agente que roda **fora** do Tasks relata o próprio custo (`POST /api/runs` ou `tasks_report_run`); a execução diz "informado pelo agente". ## 3. Responder é de uma pessoa - `POST /api/requests/:id/answer` aceita **só a sessão de uma pessoa**. Token OAuth e chave `tk_` são recusados. Não existe ferramenta para responder. - Retomar (`DELETE /api/pause`) e apagar um painel também são só da sessão. ## 4. Painéis, números e conferências - **Painel** — blocos de número, funil ou lista, por 7 dias, 30 dias ou no mês, com meta. Um bloco que chega à meta do mês emite `goal.reached`. - **Número** — a soma ou a contagem de um tipo de evento, ou um número mandado pronto (`POST /api/metrics` com a `tk_`, ou `tasks_push_metric`). - **Conferência** — compara a contagem de dois sistemas a cada 15 minutos e diz quando deixam de bater (`reconciliation.diverged`) e quando voltam (`reconciliation.matched`). ## 5. Eventos de entrada `POST https://tasks.worker.myoperations.click/events/:sourceId` — uma fonte por sistema, criada no painel, cada uma com o seu segredo `whsec_` (mostrado uma vez). Assinatura `x-ccm` (Standard Webhooks), corpo até 256 KB, qualquer tipo no formato `.`. Um evento entregue duas vezes conta uma vez. Ao trocar o segredo, o antigo ainda vale 24 horas. ## 6. Rotas Base: `https://tasks.worker.myoperations.click`, sem versão no caminho, com a sessão do painel ou `Authorization: Bearer tk_…` onde a chave vale. Coleções respondem `{items, page}`; erros, `{error: {code, message}}`. ``` GET /status o serviço e as promessas dele GET /api/agents · POST /api/agents os agentes (POST cria a versão 1) GET /api/agents/:id · PATCH o agente: modelo, limites, conexões, gatilhos POST /api/agents/:id/versions salvar as instruções cria uma versão nova POST /api/agents/:id/run "Rodar agora" (respeita a pausa e os limites) GET /api/connections · POST as conexões MCP POST /api/connections/:id/test lista as ferramentas; as novas chegam como Confirma PATCH /api/connections/:id/tools/:name { policy } GET /api/requests · POST os pedidos (POST: agente de fora, com a tk_) POST /api/requests/:id/answer responde — só a sessão de uma pessoa GET /api/runs · POST /api/runs as execuções; POST = relato de agente de fora GET /api/pause · POST · DELETE pausa; DELETE ("Retomar") só pela sessão GET /api/boards · POST · PATCH · DELETE os painéis e os blocos GET /api/metrics · POST /api/metrics os números; POST manda um número pronto (tk_) GET /api/reconciliations · POST as conferências; POST …/:id/check confere agora GET /api/sources · POST as fontes de entrada; POST …/:id/rotate GET /api/webhooks · POST · PATCH · DELETE os destinos POST /api/webhooks/:id/test um evento de teste assinado, agora GET /api/deliveries · POST …/:id/retry as entregas, com reenvio GET /api/keys · POST /api/keys a chave tk_ (POST só pela sessão) GET /api/models os dois modelos e o padrão GET /api/plan o uso; nada é cobrado ``` ## 7. Webhooks para fora Até 20 destinos por conta, cada um com os eventos que assina. Padrão **Standard Webhooks** com o prefixo `x-ccm`: ``` x-ccm-id: x-ccm-timestamp: 1790265731 x-ccm-signature: v1, ``` A chave do HMAC é o base64 depois de `whsec_`. Recuse timestamp com mais de 5 minutos e ignore um `x-ccm-id` já visto. Corpo: `{ type, timestamp, data: { person, channel, properties } }`. | Evento | Quando | |---|---| | `request.created` | um agente criou um pedido | | `request.answered` | uma pessoa respondeu, com a resposta | | `action.pending` | uma ação de agente espera aprovação (ferramenta Confirma) | | `run.completed` | uma execução terminou bem, com passos, saídas e custo | | `run.failed` | uma execução falhou ou parou, com o passo e o erro | | `reconciliation.diverged` | uma conferência passou a divergir | | `reconciliation.matched` | uma conferência voltou a bater | | `goal.reached` | um bloco chegou à meta do mês | Toda entrega é primeiro uma linha na caixa de saída. Se o destino falhar: nova tentativa em 1 min, 5 min, 30 min, 2 h e 12 h; depois, reenvio à mão. 401 e 403 ficam retidos até o destino voltar; 410 é definitivo. O reenvio leva o mesmo id. ## 8. Servidor MCP - **Endereço:** `https://tasks.worker.myoperations.click/mcp` (Streamable HTTP), para a conta inteira — a conta vem do token, nunca de um argumento. - **OAuth 2.1:** metadados em `https://tasks.worker.myoperations.click/.well-known/oauth-protected-resource`. O token só vale para este servidor (audiência conferida). A `tk_` é recusada. - É para agentes que rodam **fora** do Tasks. Os que rodam no Tasks usam as conexões (seção 1); a conexão do próprio Tasks já vem pronta. | Tool | Regra | O que faz | |---|---|---| | `tasks_create_request` | Livre | cria um pedido. Pedir é sempre livre: a resposta é de uma pessoa | | `tasks_get_request` | Livre | lê um pedido e a resposta | | `tasks_report_run` | Livre | relata uma execução de agente de fora, com o custo que ele informa | | `tasks_should_run` | Livre | pergunta se pode seguir; responde "não" com a pausa ligada | | `tasks_read_board` · `tasks_read_metric` · `tasks_list_reconciliations` | Livre | lê um painel, um número e as conferências | | `tasks_push_metric` | Livre | manda um número pronto | | `tasks_update_board` | Confirma | muda blocos ou metas; vira pedido de aprovação | | `tasks_pause_agents` | Confirma | pausa todos os agentes; vira pedido de aprovação | | `tasks_delete_board` | Só humano | **não é registrada**: não aparece na lista de ferramentas | **Responder um pedido, retomar e apagar não são ferramentas.** O agente pede. Quem responde é uma pessoa. ## 9. WhatsApp — construído, ainda não no ar Construído e testado contra uma Meta simulada. Não está no ar: falta a Meta aprovar o aplicativo, a verificação do negócio, a revisão do app e o modelo de mensagem `tasks_pedido_novo`. Até lá, o pedido chega no painel. As regras do canal, para você não prometer outra coisa: - O número é um **WhatsApp Business da própria conta**, informado no painel. Não é um número nosso. - **Fora da janela de 24 horas**, a Meta só deixa enviar um **modelo de mensagem aprovado por ela**. - Dentro da janela, uma decisão vira **até 3 botões** (até 20 caracteres cada); com mais opções, vira uma lista de até 10 linhas. - A resposta vale pelo número da opção, por "aprovado" / "sim" / "ok", ou por texto. Só o número verificado da pessoa conta. ## 10. Retenção Execuções, passos, eventos de entrada, mensagens do WhatsApp e checagens das conferências são apagados aos 90 dias. Pedidos, respostas, versões das instruções e os números diários ficam. ## 11. Escopo — o que este produto NÃO faz - **WhatsApp no ar.** Construído; espera a aprovação da Meta. - **Envio de arquivo** como anexo: só link, texto ou referência. - **Um modelo fora dos dois da lista.** - **Um agente responder o próprio pedido, retomar depois da pausa ou apagar um painel.** - **Custo estimado.** O custo é o da OpenRouter; "informado pelo agente" só para agente de fora. - **Cobrança.** Não há plano publicado, e nada é cobrado. ## 12. Checklist para agentes de IA 1. **Para o MCP, o login por código no e-mail**; para a API, peça a `tk_`. 2. **Nunca ponha a `tk_` no HTML** nem no `/mcp`. 3. **Peça, não decida:** o que for de uma pessoa vira `tasks_create_request`. 4. **Antes de cada passo, `tasks_should_run`.** "Não" quer dizer parar. 5. **Ao terminar, `tasks_report_run`**, com o custo que você souber. 6. **Não prometa WhatsApp** até o `/status` dizer que está configurado. 7. **Não invente rota nem tool.** A seção 6 lista as rotas; a 8, as tools.