Desenvolvimento com IA dentro da VTEX

Contextualizando os agentes de IA

Antes de olhar diretamente para as novas ferramentas da VTEX, é importante entender o que são agentes de IA e porque esse conceito tem aparecido tanto no desenvolvimento de software nos últimos anos.

De forma simples, um agente de IA é um sistema que usa um modelo de linguagem para interpretar um objetivo, raciocinar sobre o que precisa ser feito e executar ações com apoio de ferramentas externas. Ele pode cumprir várias funções como tomada de decisões, resolução de problemas e execução de acões que interagem com ambientes externos.

Diferente de um chatbot tradicional, que normalmente apenas responde a uma pergunta, um agente pode trabalhar com instruções, contexto, ferramentas, memória, validações e etapas intermediárias para chegar em um resultado.

O núcleo principal dos agentes de IA são os modelos de linguagem (LLMs). Esses modelos produzem suas próprias respostas com base nos dados usados para treiná-los e são limitados por restrições de conhecimento e raciocínio delimitados durante esse processo.

Os agentes de IA no desenvolvimento de software

No contexto de desenvolvimento de software, agentes de IA podem atuar como uma camada de apoio dentro do fluxo de trabalho do desenvolvedor. Eles não substituem o conhecimento técnico e conceitual, mas podem ajudar em tarefas que exigem consulta, interpretação, organização e tomada de decisão com base em contexto do fluxo de trabalho.

Na prática, isso significa que um agente pode ajudar a entender uma documentação, sugerir caminhos de implementação, revisar trechos de código, explicar mensagens de erro, gerar exemplos, comparar abordagens e até interagir com ferramentas específicas do projeto.

Um exemplo simples é quando o desenvolvedor precisa implementar uma funcionalidade usando uma tecnologia que não domina completamente. Em vez de apenas perguntar genericamente “como fazer isso?”, ele pode usar um agente com acesso ao contexto do projeto, à documentação da ferramenta e às regras específicas daquele ambiente. Assim, a resposta tende a ser mais próxima da realidade do código e menos genérica, basicamente o que acontece com as novas ferramentas de IA criadas pela VTEX.

Mesmo assim, é importante ter cuidado. Os agentes de IA não eliminam a necessidade de revisão humana. O desenvolvedor ainda precisa validar se a sugestão faz sentido, se está alinhada com o projeto, se respeita boas práticas e se não introduz problemas de segurança, performance ou manutenção.

Desenvolvimento assistido por IA dentro da VTEX

O desenvolvimento de aplicações e soluções na VTEX, envolve trabalhar com diversas ferramentas como frameworks e APIs que podem variar de acordo com cada plataforma. Por conta dessa abrangência é importante que, ao utilizar um assistente de IA, ele seja instruído e contextualizado da forma mais eficaz possível dentro do ecossistema da Plataforma, por isso, agora a VTEX oferece duas ferramentas que atuam de forma complementar: o VTEX Developer MCP e o VTEX Skills.

Essas ferramentas têm propostas diferentes, mas se complementam muito bem dentro de um fluxo de desenvolvimento assistido por IA.
O VTEX Developer MCP faz mais sentido quando o assistente precisa buscar informações de forma dinâmica durante uma tarefa. Por exemplo: consultar a documentação da VTEX, verificar referências de APIs, entender parâmetros disponíveis ou recuperar informações atualizadas diretamente das fontes oficiais da plataforma.

Já o VTEX Skills entra como uma camada de contexto mais persistente. Ele é útil quando o assistente precisa seguir padrões recomendados, respeitar limitações conhecidas da plataforma e considerar orientações específicas de implementação dentro do ecossistema VTEX.

Na prática, enquanto o MCP ajuda o assistente a acessar informações atuais e sob demanda, o Skills contribui com um contexto reutilizável sobre boas práticas, restrições e formas recomendadas de desenvolver na plataforma.

