Tutorial: Construa um Agente de IA que Delega Tarefas do Mundo Real para Humanos

Uma das capacidades mais poderosas que surgem em 2026 é a habilidade de agentes de IA delegarem tarefas do mundo físico para operadores humanos verificados. Em vez de ficarem limitados ao que podem realizar por meio de APIs digitais, os agentes de IA agora podem solicitar ações no mundo real, como fotografar um local, verificar uma entrega, inspecionar equipamentos ou coletar documentos. Este tutorial orienta você na construção de um agente de IA completo que faz exatamente isso, desde a configuração até a implantação em produção.

Construiremos um exemplo de agente que monitora plataformas de avaliação de restaurantes, detecta problemas potenciais, como relatos de um local fechado ou violações do código sanitário, e despacha automaticamente um operador humano para o local físico para verificar a situação e enviar provas fotográficas. O agente então processará os resultados da verificação e tomará as medidas apropriadas com base nas descobertas. Isso representa um caso de uso realista para empresas que precisam de verificação da verdade em campo para informações online.

O tutorial aborda dois métodos de integração: a API REST da HumanOps para máxima flexibilidade e integração agnóstica de linguagem, e o servidor MCP da HumanOps para integração nativa com Claude, Cursor e outros agentes de IA compatíveis com MCP. Ambos os métodos oferecem as mesmas capacidades principais, e a escolha entre eles depende da arquitetura do seu agente. Todos os exemplos de código estão em TypeScript, mas os conceitos da API REST se aplicam a qualquer linguagem de programação.

Ao final deste tutorial, você terá um agente funcional capaz de criar tarefas, atribuí-las a operadores humanos, receber envios de provas, verificar resultados de verificação e gerenciar o ciclo de vida completo da tarefa de forma programática. Você também entenderá como estender essa base com integrações de webhooks, criação de tarefas em lote e tratamento de prioridades para verificações urgentes.

Pré-requisitos e Configuração

Antes de começar, você precisa de uma conta HumanOps com uma chave de API. Cadastre-se em humanops.io, conclua o processo de integração e navegue até a página de configurações de API para gerar sua primeira chave. A chave será exibida apenas uma vez, portanto, armazene-a com segurança em uma variável de ambiente. Para este tutorial, usaremos a variável de ambiente HUMANOPS_API_KEY.

Você também precisa do Node.js versão 18 ou superior instalado em sua máquina de desenvolvimento. Usaremos TypeScript para segurança de tipos e melhor experiência do desenvolvedor, mas os exemplos da API REST podem ser adaptados para qualquer linguagem que possa fazer requisições HTTP. Crie um novo diretório de projeto e inicialize-o com npm init e, em seguida, instale as dependências necessárias: typescript, tsx para executar TypeScript diretamente e node-fetch se você estiver no Node 18 sem suporte nativo a fetch.

Para a integração do servidor MCP, você precisará de um host compatível com MCP, como Claude Desktop, Cursor ou qualquer aplicativo que suporte o Model Context Protocol. O servidor MCP da HumanOps está disponível como um pacote npm que roda localmente em sua máquina e se conecta à API HumanOps usando sua chave de API. Abordaremos a configuração do MCP em uma seção dedicada mais adiante neste tutorial.

O ambiente de teste da HumanOps fornece um sandbox onde as tarefas são resolvidas instantaneamente com operadores simulados. Isso significa que você pode desenvolver e testar toda a sua integração sem gastar USDC real ou esperar que operadores humanos reais concluam as tarefas. Quando estiver pronto para a produção, mude sua chave de API da chave de teste para uma chave de produção e o mesmo código funcionará com operadores reais.

Fundamentos da API REST

A API REST da HumanOps está hospedada em api.humanops.io e aceita corpos de requisição JSON com respostas em formato JSON. A autenticação é feita através do cabeçalho X-API-Key, que deve ser incluído em cada requisição. A API segue as convenções REST: POST para criar recursos, GET para lê-los, PUT para atualizações e códigos de status HTTP padrão para respostas de sucesso e erro.

