Aprendendo mais rápido com o Antigravity

Criando frontends Flutter para o ADK

Dash aproveitando o Antigravity

Aprendendo mais rápido com o Antigravity

Criando frontends Flutter para o ADK

Como posso criar um frontend em Flutter para um agente quando esse agente foi construído com um SDK e uma linguagem que eu nunca usei antes?

Esse foi o desafio que enfrentei ao abordar um agente em Python criado com o Agent Development Kit (ADK). Com pouca experiência em Python e nenhuma familiaridade com o framework ADK, construir um cliente que se integrasse ao servidor do backend representava uma curva de aprendizado significativa. Além disso, mesmo que eu conseguisse que um agente de código gerasse algo funcional, terminar o projeto sem entender o código também seria uma forma de fracasso.

Depois de alguns começos falsos, porém, encontrei uma resposta. Usando um fluxo de trabalho estruturado e iterativo com meu parceiro de programação com IA, o Antigravity, criei uma skill de desenvolvedor reutilizável que codificava o que aprendi a cada rodada. Comecei do zero, gerei notas sobre o código, criei vários apps conectados ao deep_search agente (um coordenador de pesquisa multiagente dos exemplos oficiais do repositório de samples do ADK) e fui construindo a skill e minha própria compreensão aos poucos. Em alguns momentos, eu usava vários agentes ao mesmo tempo: um agente “autor” para criar a skill comigo e um agente “programador” para usar essas orientações na construção dos frontends.

O resultado foi uma skill de agente chamada flutter_frontend_for_adk. Ela inclui cinco documentos de referência que guiam o Antigravity por uma sequência de fases, cada uma terminando em uma entrega. As primeiras fases geraram os seguintes arquivos de notas, para que eu pudesse estruturar como o agente “programador” pensava sobre a tarefa enquanto analisava o agente e se preparava para gerar o app:

  • AGENT_INTERFACE_NOTES.md — Notas feitas durante a análise do código-fonte do agente. Qual é o objetivo dele e como ele é construído? Quais são as interfaces e APIs que esse agente expõe e como elas funcionam?

  • FRONTEND_USAGE_NOTES.md — A primeira especificação. O que o frontend deve fazer e como os usuários devem interagir com ele?

  • FRONTEND_ARCHITECTURE_NOTES.md — Um plano de arquitetura. Quais serviços, classes, estados e modelos devem ser criados?

  • FRONTEND_DESIGN_NOTES.md — Um documento de design para o frontend. Como ele vai ser? Quais são as cores, fontes e outros detalhes?

Depois disso, o Antigravity pôde gerar o código do aplicativo, executá-lo e testá-lo. Como a skill (e eu) ainda estamos em desenvolvimento, agora tenho um bom domínio do ADK, além de uma forma útil de criar frontends para agentes existentes.

Foi assim que aconteceu.

Captura de tela de um frontend gerado para o agente deep_search
Captura de tela de um frontend gerado para o agente deep_search

Comece com o trabalho de outras pessoas

Não sou o único escrevendo skills por aqui, então o primeiro passo foi instalar algumas skills das equipes do Google Cloud e do Flutter:

bash
npx skills add google/agents-cli --skill google-agents-cli-adk-code
npx skills add flutter/skills

Elas me deram alguns conhecimentos básicos sobre o ADK, sua ferramenta de CLI e o Flutter. Eu também tinha o servidor MCP do Dart instalado, graças à extensão do Dart para o Antigravity.

Estabeleça o loop

Em vez de começar pedindo ao agente para criar um app de uma vez, estabeleci um tipo de “loop de aprendizado” com ele. Primeiro, pedi ao agente programador que executasse o fluxo de trabalho da minha skill e, em seguida, trabalhei com o agente autor para avaliar manualmente a saída do programador, identificar lacunas nas instruções da skill e atualizar as diretrizes para melhorar as próximas execuções. Após cada iteração, eu apagava as notas geradas e o app, recomeçava e descobria a próxima coisa que precisava aprender.

Aqui está meu loop!
Aqui está meu loop!

O loop consiste em cinco etapas distintas, conduzidas por conversas com o Antigravity:

1) Execute a skill atual: Em uma conversa nova, o agente programador executa o fluxo de trabalho definido pela versão atual do arquivo da skill.

Meu prompt: This codebase includes an agent built with ADK, but no frontend or client. I'd like you to read the instructions in flutter-frontend-for-adk/SKILL.md and follow the workflow. Do not examine git history, do not reference the context of other conversations we've had, and do not change git branches.

2) Avalie a saída e as especificações: Em uma segunda conversa, o agente autor e eu inspecionamos as entregas geradas, como notas de arquitetura, especificações de design e a estrutura do código resultante. Eu era melhor em notar problemas estruturais, enquanto o Antigravity ajudou a identificar todos os detalhes pequenos.

