O que os agentes de IA realmente veem ao buscar seu Ator Apify

A Apify passou este ano tornando a frase "seu Actor como uma ferramenta para agentes de IA" concreta: um servidor de Modelo de Contexto de Protocolo (MCP) hospedado, cobrança por evento que um agente pode realmente pagar, até mesmo trilhas de pagamento em criptomoedas que não exigem uma conta Apify do lado do chamador. A proposta se escreve sozinha: construa um bom Actor, descreva-o bem, e um robô com um orçamento irá encontrá-lo.

O que eu não consegui encontrar em lugar nenhum foram números. Quando um agente vai procurar uma ferramenta, o que ele realmente vê? Ele vê a mesma classificação que um humano vê na Apify Store, ou algo diferente? Existe — como eu esperava silenciosamente — uma porta lateral para novos Actors que ainda não acumularam usuários?

Eu tinha um bom motivo para querer essa porta lateral. Entre 29 de julho e 1 de agosto, publiquei três Actors pay-per-event (PPE) sob uma nova conta de desenvolvedor: scrapers para produtos e avaliações da Wildberries, listagens de imóveis da Avito e avaliações da Lazada — grandes marketplaces, cantos tranquilos da Store. Nova conta, zero avaliações, contagens de usuários que posso listar de memória. Um início frio clássico.

Então, em 6 de agosto, eu medi isso. Conectei-me ao servidor MCP da Apify da mesma forma que qualquer agente faz, executei as buscas que um agente faria e comparei os resultados com a busca da Store voltada para humanos do mesmo dia. Este artigo é o método, os números e as duas armadilhas que produziram resultados convincentemente errados antes dos reais — uma delas me fez acreditar que meus Actors estavam invisíveis para os agentes.

Como um agente chega ao seu Actor

Antes das medições, um rápido mapa do pipeline, porque isso determina o que vale a pena otimizar.

Um agente (ou seu suporte — Claude Desktop, um loop SDK, o que for) se conecta a https://mcp.apify.com, o servidor MCP hospedado. O transporte é HTTP Streamable; a autenticação é feita via OAuth ou um cabeçalho de token de API simples. A configuração mínima do cliente é:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com",
      "headers": { "Authorization": "Bearer <APIFY_TOKEN>" }
    }
  }
}

O conjunto de ferramentas padrão expõe, entre outras, três ferramentas que importam para a descoberta:

• search-actors — busca por palavras-chave na Store,
• fetch-actor-details — o cartão completo de um Actor: descrição, preços, estatísticas, esquema de entrada, README,
• call-actor — executa um Actor pelo nome com uma entrada JSON, que é validada contra seu esquema de entrada no momento da execução.

O fluxo pretendido é exatamente o que você adivinharia: buscar → buscar detalhes → chamar. Alternativamente, um Actor específico pode ser montado como uma ferramenta nomeada adicionando ?tools=username/name à URL do servidor, caso em que o servidor MCP lê seu esquema de entrada e gera uma ferramenta dedicada a partir dele.

Quem está na piscina pesquisável? Nem todos. O servidor retorna apenas Actors gratuitos e pay-per-event para chamadores agentes — Actors de modelo de aluguel são excluídos — e descarta Actors que não passam nas verificações de segurança da plataforma. A documentação de monetização da Apify adiciona mais duas condições para um Actor ser utilizável por chamadores agentes (e pagantes em criptomoedas): ele deve ser executado com permissões limitadas, e ele não deve ser um Actor em modo Standby. Não há opt-in: um Actor pay-per-event com permissões limitadas e sem Standby está automaticamente incluído. A partir do final de julho de 2026, um pouco mais de 29.000 Actors na Store passaram por essa barreira (contados via a API pública da Store com o filtro de usuários-agentes). Os meus estão entre eles, o que tornou a próxima pergunta interessante.

O experimento: buscando meus próprios Actors da maneira que um agente faria

Eu queria a visão mais crua possível — sem SDK, sem mágica do lado do cliente — então falei JSON-RPC diretamente com o servidor usando curl. Três etapas; o único pré-requisito é seu token da API Apify exportado como APIFY_TOKEN.

Passo 1: inicializar e capturar a sessão. O ID da sessão volta como um cabeçalho de resposta (-D headers.txt abaixo salva isso), e tudo após initialize deve carregá-lo:

S=$(curl -s -D headers.txt -X POST "https://mcp.apify.com/" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
  > /dev/null; grep -i "^mcp-session-id:" headers.txt | tr -d '\r' | awk '{print $2}')

Uma pequena coisa que me custou uma tentativa: grep por ^mcp-session-id: com o âncora. Sem isso, a primeira correspondência é a linha access-control-expose-headers, que apenas menciona Mcp-Session-Id, e você passa um minuto confuso enviando uma lista de cabeçalhos CORS como seu ID de sessão.

Passo 2: chamar a ferramenta de busca. As respostas chegam como um fluxo de Eventos Enviados pelo Servidor (SSE); a carga útil é a última linha data::

curl -s -X POST "https://mcp.apify.com/" \
  -H "Authorization: Bearer $APIFY_TOKEN" -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" -H "mcp-session-id: $S" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search-actors","arguments":{"keywords":"Lazada reviews","limit":10,"offset":0}}}'

que retorna