Quando usados em conjunto, os dois recursos tornam o assistente mais preparado para trabalhar com VTEX: ele passa a ter acesso tanto ao material de referência atualizado quanto a um conjunto de orientações específicas que ajudam a gerar respostas mais alinhadas com a realidade da plataforma.

VTEX Developer MCP

Depois de entender o papel dos agentes de IA no desenvolvimento, fica mais fácil entender onde esta ferramenta entra. O VTEX Developer MCP é um servidor baseado no Model Context Protocol que conecta assistentes de IA à documentação da VTEX e às referências de APIs da plataforma.

Na prática, ele funciona como uma ponte entre o assistente de IA e o conteúdo oficial da VTEX, permitindo que a ferramenta consulte informações durante a execução de uma tarefa.

Isso é importante porque um dos grandes problemas ao usar IA no desenvolvimento é a falta de contexto específico. Um assistente pode até conhecer conceitos gerais de front-end, APIs ou e-commerce, mas nem sempre entende detalhes próprios da VTEX, como endpoints, limitações, guias oficiais ou padrões recomendados. Com o MCP configurado, o assistente passa a conseguir buscar informações diretamente na documentação, recuperar artigos completos, procurar endpoints com base em definições OpenAPI e consultar especificações detalhadas de APIs.

Segundo a própria VTEX, essas capacidades permitem que as respostas sejam baseadas em conteúdo atualizado da plataforma.

O que o VTEX Developer MCP permite fazer

Na prática, o assistente conectado ao MCP pode ajudar em tarefas como:

• buscar artigos na documentação da VTEX;
• recuperar o conteúdo completo de uma documentação;
• procurar endpoints relacionados a uma API;
• consultar detalhes técnicos de um endpoint específico.

Isso muda bastante a forma como o desenvolvedor pode interagir com a IA. Em vez de perguntar algo genérico como “como integrar pagamentos na VTEX?”, você pode pedir para o assistente buscar a documentação oficial, localizar o guia correto e explicar a implementação com base naquele conteúdo.

Requisitos para usar e configuração

Para usar o VTEX Developer MCP, é necessário ter o Node.js 18 ou superior instalado e uma ferramenta de desenvolvimento compatível com MCP.

Embora a documentação da VTEX apresente opções para diferentes ambientes, como Cursor, Claude Code e Claude Desktop, neste artigo o foco será na configuração usando o Visual Studio Code utilizando o Codex , por ser uma das IDEs mais utilizadas no desenvolvimento web e também uma ferramenta bastante presente no fluxo de trabalho de quem desenvolve com VTEX.

Antes de configurar, verifique se o Node.js está instalado corretamente executando o comando abaixo no terminal:

node --version

O servidor MCP da VTEX pode ser executado usando o pacote @vtex/developer-mcp com npx:

npx -y @vtex/developer-mcp 

No caso do Codex, a configuração dos servidores MCP é feita no arquivo config.toml. Essa configuração pode ser global, usando: ~/.codex/config.toml

Ou pode ser específica do projeto, criando uma pasta .codex na raiz do repositório: .codex/config.toml

Essa segunda opção é interessante quando você quer manter a configuração do MCP junto do projeto, principalmente em repositórios onde aquele contexto faz sentido apenas para aquele ambiente.

Dentro do arquivo .codex/config.toml, a configuração do VTEX Developer MCP pode seguir este formato:

[mcp_servers.vtex-developer]

command = "npx"

args = ["-y", "@vtex/developer-mcp"]

Depois de adicionar a configuração, reinicie o Codex ou o VS Code para garantir que o servidor MCP seja carregado corretamente.

Com isso, o Codex passa a conseguir usar o VTEX Developer MCP como fonte de contexto, permitindo buscar documentações, recuperar artigos completos, pesquisar endpoints e consultar especificações de APIs da VTEX durante as tarefas de desenvolvimento.

VTEX Skills

