Phase 13 - Lesson 13

Tarefas Assíncronas (SEP-1686) — Chame Agora, Busque Depois para Trabalho de Longa Duração

This lesson includes a graded coding exercise that runs in your browser, unlocked with lifetime access.

O trabalho real do agente leva de minutos a horas: execuções de CI, síntese de pesquisa profunda, exportações em lote. Chamadas de ferramentas síncronas derrubam conexões, expiram ou bloqueiam a interface de usuário. O SEP-1686, mesclado em 25/11/2025, adiciona uma primitiva de Tarefas: qualquer solicitação pode ser aumentada para se tornar uma tarefa, e o resultado pode ser obtido mais tarde ou transmitido por meio de notificações de estado. Nota de risco de desvio: as Tarefas são experimentais até o primeiro semestre de 2026; a superfície do SDK ainda está sendo projetada em torno da especificação.

Tipo: Build Idiomas: Python (stdlib, máquina de estado de tarefas assíncronas) Pré-requisitos: Fase 13 · 07 (servidor MCP), Fase 13 · 09 (transportes) Tempo: ~75 minutos

Objetivos de Aprendizado

• Identificar quando promover uma ferramenta de síncrona para aumentada por tarefa (trabalho do lado do servidor >30 segundos).
• Percorrer o ciclo de vida da tarefa: working → input_required → completed / failed / cancelled.
• Persistir o estado da tarefa para que falhas não percam o trabalho em andamento.
• Consultar tasks/status e buscar tasks/result corretamente.

O Problema

Uma ferramenta generate_report executa um pipeline de extração de vários minutos. Opções sob o modelo síncrono:

1. Manter a conexão aberta por três minutos. Transportes remotos a derrubam; os clientes expiram; as interfaces de usuário congelam.
2. Retornar imediatamente com um placeholder; exigir que o cliente consulte um endpoint personalizado. Quebra a uniformidade do MCP.
3. Executar e esquecer; sem resultado.

Nenhum é bom. O SEP-1686 adiciona um quarto: aumento de tarefa. Qualquer solicitação (geralmente tools/call) pode ser marcada como uma tarefa. O servidor retorna um ID de tarefa imediatamente. O cliente consulta tasks/status e busca tasks/result quando concluído. O estado do lado do servidor sobrevive a reinicializações.

O Conceito

Aumento de tarefa

Uma solicitação torna-se uma tarefa ao definir params._meta.task.required: true (ou optional: true, o servidor decide). O servidor responde imediatamente com:

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "_meta": {
      "task": {
        "id": "tsk_9f7b...",
        "state": "working",
        "ttl": 900000
      }
    }
  }
}

ttl é a promessa do servidor de reter o estado; após o ttl, o resultado da tarefa é descartado.

Opção por ferramenta

As anotações de ferramentas podem declarar suporte a tarefas:

• taskSupport: "forbidden" — esta ferramenta sempre é executada de forma síncrona. Seguro para ferramentas rápidas.
• taskSupport: "optional" — o cliente pode solicitar aumento de tarefa.
• taskSupport: "required" — o cliente DEVE usar aumento de tarefa.

Uma ferramenta generate_report seria required. Uma ferramenta notes_search seria forbidden.

Estados

working  -> input_required -> working  (loop via elicitation)
working  -> completed
working  -> failed
working  -> cancelled

A máquina de estado é do tipo append-only: uma vez que esteja em completed, failed ou cancelled, a tarefa é terminal.

Métodos

• tasks/status {taskId} — retorna o estado atual e uma dica de progresso.
• tasks/result {taskId} — bloqueia ou retorna 404 se ainda não estiver concluído.
• tasks/cancel {taskId} — idempotente; estados terminais ignoram.
• tasks/list — opcional; enumera tarefas ativas e concluídas recentemente.

Transmissão de alterações de estado

Quando o servidor suporta isso, o cliente pode assinar notificações de estado:

server -> notifications/tasks/updated {taskId, state, progress?}

Clientes que usam transmissão em vez de consulta obtêm uma melhor experiência do usuário (UX). A consulta sempre é suportada como a superfície mínima.

