Ensinando Codex a Pintar: Uma Habilidade de Edição de Imagem Stateful Baseada na API de Interações do Gemini e MCP

TL;DR: nb2lite-skill-codex envolve o modelo gemini-3.1-flash-lite-image do Google (NB2Lite) em um pequeno servidor FastMCP e o empacota como uma habilidade do Codex. Você digita "gerar uma imagem de uma cozinha cyberpunk" no Codex, e ele simplesmente... faz isso. Então você diz "adicione uma placa de RAMEN neon" e ele edita a mesma imagem sem precisar re-promptar toda a cena. Ah, e a imagem de capa deste artigo? Gerada pela coisa sobre a qual o artigo fala — dogfooding até o fim. Mais sobre isso no final.

Contexto: por que outra ferramenta de imagem?

A maioria dos fluxos de trabalho de geração de imagem é sem estado. Você envia um prompt, recebe pixels de volta, e o modelo imediatamente esquece tudo. Quer ajustar o resultado? Você re-descreve a cena inteira e reza para que o personagem, a iluminação e a composição sobrevivam à viagem de ida e volta. (Narrador: eles não sobrevivem.)

O NB2Lite do Google — o apelido amigável para gemini-3.1-flash-lite-image — adota uma abordagem diferente. É um modelo de imagem de alta eficiência com gerações em menos de 2 segundos, renderização de texto sólida em mais de 25 idiomas, e — o recurso principal — suporte para a API de Interações com estado, que permite que você itere sobre uma imagem em várias etapas enquanto o modelo mantém o contexto visual no servidor.

Este repositório conecta essa capacidade ao Codex, para que seu agente de codificação possa gerar e refinar imagens iterativamente como parte natural de uma sessão. Ele é enviado como duas coisas em um repositório:

1. Um servidor do Protocolo de Contexto do Modelo (MCP) (nb2lite-agent, um aplicativo FastMCP de arquivo único em server.py) expondo exatamente quatro ferramentas.
2. Uma habilidade do Codex (nb2lite-image) que ensina o Codex quando e como usar essas ferramentas corretamente.

A API de Interações: imagens com memória

A API de Interações é o ponto final com estado do Gemini. O loop central se parece com isto:

1. Você chama client.interactions.create(...) com um prompt e store=True.
2. A resposta inclui um interaction_id — um identificador para o contexto visual da vez, persistido nos servidores do Google.
3. Na próxima chamada, você passa previous_interaction_id, e o modelo edita a tela existente — preservando o personagem, estilo, iluminação e continuidade de pixels.

Então, em vez disso (sofrimento sem estado):

"Uma raposa em aquarela em uma floresta ao amanhecer, neblina, luz suave, usando um cachecol vermelho, três bétulas à esquerda, e agora também segurando uma lanterna"

...você escreve isto:

"Adicione uma lanterna em sua pata."

É isso. O contexto armazenado mantém o resto.

Alguns detalhes práticos que o servidor cuida para você:

• Cada turno retorna um novo ID de interação. Cadastre o mais recente; editar a partir de um ID obsoleto silencia sua sessão de um estado anterior (um bug sutil e muito irritante se você fizer isso manualmente).
• A proporção é escolhida no momento da geração (1:1, 16:9, 9:16, 4:3, 3:4) e herdada em edições com estado — mudá-la no meio da sessão degrada a continuidade dos pixels, então a ferramenta de edição deliberadamente não aceita uma.
• Níveis de pensamento: baixo (padrão, rascunhos rápidos) ou alto (renderização complexa, layout de texto preciso, composição de personagens). A especificação genérica da API também lista mínimo e médio, mas a API ao vivo os rejeita para este modelo com um HTTP 400 — o servidor o salva de descobrir isso da maneira difícil.

O que é MCP, em um minuto

O Protocolo de Contexto do Modelo é um padrão aberto para conectar assistentes de IA a ferramentas e dados. Antes dele, dar a um modelo acesso a algum serviço significava escrever uma integração sob medida para cada assistente — N assistentes × M serviços, todos reinventando a mesma tubulação. O MCP colapsa isso: um autor de ferramenta escreve um servidor MCP que expõe ferramentas tipadas, e qualquer cliente compatível com MCP (Codex, Codex Desktop, e uma lista crescente de outros) pode descobri-las e chamá-las sem código de cola por cliente.

Um servidor MCP é geralmente um pequeno processo local que fala JSON-RPC via stdio. O cliente o inicia, pergunta "quais ferramentas você tem?", e a partir daí o modelo pode chamá-las como funções.

O servidor nb2lite-agent expõe exatamente quatro:

As imagens são salvas no disco como gen_<timestamp>_<uuid8>.jpg (ou prefixadas com edit_/edit_local_) — o sufixo UUID evita que gerações concorrentes se sobreponham. Erros retornam como 🔴 ... strings de texto em vez de erros de protocolo, para que o agente possa lê-los e reagir a eles.

E o que é uma habilidade do Codex?

Se o MCP é as mãos (as ferramentas que o Codex pode chamar fisicamente), uma habilidade é a memória muscular — um arquivo markdown (SKILL.md) mais recursos agrupados que carregam no contexto do Codex e ensinam o fluxo de trabalho: qual ferramenta usar, em que ordem, com quais restrições.

Para nb2lite-image, a habilidade codifica coisas como:

• Chame get_help primeiro ao diagnosticar problemas de configuração — se a chave da API estiver faltando, nada mais funcionará.
• Mantenha os prompts de edição incrementais: descreva a mudança, não a cena.
• Sempre encadeie o último ID de interação.
• As gerações são cobradas — agrupe edições relacionadas e prefira thinking_level: low para rascunhos.

A habilidade também agrupa o próprio servidor MCP (mcp/server.py), seus requisitos, um script de instalação e uma cópia vendida do guia do desenvolvedor da API de Interações — então é autossuficiente: instale a habilidade, e você terá tudo o que precisa para também configurar o servidor.

Instalando a habilidade e o servidor MCP no Codex

Você precisa de Python 3.10+, Codex, e uma chave da API do Gemini do Google AI Studio. Há duas partes para instalar:

• A habilidade vai em .agents/skills/nb2lite-image/ para um projeto, ou ~/.agents/skills/nb2lite-image/ para todos os projetos.
• A registro do MCP informa ao Codex como iniciar server.py e quais nomes de variáveis de ambiente encaminhar. A chave da API em si nunca é escrita na configuração do Codex.

Escolha um caminho abaixo. Cada caminho instala ambas as partes, a menos que indicado de outra forma.

Caminho A: O marketplace de plugins (menos toques de teclado)

De um terminal, adicione o marketplace:

codex plugin marketplace ad