Enquanto o VTEX Developer MCP aproxima o assistente de IA da documentação e das referências de API da VTEX, o VTEX Skills atua em outro ponto importante: o contexto de implementação.

O VTEX Skills é uma coleção de habilidades voltadas para agentes de IA que trabalham com desenvolvimento dentro da plataforma VTEX. Essas habilidades funcionam como uma fonte de orientação específica da plataforma, ajudando o assistente a entender padrões, restrições e boas práticas que fazem sentido dentro desse ecossistema.

Isso é importante porque os assistentes genéricos de IA nem sempre conhecem, com precisão, os detalhes de implementação da VTEX. Mesmo quando conseguem responder sobre conceitos gerais de e-commerce, front-end ou APIs, eles podem falhar em pontos mais específicos da plataforma. Na prática, assuntos como substituições de APIs, endpoints do Payment Provider Protocol, requisitos de BFF, limites do Master Data e padrões recomendados de implementação exigem um contexto que vai além do conhecimento geral do modelo.

É justamente essa lacuna que o VTEX Skills tenta preencher. Ele fornece orientações práticas baseadas no conhecimento da própria plataforma, permitindo que o assistente gere respostas mais alinhadas com a realidade de quem desenvolve para VTEX.

Com isso, o agente deixa de depender apenas de respostas genéricas e passa a contar com um direcionamento mais próximo das regras, limitações e boas práticas esperadas no desenvolvimento dentro da plataforma.

Principais recursos do VTEX Skills

Esta poderosa ferramenta adiciona uma camada de contexto específico da plataforma ao assistente de IA. Isso faz com que as respostas não dependam apenas do conhecimento genérico do modelo, mas também de orientações baseadas na documentação e nas práticas recomendadas pela VTEX.

Entre os principais pontos, estão:

• Restrições específicas da plataforma: O assistente passa a considerar detalhes como uso de Secure Proxy em fluxos sensíveis, requisitos de idempotência em endpoints de pagamento, limite de tempo em simulações de fulfillment e restrições do Master Data.
• Uma fonte de contexto para várias ferramentas: As Skills são criadas uma vez e exportadas para diferentes formatos, permitindo uso em ferramentas como Cursor, GitHub Copilot, Claude, OpenCode, Kiro e outros ambientes baseados em agentes.
• Base na documentação oficial da VTEX: O conteúdo das Skills é derivado da documentação da plataforma, o que ajuda a manter as orientações mais próximas das recomendações oficiais.
• Compatibilidade com ferramentas existentes: A proposta é funcionar com ferramentas que muitos desenvolvedores já utilizam no dia a dia, sem exigir uma mudança completa no fluxo de trabalho.
• Instalação simplificada: O instalador via npx identifica ferramentas compatíveis e posiciona os arquivos nos locais adequados.
• Conteúdo versionado e mantido: As Skills acompanham a evolução da documentação, o que ajuda a manter o contexto atualizado conforme a plataforma muda.

Como o VTEX Skills funciona na prática

As Skills funcionam como arquivos de texto que o agente de IA pode carregar como um contexto persistente antes de gerar código ou sugerir uma solução. Na prática, isso significa que o assistente passa a trabalhar com orientações específicas da VTEX durante o desenvolvimento, e não apenas com o conhecimento genérico do modelo.

Com ele instalado, o agente pode receber direcionamentos sobre:

• APIs recomendadas para cada caso de uso: ajuda o assistente a entender quais APIs da VTEX fazem mais sentido para determinada tarefa e quais parâmetros precisam ser considerados.
• Restrições específicas da plataforma: orienta sobre limites e comportamentos que nem sempre ficam claros apenas olhando a documentação da API, como limites de requisição, limites de schema e janelas de timeout.
• Padrões corretos para tarefas comuns: auxilia em cenários como configurar um override no FastStore, implementar um endpoint do Payment Provider Protocol ou estruturar uma entidade no Master Data.
• Requisitos de segurança da VTEX: Adiciona contexto sobre pontos sensíveis da plataforma, como escopo PCI, uso de Secure Proxy e cuidados necessários em fluxos relacionados a pagamento.
• Instalação automatizada nos agentes compatíveis: A CLI do VTEX Skills identifica ferramentas de IA suportadas no ambiente e posiciona os arquivos exportados nos locais corretos automaticamente.