Estado durável

A especificação exige que os servidores que declaram suporte a tarefas persistam o estado. Uma falha não deve perder resultados concluídos dentro do ttl. Os armazenamentos variam de SQLite a Redis e ao sistema de arquivos. O laboratório da Lição 13 usa o sistema de arquivos.

Semântica de cancelamento

tasks/cancel é idempotente. Se a tarefa estiver no meio da execução, o servidor tentará parar (verifique o cancelamento cooperativo do executor). Se já for terminal, a solicitação será uma operação sem efeito (no-op).

Recuperação de falhas

Quando o processo do servidor reinicia:

1. Carregar todos os estados de tarefas persistidos.
2. Marcar quaisquer tarefas working cujo processo morreu como failed com o erro CRASH_RECOVERY.
3. Preservar completed / failed / cancelled por seu ttl.

Tarefas assíncronas mais amostragem

Uma tarefa pode, por si mesma, chamar sampling/createMessage. É assim que as tarefas de pesquisa de longa duração funcionam: a thread da tarefa do servidor faz a amostragem do modelo do cliente conforme necessário, enquanto a interface de usuário do cliente exibe a tarefa como working com atualizações periódicas de progresso.

Por que isso é experimental

O SEP-1686 foi lançado em 25/11/2025, mas o roteiro mais amplo aponta três problemas em aberto: primitivas de assinatura duráveis, subtarefas (relações de tarefa pai-filho) e padronização de TTL de resultado. Espere que a especificação evolua ao longo de 2026. O código de produção deve tratar as Tarefas como estáveis apenas para o caso comum e se proteger contra alterações futuras do SDK para subtarefas.

Use

code/main.py implementa um armazenamento de tarefas durável (baseado em sistema de arquivos) e uma ferramenta generate_report que roda em uma thread em segundo plano. Os clientes chamam a ferramenta, obtêm um ID de tarefa imediatamente, consultam tasks/status enquanto o executor atualiza o progresso e buscam tasks/result quando concluído. O cancelamento funciona; a recuperação de falhas é simulada matando a thread de execução e recarregando o estado.

O que observar:

• Estado da tarefa JSON persistido em /tmp/lesson-13-tasks/<id>.json.
• A thread executora atualiza o campo progress; a consulta mostra o avanço.
• O cancelamento pelo lado do cliente define um evento; o executor verifica e sai mais cedo.
• O recarregamento do estado após uma "falha" marca a tarefa em andamento como failed com CRASH_RECOVERY.

Entregue

Esta lição produz outputs/skill-task-store-designer.md. Dada uma ferramenta de longa duração (pesquisa, build, exportação), a habilidade projeta o armazenamento de tarefas (formato do estado, ttl, durabilidade), escolhe a flag taskSupport correta e esboça as notificações de progresso.

Exercícios

1. Execute code/main.py. Inicie uma tarefa generate_report, consulte o status e depois busque o resultado.
2. Adicione uma chamada tasks/cancel no meio da execução. Verifique se o executor a respeita e o estado se torna cancelled.
3. Simule a recuperação de falhas: mate a thread executora, reinicie o carregador e observe o modo de falha CRASH_RECOVERY.
4. Estenda o armazenamento para SQLite. Os ganhos de durabilidade são os mesmos; as opções de consulta se expandem (listar todas as tarefas da sessão X).
5. Leia a postagem do roadmap do MCP para 2026. Identifique o problema em aberto relacionado a Tarefas que tem maior probabilidade de afetar o design da API do SDK no próximo ano.

Termos-Chave

Leituras Adicionais

• MCP — GitHub SEP-1686 issue — a proposta original e discussão completa
• WorkOS — MCP async tasks for AI agent workflows — passo a passo do design com justificativa
• DeepWiki — MCP task system and async operations — mecânica e máquina de estados
• FastMCP — Tasks — padrões de implementação de tarefas no nível do SDK
• MCP blog — 2026 roadmap — problemas em aberto e prioridades para 2026, incluindo subtarefas |