Shopify UCP: compras com agente sem pular a confirmação humana

ANÁLISE EDITORIAL

Pesquisar um produto com IA é bem diferente de autorizar uma compra. A Skill oficial UCP, mantida pela Shopify, ajuda um agente a pesquisar ofertas, consultar um vendedor compatível com o Universal Commerce Protocol, montar um carrinho e acompanhar um pedido. Ela também descreve onde o agente precisa parar e devolver o controle ao comprador. O ponto útil não é prometer compra automática: é saber qual informação veio do catálogo, qual foi confirmada pela loja e qual etapa ainda depende da pessoa.

O que a Skill faz e para quem serve

O arquivo SKILL.md orienta a escolher entre pesquisa em catálogo global e operações restritas a um vendedor. Serve para quem desenvolve um assistente de compras, testa uma integração comercial ou revisa um fluxo de carrinho e checkout mediado por agente. O material pode orientar busca, comparação, inspeção do esquema publicado pelo lojista, acompanhamento de pedido e transferência para o site da loja. Não é um motor de pagamento, uma credencial para lojas nem um aval para finalizar pedidos sem autorização.

A apresentação oficial do CLI informa que o projeto trabalha com entradas e saídas estruturadas e que as capacidades efetivas são anunciadas por cada comerciante. A Skill acrescenta instruções para interpretar essas respostas. É diferente da entrada do catálogo sobre Stripe, voltada a construir integrações de cobrança, e da Skill da Store API do WooCommerce, voltada a desenvolver rotas de uma loja. Aqui o problema é o percurso do comprador entre vendedores.

Compatibilidade e pré-requisitos

O pacote local contém documentos para um cliente que reconheça o formato SKILL.md. O próprio frontmatter da Skill exige o binário ucp. A referência oficial de instalação informa Node.js 22.19.0 ou posterior para o CLI @shopify/ucp-cli. É necessário acesso à rede para descobrir capacidades de vendedores e consultar serviços, além de consentimento e autenticação adequados para operações que a loja proteger. Nem toda loja publica UCP, nem todo catálogo oferece os mesmos dados ou cobre o mesmo país.

Use um terminal em ambiente de teste e confirme node --version antes de instalar. Para um projeto isolado, a documentação oferece npm install --save-dev @shopify/ucp-cli e uso por npx ucp. Há também execução efêmera com npx @shopify/ucp-cli e instalação global, que modifica o ambiente do usuário inteiro. Escolha uma delas de forma consciente; o ZIP do Bastidores não instala Node, o CLI ou suas dependências.

Como instalar a Skill com escopo controlado

Primeiro baixe o ZIP local, confira seu SHA-256 informado no card, abra ORIGEM.md e compare os hashes dos arquivos. Leia LICENSE e SKILL.md antes de copiar a pasta ucp para o diretório de Skills aceito pelo seu cliente. A documentação do repositório também descreve ucp skills add para registrar a Skill diretamente pelo CLI oficial, se você preferir esse caminho. Não use os dois métodos ao mesmo tempo sem verificar se o cliente criou duplicatas.

O pacote preserva quatro referências Markdown e três expressões JMESPath em texto porque o guia principal aponta para esses materiais. Nenhum executável foi espelhado. As expressões são projeções de resposta, não comandos de compra. Para funcionamento real, instale o CLI separadamente a partir da fonte oficial, fixe a versão aprovada no seu projeto e revise o que o gerenciador de pacotes vai baixar.

Configuração antes de consultar lojas

Execute ucp profile show e ucp doctor --skip-network para entender o perfil selecionado e checar o ambiente local antes de qualquer chamada remota. A referência SETUP.md explica como perfis e variáveis de ambiente alteram a seleção. Um perfil personalizado pode anunciar uma URL controlada por quem o configurou; trate essa URL como parte da identidade da integração. Não grave tokens em instruções da Skill nem no ZIP. Se uma loja exigir cabeçalho autenticado, mantenha o segredo no mecanismo seguro do seu ambiente e confira o domínio de destino.

Para um vendedor específico, use ucp discover --business https://dominio-da-loja.example, substituindo pelo domínio real fornecido pelo comprador. A descoberta informa operações disponíveis. Para payloads de entrega, desconto ou pagamento, consulte ucp <op> --input-schema --business <url> antes de montar JSON. O esquema anunciado pela loja prevalece sobre exemplos antigos. Um erro PROFILE_FETCH_FAILED indica que aquele endereço não ofereceu o perfil esperado; não o confunda com erro de autenticação nem troque silenciosamente de vendedor.

Primeiro uso seguro e resultado esperado

Comece com uma pesquisa de leitura, sem carrinho: ucp catalog search --set /query='termo do produto' --view :compact. A saída deve trazer resultados estruturados com vendedor e dados da oferta disponíveis naquele momento. Não afirme que preço ou estoque estão garantidos para fechar negócio. Escolha um item concreto, consulte seus detalhes ou atualize a oferta com catalog lookup antes de recomendar um caminho de compra. Se o comprador informou uma loja, identifique-a pelo domínio do vendedor, não por uma marca que aparece no título do produto.