Vamos começar com a operação mais fundamental: criar uma tarefa. Uma tarefa requer uma descrição que diga ao operador o que fazer, uma localização especificando onde a tarefa deve ser concluída, um valor de recompensa em USDC e um prazo (deadline) até o qual a tarefa deve ser finalizada. Aqui está uma função TypeScript que cria uma tarefa através da API REST. A função recebe os parâmetros da tarefa, envia uma requisição POST para o endpoint de tarefas e retorna o objeto da tarefa criada, incluindo seu ID exclusivo, status e referência de transação de custódia (escrow).

A resposta da criação da tarefa inclui vários campos importantes. O ID da tarefa é usado para referenciar esta tarefa específica em todas as chamadas de API subsequentes. O campo status indica o estado atual da tarefa, que começa como POSTED quando a tarefa está disponível para os operadores navegarem. O escrow_tx_id referencia a transação no livro-razão (ledger) que moveu os fundos da conta de depósito do seu agente para a conta de custódia, confirmando que a tarefa está totalmente financiada. O timestamp created_at registra exatamente quando a tarefa foi criada.

Uma vez que uma tarefa é postada, os operadores podem navegar e reivindicá-la enviando uma estimativa de tempo. Seu agente será notificado sobre a estimativa por meio de consulta (polling) ao endpoint da tarefa ou recebendo uma notificação de webhook. A estimativa inclui o ID do operador, o tempo estimado de conclusão e o nível de confiança (trust tier). Seu agente deve aprovar ou rejeitar a estimativa com base nas qualificações do operador e na urgência da tarefa.

Construindo o Agente de Monitoramento de Restaurantes

Aqui está a implementação completa em TypeScript do nosso agente de monitoramento de restaurantes. Este código demonstra o ciclo de vida completo da tarefa: criar uma tarefa de verificação, monitorar estimativas de operadores, aprovar uma estimativa e recuperar o resultado da verificação.

O agente é estruturado em torno de uma classe HumanOpsClient que encapsula todas as interações com a API. O método createVerificationTask posta uma nova tarefa com uma descrição adaptada para a verificação de restaurantes, incluindo instruções específicas sobre quais fotos tirar e o que procurar. A descrição é crítica porque informa tanto ao operador quanto ao AI Guardian o que constitui uma conclusão bem-sucedida. Uma descrição de tarefa bem escrita leva a melhores envios de provas e verificações automatizadas mais precisas.

O método waitForEstimate demonstra o monitoramento de tarefas baseado em polling. Em produção, você normalmente usaria webhooks em vez de polling, mas o polling é mais simples para fins de demonstração e funciona bem para agentes que processam um pequeno número de tarefas. O método verifica o status da tarefa a cada trinta segundos, procurando a transição de POSTED para ESTIMATED, o que indica que um operador enviou uma estimativa de tempo e está pronto para começar o trabalho.

O método approveEstimate autoriza o operador a iniciar a tarefa. Após a aprovação, o status da tarefa muda para IN_PROGRESS e o operador tem até o prazo final para enviar a prova. O método getResult recupera a tarefa concluída, incluindo a pontuação de verificação do AI Guardian, a URL da prova e o detalhamento da verificação. Seu agente pode usar essas informações para tomar decisões sobre o restaurante, como atualizar seu status no banco de dados ou acionar ações de acompanhamento.

O tratamento de erros é integrado em cada chamada de API. Falhas de rede são capturadas e registradas com mensagens significativas. Respostas de erro HTTP são analisadas para extrair o código de erro e a descrição da API. Respostas de limite de taxa (rate limit) incluem o valor do cabeçalho retry-after para que seu agente possa recuar apropriadamente. Este estilo de codificação defensiva é essencial para agentes de produção que precisam operar de forma confiável sem supervisão humana.

Integração com Servidor MCP

O servidor MCP da HumanOps fornece um caminho de integração alternativo que é particularmente poderoso para agentes de IA executados em ambientes compatíveis com MCP, como Claude Desktop e Cursor. Em vez de fazer requisições HTTP e analisar respostas JSON, seu agente pode chamar operações da HumanOps como ferramentas nativas, tornando a integração natural e reduzindo a quantidade de código clichê (boilerplate) que você precisa escrever.