Meu prompt: While I review the notes and code, take a look at the generated artifacts and tell me how well you think they match the instructions and our goals.

3) Identifique lacunas e modos de falha: Identificamos áreas em que o agente programador não tinha orientação específica, fez suposições incorretas ou encontrou problemas de integração.

Meu prompt: I noticed two issues in the last run: first, the root gitignore is ignoring the new frontend/lib/ folder due to a global 'lib/' ignore rule. Second, the coder agent is executing all six phases continuously without stopping. We need a way to pause and verify the deliverables after each stage.

4) Atualize a skill central e as referências: Atualizamos as instruções no SKILL.md ou nos guias auxiliares do diretório references/ para resolver as lacunas.

Meu prompt: Let's update Phase 6 in SKILL.md to explicitly handle the gitignore issue by adding '!frontend/lib' if 'lib/' is ignored globally. Also, add a mandatory 'Review' step at the end of Phases 1 to 4 instructing the agent to pause and wait for my approval before proceeding.

5) Limpe os arquivos locais e execute de novo: Apago os arquivos temporários de especificação, redefino a árvore de trabalho do git e volto ao início do loop.

Trabalhar com um par de agentes definitivamente acelerou as coisas, mas não tornou o processo instantâneo. Eu só consigo absorver tanta informação de uma vez! Dentro de cada iteração, porém, li as notas e os arquivos de código-fonte, revisei a conversa com o Antigravity e (quando já estava gerando código real) executei o app para ver como ele se saía.

No começo, eu estava lendo e aprendendo principalmente. No fim, porém, já entendia o suficiente sobre o que estava acontecendo para focar nas coisas que falhavam de forma consistente, começar a pesquisar por conta própria e ajustar o código para corrigir os problemas. Depois que terminei de modificar as anotações e a base de código, eu perguntava ao Antigravity como ele poderia atualizar a skill para que a geração de código futura ficasse mais parecida com o que eu tinha montado. Como resultado, a skill não era só um conjunto de instruções para o agente programador, mas também um registro do que eu estava aprendendo.

Dando voltas e mais voltas no loop

Foram treze iterações até chegar a algo de que não me envergonho em compartilhar. Estas são as primeiras seis, que foram principalmente sobre descoberta e anotações:

  1. Bootstrapping e mapeamento do workspace — Percebi que um único arquivo monolítico SKILL.md era difícil demais para o agente navegar. Refatorei a skill para ser modular, criando uma pasta dedicada references/ e escrevendo o primeiro guia especializado: references/agent_discovery.md. Isso levou o Antigravity a analisar o código-fonte do agente e a criar AGENT_INTERFACE_NOTES.md para registrar o que ele aprendeu.

  2. Definindo o comportamento e a experiência do usuário — Em seguida veio a especificação de uso do frontend: o que ele faria? Como um usuário interagiria com ele? Adicionei uma nova fase à skill, instruindo-a a ler references/frontend_usage.md e a me entrevistar sobre preferências de plataforma e requisitos de funcionalidades. Isso gerou FRONTEND_USAGE_NOTES.md, que definiu o propósito e o conjunto de funcionalidades do app antes de encostarmos no código.

  3. Definindo o blueprint estrutural — Arquitetura. Adicionamos references/frontend_architecture.md à skill, focado nos detalhes arquiteturais de que o frontend precisaria, e fiz o agente produzir FRONTEND_ARCHITECTURE_NOTES.md.

  4. Desenhando a estética visual — Criamos references/frontend_design.md para instruir o agente sobre como definir a estética visual, e acrescentamos instruções de scaffolding a SKILL.md. Esse guia direcionava o agente a me entrevistar sobre preferências de tema, breakpoints e animações, e o Antigravity começou a produzir FRONTEND_DESIGN_NOTES.md.

  5. Gerando e executando um app — Nesse ponto, consegui pedir ao Antigravity para começar a gerar o código Flutter real com base em todas as especificações que tínhamos reunido. O app falhou de forma bem espetacular, e percebi que era preciso um arquivo geral de “boas práticas” para evitar problemas que provavelmente voltariam. Adicionamos references/frontend_best_practices.md aos arquivos da skill para orientar a codificação em si, e começamos a corrigir as coisas uma por uma.