Com isso, o VTEX Skills funciona como uma camada de orientação prática para o agente. Ele ajuda o assistente a sugerir soluções mais alinhadas com a realidade da plataforma, reduzindo respostas genéricas e aproximando a IA dos padrões esperados no desenvolvimento VTEX.

Configuração e uso

A forma mais prática de iniciar a configuração é com npx. Ele detecta as ferramentas de IA que você possui no seu ambiente e coloca os 'skill files' nos locais mais adequados.Também é possível fazer a instalação manual, como este artigo está focado no codex mostraremos o comando voltado para ele. Na documentação oficial você poderá encontrar o comando que se adeque a seu ambiente de desenvolvimento.

npx (recomendado): funciona com o Cursor, Claude Code, Codex, OpenCode, e mais 38 agentes. Detecta automaticamente as ferramentas de IA instaladas.

npx skills add vtex/skills

Codex (instalação manual): formato é compatível com várias ferramentas, incluindo Cursor, GitHub Copilot, Codex, Windsurf, Amp, Devin e outros agentes.

curl -sL https://github.com/vtex/skills/releases/latest/download/agents-md.tar.gz | tar xz -C seu-repositorio/ 

Tracks e Skills disponíveis

As Skills da VTEX são organizadas em diferentes tracks, ou trilhas de conhecimento. Cada track agrupa habilidades relacionadas a uma área específica do desenvolvimento dentro da plataforma.

Essa organização ajuda o agente de IA a receber um contexto mais direcionado para o tipo de tarefa que está sendo executada. Em vez de carregar orientações genéricas sobre toda a plataforma, o desenvolvedor pode instalar todas as tracks de uma vez ou escolher apenas aquelas que fazem sentido para o projeto em questão.

Na prática, isso torna o uso das Skills mais flexível. Um projeto focado em VTEX IO, por exemplo, pode priorizar a track de Custom VTEX IO Apps. Já um projeto envolvendo pagamentos pode se beneficiar mais da track de Payment Connector Development.

Recapitulando

O desenvolvimento assistido por IA dentro da VTEX passa principalmente pela combinação entre contexto, documentação atualizada e orientação específica da plataforma.

Agentes de IA se tornam mais úteis no desenvolvimento de software quando conseguem trabalhar além de respostas genéricas. Para isso, precisam de instruções claras, acesso a ferramentas externas e informações relacionadas ao ambiente em que a tarefa está sendo executada.

No ecossistema VTEX, esse contexto é especialmente importante. A plataforma possui APIs, frameworks, padrões de implementação e restrições próprias, que nem sempre são compreendidos corretamente por modelos de IA de uso geral.

Nesse cenário, o VTEX Developer MCP atua como uma ponte entre o assistente de IA e a documentação oficial da VTEX. Ele permite que o agente busque artigos, recupere conteúdos completos, pesquise endpoints e consulte especificações de APIs durante a execução de uma tarefa.

O VTEX Skills, por outro lado, adiciona uma camada de orientação persistente ao assistente. Seu papel é fornecer padrões recomendados, boas práticas, restrições conhecidas e informações específicas da plataforma para apoiar decisões de implementação.

Enquanto o MCP contribui com acesso dinâmico a informações atualizadas, o Skills oferece um contexto reutilizável sobre como desenvolver de forma mais alinhada ao ecossistema VTEX.

A combinação desses dois recursos torna o uso de IA mais relevante para desenvolvedores que trabalham com a plataforma, reduzindo respostas genéricas e aproximando o assistente das documentações, regras e práticas reais do desenvolvimento VTEX.