Por que Skills de dados públicos precisam de um envelope de resposta unificado

Em resumo: este é o artigo do contrato de resposta: as plataformas públicas diferem, mas os agents precisam de um único envelope para paginação, cobrança, erros e registros.

Toda fonte de dados públicos retorna um formato de resposta diferente. O TikTok envelopa os resultados de um jeito, o Reddit de outro, o YouTube de outro, o LinkedIn de outro. Se o seu agent conversa com todos eles diretamente, ele herda toda essa variação — a lógica de paginação se ramifica, as políticas de retry se ramificam, o parsing de erros se ramifica. Resolvemos isso empurrando cada operação por um único envelope. Este é o schema e por que ele importa.

O problema

A variação entre fontes é o imposto silencioso dos agents multiplataforma. O loop de uso de ferramentas do agent precisa lidar com muitos formatos, e essa complexidade aparece em três lugares caros de manter: o prompt (o modelo precisa ser ensinado em cada formato), a política de retry (fontes diferentes paginam de forma diferente após uma falha) e o envelope de erro (a resposta de não autorizado de uma plataforma não se parece em nada com a de outra).

Vimos nossos próprios agents de demonstração gastarem a maior parte de seus tokens em malabarismo de formatos em vez de raciocínio, e decidimos que a correção certa era no gateway, não no agent.

O envelope da UnifAPI

Todo endpoint HTTP que expomos, em todas as plataformas, retorna o mesmo formato externo: { request_id, data, pagination?, billing }. Os campos dentro de data são específicos de plataforma — um vídeo do TikTok tem hashtags, um post do Reddit tem subreddit — mas tudo ao redor é consistente.

Os erros se colapsam em um vocabulário fechado. Cada um carrega uma mensagem legível por humano e um type legível por máquina. O modelo pode ramificar pelo type sem precisar reconhecer texto específico de plataforma.

Padrões de reshape que usamos

Padronizar plataformas públicas por trás de um único envelope significa que nossa camada de reshape é de algumas centenas de linhas por plataforma. Três padrões dominam.

Unificação de cursor — o token de paginação de cada plataforma (max_cursor, after, nextPageToken, end_cursor, page) vira pagination.cursor. Calculamos has_more a partir de qualquer sinal que a fonte forneça (length === limit, uma flag has_more explícita, um next-cursor nulo).

Achatamento de campos — quando uma fonte aninha dados três níveis abaixo (data.data.children.data, é com você, Reddit), nós o elevamos para o data[] de topo. O modelo nunca vê os envelopes intermediários; ele vê os registros.

Parsing defensivo — plataformas públicas mudam tipos de campo sem aviso (um count vira string, um array vira um único item, um timestamp vira null). A camada de reshape coage cada campo ao seu tipo declarado e descarta o registro apenas se os campos obrigatórios estiverem faltando. Essa disciplina pega a maioria das falhas silenciosas que vimos no passthrough cru.

O que quebra se você pular isto

Sem um envelope, duas coisas dão errado em escala. Primeiro, o prompt do seu agent cresce linearmente com a contagem de plataformas — cada nova plataforma adiciona um parágrafo explicando seu formato de resposta. Na plataforma 10, o prompt é a parte mais lenta da chamada.

Segundo, o seu código de retry e paginação cresce de forma multiplicativa. Cada esquisitice específica de fonte interage com cada outra esquisitice, e a matriz de "o retry-após-cursor funciona na plataforma X sob a condição Y" explode. Equipes que não normalizam cedo acabam escrevendo uma camada de normalização tarde, depois dos bugs.

O que vem a seguir

O envelope atual cobre endpoints no estilo de lista de forma limpa. A próxima iteração em que estamos trabalhando cobre fontes em formato de streaming e webhook — lugares em que a resposta não é um { data: [...] } de uma vez, mas uma série de eventos ao longo do tempo. Estamos modelando-a para parecer um iterador assíncrono do lado do agent, de modo que a mudança no prompt seja mínima.

Se você está construindo um agent multiplataforma hoje e quer ver como o envelope se comporta na prática, comece com uma Skill em unifapi.com/skills ou inspecione a especificação OpenAPI em unifapi.com/openapi.json — todo endpoint, todo campo, um único formato.

O que ler em seguida

Design das ferramentas do catálogo de MCP - mostra como os agents descobrem as operações que retornam este envelope.

UnifAPI vs RapidAPI - usa a normalização como ponto de comparação.

Especificação OpenAPI - expõe o schema ao vivo por trás do texto.