A partir daí, continuei iterando com o Antigravity, tratando um problema por vez, atualizando o código, atualizando a skill para acompanhar e depois apagando o frontend gerado para tentar de novo. No processo, o loop ficou mais apertado e as mudanças ficaram menores. Fiz mais sete iterações:

  1. O app não consegue fazer chamadas de rede! — Corrigi os entitlements e o info para macOS e iOS.

  2. Todo esse markdown não está sendo formatado! — Usei flutter_markdown para exibir corretamente o texto do agente, que muitas vezes contém markdown.

  3. Por que o código não está saindo certo? — Adicionei lints, regras de formatação e outras verificações pós-geração.

  4. Sealed classes! — Tipos de mensagem diferentes devem compartilhar um tipo base, para que o app possa usar switches exaustivos.

  5. Por que as conversas não rolam? — Adicionei um ScrollController para avançar automaticamente as listas de mensagens quando novas chegam.

  6. Por que o app travou quando rodei na web? — Removi dart:io e passei a depender de package:http para a rede.

  7. Eventos parciais na minha lista! — O ADK envia um fluxo de eventos, às vezes em pedaços. O frontend precisava montar e apresentar os eventos de forma coerente, em vez de mostrar ao usuário uma lista com todos os parciais (e com a formatação markdown quebrada).

  8. Por que a janela de ferramentas está em branco? — Do jeito como foram gerados, os apps não tratavam corretamente as convenções de nomenclatura das ferramentas, e o tratamento de eventos não identificava corretamente quando as ferramentas eram invocadas.

Um exemplo de “coisa que deu errado”

Para você ter uma ideia do trabalho feito em cada iteração, vamos analisar uma das mudanças: como o frontend lida com eventos parciais.

O servidor do ADK transmite eventos que representam pequenos pedaços de conteúdo ou etapas parciais de execução de ferramentas. Se o cliente renderizar cada evento recebido da rede como uma bolha de mensagem individual na lista do chat, porém, a interface fica fragmentada. Uma única resposta do agente apareceria como dezenas de blocos de texto isolados e quebrados.

O jeito antigo (uma lista ingênua):

dart
// Rendering every raw event chunk in a list view
ListView.builder(
  itemCount: rawEvents.length,
  itemBuilder: (context, index) {
    // Each partial text chunk is rendered in a separate bubble
    return ChatBubble(text: rawEvents[index].contentText);
  },
)

Esse código gera uma UI que se parece com isto:

Olha só todos esses itens de lista quebrados e segmentos meio em negrito!
Olha só todos esses itens de lista quebrados e segmentos meio em negrito!

A correção não é particularmente difícil, depois que você sabe o que fazer. Eu não sabia, claro, então comecei a fazer perguntas ao Antigravity, como “Como o ADK usa SSE para transmitir eventos?” e “Como é a estrutura de dados, no fio, de um evento, e como sei se ele é um evento parcial?”. Se “vibe learning” fosse uma coisa, era isso que eu estava fazendo.

Acabou que bastava verificar uma flag, então ajustei o código na classe AgentProvider do frontend, pedi ao Antigravity para revisar caso eu tivesse esquecido algo óbvio, e rodei o app para verificar. Foi preciso mais um pedido ao Antigravity para atualizar as boas práticas, de modo que todo novo frontend usasse essa abordagem.

O jeito novo (agregação no AgentProvider):

dart
await for (final event in stream) {
  if (event.partial && event.contentText != null) {
    // Accumulate streaming text
    _activeStreamingAuthor = event.author;
    _activeStreamingResponse =
        (_activeStreamingResponse ?? '') + event.contentText!;
  } else {
    // Finished chunk: Clear accumulator and add to permanent events list
    _activeStreamingResponse = null;
​
    final updatedEvents = List<Event>.from(_activeSession!.events)
        ..add(event);
​
    // Merge state delta
    Map<String, dynamic> mergedState = _extractSessionStateMap(
      _activeSession!,
    );
    if (event.actions.stateDelta.isNotEmpty) {
      mergedState.addAll(event.actions.stateDelta);
    }
​
    // Build a new copy of the Session with updated events & state
    _activeSession = Session.fromJson({
      'id': _activeSession!.id,
      'app_name': _activeSession!.appName,
      'user_id': _activeSession!.userId,
      'events': updatedEvents.map((ev) => _serializeEvent(ev)).toList(),
      'state': mergedState,
    });
​
    _processCompletedEvent(event);
  }
​
  notifyListeners();
}

Experimente você mesmo

Sou muito adepto de “aprender fazendo”, e me arriscar em algo totalmente fora da minha zona de conforto (uma linguagem nova e um SDK novo) foi bem intimidante. Ter esse loop, porém, me deu uma estrutura para trabalhar, o que ajudou muito, e agora tenho uma skill de agente nova e bacana.

Se você ainda não fez isso, baixe o Antigravity e experimente — levei só algumas horas, e definitivamente aprendi alguns truques novos.

Para começar:

  1. Baixe o Antigravity para integrar o assistente de programação agêntico ao seu ambiente de desenvolvimento.

  2. Visite a documentação Começando com o AGY para aprender a definir suas próprias skills de desenvolvedor e guias de referência.

  3. Escreva uma skill simples para um framework que você queira explorar e continue no loop até conseguir algo de que goste!

Mais do Flutter