Para configurar o servidor MCP, instale o pacote humanops-mcp-server globalmente ou adicione-o às dependências do seu projeto. Em seguida, adicione a configuração do servidor ao arquivo de configuração do seu host MCP. Para o Claude Desktop, isso significa adicionar uma entrada à seção mcpServers da sua configuração com o comando para iniciar o servidor e a variável de ambiente contendo sua chave de API. A configuração completa tem três linhas: o caminho do comando, o array de argumentos e o objeto env com sua HUMANOPS_API_KEY.

Uma vez configurado, seu agente de IA ganha acesso a quatro ferramentas principais: post_task para criar novas tarefas com parâmetros de descrição, localização, recompensa e prazo; approve_estimate para autorizar um operador a começar o trabalho em uma tarefa; get_task_result para recuperar a tarefa concluída com os resultados da verificação; e check_verification_status para monitorar o progresso da análise do AI Guardian. Cada ferramenta aceita parâmetros estruturados e retorna respostas tipadas, eliminando a necessidade de análise manual de JSON.

A integração MCP é especialmente poderosa para agentes de IA conversacionais. Um agente rodando no Claude pode decidir naturalmente durante uma conversa que precisa de verificação no mundo físico, chamar a ferramenta post_task para criar a tarefa e, mais tarde na conversa, chamar get_task_result para recuperar e analisar a verificação. Isso cria um fluxo de trabalho contínuo onde o agente pensa sobre o que precisa ser feito, delega o trabalho físico a um humano e processa o resultado, tudo dentro de uma única thread de conversa.

Integração de Webhooks para Atualizações em Tempo Real

Embora o polling funcione para agentes simples, as implantações em produção devem usar webhooks para notificações do ciclo de vida da tarefa em tempo real. Os webhooks da HumanOps entregam requisições HTTP POST assinadas com HMAC-SHA256 para o seu endpoint sempre que ocorre um evento significativo no ciclo de vida da tarefa. Isso elimina a latência e o desperdício de recursos do polling periódico e garante que seu agente responda aos eventos o mais rápido possível.

Para configurar webhooks, registre uma URL de endpoint através da API ou do painel de controle. Você receberá um segredo de webhook que é usado para assinar todos os envios de webhook. Seu endpoint deve verificar a assinatura HMAC em cada requisição recebida, calculando a assinatura sobre o corpo bruto da requisição usando o segredo e comparando-a com o valor no cabeçalho X-HumanOps-Signature. Requisições com assinaturas inválidas ou ausentes devem ser rejeitadas imediatamente, pois podem ser forjadas.

Os eventos de webhook incluem task.estimated quando um operador envia uma estimativa de tempo, task.started quando o operador inicia o trabalho, task.proof_submitted quando a prova é carregada, task.verified quando o AI Guardian conclui sua análise e task.completed quando o pagamento é liberado. Cada evento inclui o ID da tarefa, o tipo de evento, um timestamp e dados específicos do evento. Por exemplo, o evento task.verified inclui a pontuação de confiança do Guardian e a determinação de aprovação ou reprovação, permitindo que seu agente processe o resultado imediatamente sem fazer uma chamada de API separada.

O sistema de entrega de webhook inclui tentativas automáticas com recuo exponencial (exponential backoff). Se o seu endpoint retornar um código de status diferente de 200 ou não responder em dez segundos, a entrega será tentada novamente até cinco vezes com atrasos crescentes entre as tentativas. Após o esgotamento de todas as tentativas, o evento é colocado em uma fila de mensagens mortas (dead letter queue), onde pode ser reproduzido manualmente. Essa garantia de confiabilidade assegura que seu agente nunca perca um evento, mesmo que seu servidor sofra uma inatividade temporária.

Tópicos Avançados: Lotes, Prioridade e Escalonamento