O guia oficial do catálogo separa pesquisa, consulta por ID e atualização de disponibilidade. O resultado esperado desta primeira etapa é uma lista comparável e rastreável, não um pedido. A ausência de resultado pode refletir filtros, país, autenticação ou cobertura da fonte. Informe essa limitação ao usuário em vez de inventar uma alternativa comercial.

Carrinho, checkout e confirmação humana

Quando o comprador escolher um produto e autorizar avançar, descubra primeiro as capacidades do vendedor e monte um carrinho por loja. Resultados de comerciantes diferentes não formam automaticamente um único pedido. O carrinho pode oferecer estimativas; métodos de entrega e total final dependem do checkout e das respostas do vendedor. A referência de fulfillment orienta a preservar IDs de linhas existentes e a usar os métodos devolvidos pela loja. Não invente frete, imposto ou disponibilidade regional.

Em uma automação responsável, pesquisar e criar um carrinho são etapas separadas de concluir a transação. Antes de checkout complete, mostre ao comprador vendedor, item, quantidade, entrega, moeda e totais apresentados pelo comerciante, com avisos e condições obrigatórios. Peça confirmação inequívoca. Se o protocolo retornar requires_escalation, apresente a URL de continuação recebida do próprio vendedor e explique que a pessoa precisa revisar ou autenticar a compra. Não construa uma URL de pagamento por dedução.

Permissões, privacidade e riscos

O texto da Skill não concede permissão sozinho, mas pode levar um agente com rede e execução de comandos a enviar consultas, endereço, dados de carrinho e eventualmente informações de compra a serviços externos. Limite essas permissões no cliente, separe ambiente de teste e produção, e não coloque cartão, token, endereço completo ou histórico de pedidos em prompts públicos. O site do protocolo UCP apresenta o modelo geral; cada loja, porém, anuncia suas próprias operações e exigências. A identidade de um vendedor exibida no catálogo não prova, por si, que ele é o fabricante ou revendedor autorizado.

Mensagens de aviso e divulgação legal da loja não devem ser escondidas para acelerar a compra. Se o canal não puder mostrar uma divulgação obrigatória de modo adequado, devolva o comprador para a interface da loja. Se as linhas do total não fecharem, apresente o total que a loja declarou, registre a divergência e não conclua autonomamente o checkout. Essas cautelas vêm das regras do SKILL.md oficial, não de um teste comercial feito pelo Bastidores.

Erros comuns e como diagnosticar

Se ucp não for reconhecido, confirme Node.js, a instalação escolhida e se você precisa invocar npx ucp ou npx @shopify/ucp-cli. Se ucp doctor falhar, leia a verificação específica de runtime, perfil, diretório de estado, proxy ou URL, sem reexecutar checkout por tentativa. Se a loja rejeitar um campo com SCHEMA_VALIDATION_FAILED, consulte o --input-schema da operação exata e ajuste somente o payload. Se aparecer AUTH_REQUIRED ou INSUFFICIENT_PERMISSIONS, pare e transfira a pessoa para uma URL legítima recebida na resposta, sem contornar autenticação.

Se um produto sumir de uma lista salva, faça catalog lookup para distinguir indisponibilidade de um resultado antigo. Se um carrinho voltar com totais diferentes, use os valores atualizados do vendedor e peça nova revisão ao comprador. Para detalhes dos códigos e das formas de resposta, consulte a referência técnica oficial. Nenhum desses erros autoriza trocar de vendedor sem consentimento.

Versão, licença e escolha editorial

A cópia documental foi fixada no commit 1cd915db53a7734c4d32f998131ca00debb11f4f. O repositório da Shopify publica a release v0.9.0; a versão do CLI instalada por você deve ser conferida separadamente. A licença MIT permite redistribuir o material com o aviso original, que foi preservado no ZIP. O repositório tinha 79 estrelas em 11/10/2026, às 14h de São Paulo, conforme consulta à API pública do GitHub. Esta é uma exceção ao limiar usual de mil estrelas porque a Skill é mantida pela própria plataforma, com documentação, release e licença verificáveis; não fazemos alegação de adoção ampla.

Download local e repositório oficial

O card de download nesta página oferece o pacote documental auditado pelo Bastidores, com SKILL.md, referências, expressões de visualização, LICENSE e ORIGEM.md. Confira o SHA-256 exibido antes de instalar. O botão separado para o repositório oficial abre o código e as atualizações da Shopify em outra aba. O ZIP não substitui o CLI nem contém capturas reais, binários, executáveis, segredos ou credenciais. A capa acima é uma ilustração editorial exclusiva, não uma captura do produto e não comprova uma compra concluída.