Hands-on projects com guias passo a passo
Do primeiro agente CLI ao orquestramento multi-agente: cinco projetos práticos que conectam toda a teoria das trilhas anteriores em implementações reais.
Análise comparativa dos três principais agentes CLI do mercado: Gemini CLI (Google), Claude Code (Anthropic) e Codex CLI (OpenAI), com critérios para escolher o mais adequado ao seu contexto.
A escolha do agente impacta diretamente a experiência, os custos e as integrações disponíveis. Entender as diferenças evita retrabalho e frustrações.
Modelos de linguagem subjacentes, limites de contexto, pricing, ecossistema de plugins, suporte a MCP, licenciamento open-source vs proprietário.
Guia completo de instalação do agente escolhido, cobrindo dependências (Node.js, Python), configuração de API keys e autenticação OAuth quando necessário.
Problemas de setup são a principal causa de desistência. Um processo limpo de instalação garante que você comece a produzir valor rapidamente.
npm/npx, pip/pipx, variáveis de ambiente, API keys, OAuth 2.0, PATH do sistema, versões de runtime, gerenciadores de pacotes.
Sua primeira interação real com o agente no terminal: como formular prompts, entender respostas, usar flags e explorar as capacidades básicas.
A qualidade do prompt determina a qualidade da resposta. Dominar a comunicação com o agente é a habilidade mais fundamental do workflow agent-native.
Prompt engineering no terminal, flags e opções, modo interativo vs one-shot, streaming de resposta, contexto de conversa, temperatura e parâmetros.
Usando o agente para navegar, entender e explicar um repositório de código existente — explorando arquivos, dependências, arquitetura e padrões.
Ler código alheio é uma das tarefas mais comuns e demoradas. Um agente CLI pode acelerar esse processo em ordens de magnitude.
Leitura de arquivos via agente, análise de dependências, mapeamento de arquitetura, contexto de projeto, limites de token, estratégias de navegação.
O momento em que o agente deixa de apenas ler e passa a escrever: editando um arquivo real no seu projeto, com diff review e aprovação humana.
A edição assistida é o core do workflow de desenvolvimento agent-native. Entender como funciona e como revisar é essencial para produtividade e segurança.
Edição de arquivos via agente, diffs, aprovação humana (human-in-the-loop), rollback, git integration, review de mudanças, confiança gradual.
Configuração de sandboxes, políticas de permissão e fluxos de aprovação para que o agente opere com segurança e dentro dos limites definidos por você.
Segurança não é opcional. Configurar permissões corretamente é o que separa uso profissional de uso irresponsável de agentes CLI.
Sandbox modes, allowlists e denylists, políticas de aprovação, escopo de acesso ao filesystem, rede e processos, auditoria de ações.
Visão geral do projeto: um MCP server que gerencia notas pessoais, expondo resources (listar notas) e tools (criar, editar, deletar) para qualquer agente compatível.
Construir um MCP server do zero é a melhor forma de entender o protocolo por dentro. Notas são simples o suficiente para focar no protocolo, não no domínio.
MCP server architecture, resources vs tools, transport layer (stdio), schema definition, capability negotiation.
Inicialização do projeto TypeScript com as dependências do MCP SDK, configuração de tsconfig, estrutura de diretórios e scripts de build.
Um setup correto evita problemas futuros. A estrutura do projeto influencia manutenibilidade e facilidade de teste.
TypeScript setup, @modelcontextprotocol/sdk, tsconfig.json, projeto scaffolding, ESM modules, build pipeline.
Implementação dos resources do MCP: endpoints que o agente pode consultar para ler dados — neste caso, listar notas e ler o conteúdo de uma nota específica.
Resources são a forma como o agente acessa dados do seu sistema. Definir resources claros e bem tipados é a base de qualquer integração MCP.
MCP resources, URI templates, MIME types, resource listing, resource reading, schemas JSON, paginação.
Implementação das tools do MCP: funções que o agente pode invocar para criar, editar e deletar notas, com schemas de input/output bem definidos.
Tools são o mecanismo de ação do agente. Sem tools bem definidas, o agente pode ler mas não pode agir — e ação é o que gera valor.
MCP tools, input schemas (JSON Schema), output schemas, validação, error handling, idempotência, side effects.
Conectando seu MCP server local a um agente real (Claude Code ou Gemini CLI), testando resources e tools, debugando problemas de comunicação.
O teste local é onde teoria vira prática. Ver o agente usando suas tools pela primeira vez é o momento eureka do desenvolvimento MCP.
Configuração de MCP client, stdio transport, debug logging, MCP Inspector, teste manual, verificação de schemas.
Preparando o MCP server para distribuição: build de produção, publicação no npm, Docker container e registro em catálogos de MCP servers.
Um MCP server que funciona local mas não é distribuível tem valor limitado. Publicar é o que torna seu trabalho reutilizável pela comunidade.
npm publish, Docker packaging, versionamento semântico, README para MCP servers, catálogos e marketplaces, CI/CD para MCP.
Seleção estratégica de uma aplicação real para agentificar: critérios de escolha, análise de complexidade e definição do escopo do projeto CLI-Anything.
Nem toda app é igualmente agentificável. Escolher bem o alvo é metade do sucesso — apps com APIs claras e estado previsível são as melhores candidatas.
Critérios de agentificabilidade, análise de APIs existentes, mapeamento de funcionalidades, escopo mínimo viável, complexidade de estado.
Instalação e configuração do framework CLI-Anything: dependências, plugin system, configuração do ambiente de desenvolvimento e primeiros testes.
CLI-Anything é o framework que automatiza a transformação de software em interfaces agent-native. Dominar seu setup é pré-requisito para o pipeline.
CLI-Anything framework, plugin architecture, configuração de ambiente, templates, scaffolding, dependências de runtime.
Execução completa do pipeline CLI-Anything: as 7 fases de transformação aplicadas à app escolhida, do mapeamento inicial ao CLI funcional.
O pipeline é o coração do CLI-Anything. Executá-lo na prática solidifica o entendimento teórico e revela nuances que só aparecem no uso real.
As 7 fases do pipeline, mapeamento funcional, geração de comandos, validação de output, iteração, refinamento de prompts, quality gates.
Análise detalhada dos artefatos gerados pelo pipeline: o CLI executável, o modo REPL interativo, outputs em JSON estruturado e a documentação gerada.
Entender o output permite avaliar qualidade, identificar gaps e iterar. Um CLI bem gerado é composável; um mal gerado é um obstáculo.
CLI structure, REPL mode, JSON output format, help text gerado, man pages, completion scripts, error messages.
Teste sistemático do CLI gerado: execução de cada comando, verificação de estado, validação de outputs e identificação de edge cases.
Testar é validar. Sem testes, você não sabe se o CLI gerado funciona corretamente em todos os cenários que o agente vai encontrar.
Testes de CLI, validação de output, state management, edge cases, error paths, testes de integração, smoke tests.
O passo final: conectando o CLI gerado a um agente via SKILL.md, configurando o agente para descobrir e usar os comandos, fechando o ciclo de agentificação.
A integração com o agente é o objetivo final de todo o processo. Sem ela, você tem um CLI; com ela, você tem uma ferramenta agent-native.
SKILL.md specification, agent discovery, tool registration, capability advertisement, end-to-end testing, agent workflow validation.
Configuração completa do gws: instalação via npm, criação do Google Cloud Project, configuração OAuth 2.0 e autenticação com sua conta Google Workspace.
O setup OAuth do Google é notoriamente complexo. Este guia passo a passo elimina a frustração e garante que você consiga conectar rapidamente.
Google Cloud Console, OAuth 2.0 credentials, scopes de API, consent screen, token refresh, service accounts vs user accounts.
Operações de Gmail via terminal: listar mensagens com filtros, ler conteúdo de emails, enviar novas mensagens e responder threads — tudo via linha de comando.
Email é o canal de comunicação mais usado no trabalho. Operar Gmail via CLI permite automação, scripting e integração com agentes.
Gmail API, queries de busca, labels, threads vs messages, MIME format, attachments, batch operations.
Gerenciamento de Google Drive via terminal: upload e download de arquivos, busca por nome e conteúdo, compartilhamento e organização de pastas.
Drive é o repositório de documentos de milhões de empresas. Acessá-lo via CLI permite automação de fluxos documentais que hoje são manuais.
Drive API, file metadata, MIME types, folder hierarchy, sharing permissions, search queries, resumable uploads.
Operações de Google Sheets via terminal: leitura de ranges, escrita de dados, formatação básica e uso de planilhas como database leve para automações.
Sheets é o "banco de dados" mais popular do mundo corporativo. Ler e escrever dados via CLI abre possibilidades enormes de automação.
Sheets API, A1 notation, ranges, batch updates, value input options, cell formatting, formulas via API.
Gerenciamento de Google Calendar via terminal: listar eventos, criar reuniões, verificar disponibilidade e automatizar agendamento.
Calendário é o sistema de coordenação do trabalho moderno. Automatizar agendamento via CLI economiza horas semanais de trabalho manual.
Calendar API, events CRUD, recurrence rules, timezone handling, free/busy queries, attendees management, reminders.
A integração final: conectando gws ao Gemini CLI para que o agente opere Gmail, Drive, Sheets e Calendar de forma autônoma via linguagem natural.
Esta é a demonstração mais poderosa do paradigma agent-native: um agente que opera todo o Google Workspace via terminal, com linguagem natural.
Tool composition, agent orchestration, natural language to CLI, multi-service workflows, error recovery, permission boundaries.
Design da arquitetura multi-agente: como planejar um fluxo onde múltiplos agentes colaboram, dividindo responsabilidades e coordenando ações.
Problemas complexos exigem múltiplos agentes especializados. Planejar a arquitetura antes de implementar evita gargalos e conflitos.
Multi-agent patterns, orquestrador vs coreografia, divisão de responsabilidades, fluxo de dados, pontos de sincronização, fallback strategies.
Conexão de múltiplos MCP servers a um único agente ou grupo de agentes, criando um toolkit composto que expande as capacidades do sistema.
O poder do MCP está na composição. Um agente com 5 MCP servers conectados é exponencialmente mais capaz que um com apenas 1.
MCP composition, tool namespacing, conflict resolution, capability aggregation, configuration management, dynamic server discovery.
Implementação de uma pipeline end-to-end: agente escreve código, outro faz deploy, outro monitora — demonstrando orquestração real de múltiplos agentes.
Este é o futuro do desenvolvimento: pipelines onde agentes especializados colaboram em cada etapa, do código à produção.
CI/CD agent-native, deploy automation, health checks, monitoring integration, pipeline stages, handoff protocols.
Implementação de observabilidade no sistema multi-agente: logging estruturado, métricas de performance, tracing distribuído e ferramentas de debugging.
Sem observabilidade, sistemas multi-agente são caixas-pretas. Quando algo falha (e vai falhar), você precisa saber onde, quando e por quê.
Structured logging, OpenTelemetry, distributed tracing, metrics collection, dashboards, alerting, agent session replay.
Estratégias de tratamento de erros em sistemas multi-agente: retry policies, circuit breakers, fallbacks, escalação humana e recuperação graceful.
Agentes falham. Modelos alucinam, APIs timeout, permissões expiram. O que diferencia um sistema robusto é como ele lida com falhas.
Error handling patterns, retry with backoff, circuit breaker, human escalation, graceful degradation, compensation transactions, dead letter queues.
Boas práticas para levar sistemas multi-agente para produção: segurança, performance, custos, compliance, monitoramento e operação contínua.
O gap entre demo e produção é enorme. Conhecer as boas práticas evita incidentes, custos descontrolados e problemas de segurança.
Production readiness, rate limiting, cost management, security hardening, compliance frameworks, SLAs, runbooks, incident response.