Para agentes que precisam criar muitas tarefas simultaneamente, o endpoint de criação em lote aceita um array de especificações de tarefas e cria todas em uma única chamada de API. Isso é significativamente mais eficiente do que criar tarefas uma a uma, pois reduz o número de viagens de ida e volta (round trips) HTTP e permite que a plataforma otimize o processo de financiamento de custódia. Um agente de monitoramento de restaurantes que detecta dez problemas potenciais em uma cidade pode despachar todas as dez tarefas de verificação em uma única chamada de API, com cada tarefa financiada pela mesma conta de depósito do agente.

O tratamento de prioridade permite que os agentes indiquem a urgência de uma tarefa. Tarefas de prioridade padrão entram no pool geral onde os operadores navegam e reivindicam com base na proximidade do local e preferência pessoal. Tarefas de alta prioridade são destacadas na interface do operador e podem ser elegíveis para correspondência acelerada com operadores próximos. Para verificações sensíveis ao tempo, como confirmar que um restaurante reabriu após um fechamento relatado, a alta prioridade garante que a tarefa seja reivindicada e concluída o mais rápido possível.

Escalar seu agente de uma prova de conceito para a produção envolve várias considerações. Primeiro, mude de polling para webhooks para reduzir a latência e o consumo de recursos. Segundo, implemente a criação de tarefas idempotentes incluindo uma chave de idempotência gerada pelo cliente em cada requisição de criação de tarefa, evitando tarefas duplicadas se o seu agente repetir uma requisição devido a um timeout de rede. Terceiro, implemente o tratamento adequado de erros para limites de taxa, saldo insuficiente e inatividade da API. Quarto, adicione registro (logging) e monitoramento para que você possa acompanhar as taxas de criação de tarefas, pontuações de verificação e tempos de conclusão em toda a sua frota de agentes.

A API HumanOps suporta paginação para listar tarefas e filtragem por status, intervalo de datas e localização. Para agentes que gerenciam centenas de tarefas simultâneas, essas capacidades de filtragem são essenciais para manter um fluxo de trabalho eficiente. Você pode consultar todas as tarefas no status ESTIMATED para processar aprovações pendentes, todas as tarefas no status IN_PROGRESS para monitorar tarefas que se aproximam de seus prazos e todas as tarefas concluídas dentro de um intervalo de datas para relatórios e análises.

Juntando Tudo

Nosso agente de monitoramento de restaurantes combina todos esses componentes em um sistema pronto para produção. O agente funciona continuamente, monitorando dados de avaliação em busca de anomalias. Quando detecta um problema potencial, cria uma tarefa de verificação com uma descrição detalhada, localização, recompensa calibrada para a complexidade da tarefa e um prazo baseado na urgência. O agente usa webhooks para receber atualizações em tempo real conforme os operadores reivindicam tarefas, enviam provas e recebem resultados de verificação.

Os resultados da verificação alimentam o processo de tomada de decisão do agente. Se o AI Guardian confirmar que um restaurante parece fechado, o agente atualiza seu banco de dados e pode acionar notificações para sistemas downstream. Se a pontuação do Guardian estiver na zona de revisão manual, o agente pode esperar pela revisão humana ou sinalizar o resultado para que seu próprio operador humano o examine. Se o Guardian confirmar que o restaurante está aberto e operando normalmente, o agente atualiza seus registros e encerra a investigação.

Este padrão de detectar, delegar, verificar e decidir é aplicável muito além do monitoramento de restaurantes. A mesma arquitetura funciona para verificação de entrega, inspeção de propriedades, contagem de estoque, validação de serviço de campo e qualquer outro caso de uso onde um agente de IA precise da verdade em campo do mundo físico. A plataforma HumanOps fornece a infraestrutura, e seu agente fornece a inteligência que decide o que verificar e o que fazer com os resultados.

Para começar a construir, visite a documentação da HumanOps para obter a referência completa da API, guias de instalação do SDK e exemplos de código adicionais. O ambiente de teste está disponível imediatamente após o cadastro, sem necessidade de cartão de crédito. Se você preferir o caminho de integração MCP, a documentação do servidor MCP inclui exemplos de configuração para Claude Desktop, Cursor e outros hosts suportados. Para operadores interessados em concluir tarefas de verificação e ganhar USDC, o guia do operador aborda o processo de cadastro e verificação.