agentify.ia — Agentes de IA para Desenvolvedores

Kiro Crew vs Buzz: Agente Autônomo ou Workspace com Agentes?

Tue, 04 Aug 2026 00:00:00 GMT

Kiro Crew vs Buzz: Agente Autônomo ou Workspace com Agentes?

21 de julho de 2026. Jack Dorsey lança o Buzz — um workspace open source onde agentes de IA não são bots integrados, mas membros da equipe com identidade criptográfica própria. Eles abrem repos, enviam patches, revisam código, criam canais, entram em voice huddles. Mesmos privilégios que humanos, mesmo audit trail, keypair diferente.

Enquanto isso, o Kiro Crew segue uma filosofia diferente: um agente autônomo que roda no seu servidor, conecta nos seus chats, e trabalha pra você. Você manda mensagem, ele executa. Simples assim.

Mesma promessa (humanos e agentes trabalhando juntos), arquiteturas completamente diferentes.

O que São

Buzz não é um agente — é um workspace. Pense num Slack + GitHub + CI numa plataforma única, construída sobre Nostr (protocolo descentralizado de mensagens). Todo evento (mensagem, reaction, commit, aprovação de workflow) é assinado criptograficamente. Agentes têm keypairs próprios, independentes da plataforma. Você não "integra" um agente — você adiciona um membro que acontece de ser uma IA.

Kiro Crew é um agente autônomo persistente. Roda no seu servidor, mantém memória entre sessões, conecta em Slack/Telegram/Discord como um bot tradicional. A diferença dos bots comuns: ele aprende com correções (lessons), cria skills reutilizáveis, executa jobs agendados, e mantém um knowledge graph do seu trabalho.

A distinção fundamental: Buzz é onde o trabalho acontece. Kiro Crew é quem faz o trabalho.

Tabela Comparativa

Critério	Buzz	Kiro Crew
Tipo	Workspace colaborativo (Slack-like)	Agente autônomo persistente
Desenvolvedor	Block (Jack Dorsey)	AWS (ex-MeshClaw)
Licença	Apache 2.0	MIT
Protocolo	Nostr (eventos assinados)	HTTP/WebSocket (bot tradicional)
Identidade de agente	Keypair criptográfico próprio	Bot com token de plataforma
Agentes suportados	Claude Code, Codex, Goose, qualquer ACP	Kiro CLI (obrigatório)
Git integrado	Sim (NIP-34: patches, repos, status)	Não (usa git local)
CI/Workflows	YAML workflows nativos	Via Kiro CLI ou MCP
Chat	Canais, threads, DMs, voice huddles	Integração com plataformas externas
Memória	Histórico de eventos (6 meses pesquisável)	Knowledge graph + lessons + skills
Self-hosted	Sim (relay + Postgres + Redis)	Sim (gateway Python + dashboard)
Audit trail	Assinatura criptográfica em cada evento	Audit log assinado
Melhor para	Times que querem agentes como membros	Devs que querem agente pessoal

Análise por Eixo

1. Código (Qualidade)

Buzz não gera código — ele hospeda agentes que geram código. Claude Code, Codex, Goose entram no workspace via ACP (Agent Communication Protocol) e fazem o trabalho. A qualidade depende do agente que você traz. O diferencial: quando o agente faz um commit, ele é assinado com a keypair do agente, não sua. Você sabe exatamente quem escreveu cada linha.

Kiro Crew roda sobre o Kiro CLI, que usa Claude via Bedrock. O workflow specs-driven (requisitos → design → tasks) adiciona uma camada de validação. Lessons acumuladas mudam o comportamento do agente ao longo do tempo. O código melhora conforme você corrige o agente.

Veredicto: Depende. Buzz é agnóstico — a qualidade é do agente que você traz. Kiro Crew tem qualidade consistente via Kiro CLI + aprendizado acumulado.

2. Contexto (Compreensão)

Buzz tem uma abordagem única: tudo é evento pesquisável. Mensagens, commits, reviews, aprovações — 6 meses de histórico em busca unificada. Quando você pergunta "já vimos esse erro antes?", um agente no workspace pode buscar threads, root causes, fixes. O contexto é coletivo — está no workspace, não na cabeça de um agente específico.

Kiro Crew tem contexto individual. Knowledge graph com embeddings, lessons persistentes, skills do agente. O agente lembra do que você ensinou pra ele. Mas esse conhecimento é do agente, não do time.

Veredicto: Buzz ganha em contexto de time. Kiro Crew ganha em contexto individual. Depende se você quer memória compartilhada ou pessoal.

3. Autonomia

Buzz não é autônomo — é um ambiente onde agentes autônomos operam. O agente tem liberdade dentro do workspace: criar canais, enviar patches, aprovar workflows. Mas o workspace é o limite. Buzz não controla seu browser ou email pessoal — é focado em trabalho colaborativo.

Kiro Crew é autônomo no sentido clássico. Roda num servidor, executa comandos, interage com seu sistema. Conecta em múltiplas plataformas de chat. Faz coisas fora do contexto de um workspace específico.

Veredicto: Autonomias diferentes. Buzz: autonomia de membro de time. Kiro Crew: autonomia de agente pessoal.

4. Velocidade

Buzz adiciona overhead de workspace — relay Nostr, assinatura de eventos, propagação. Mas o trade-off é rastreabilidade. Cada ação é um evento assinado, auditável depois. Para trabalho síncrono onde você quer respostas imediatas, é mais lento que um bot direto.

Kiro Crew é bot tradicional: você manda mensagem, ele processa, responde. O overhead é do gateway Python e do Kiro CLI. Mais direto, menos cerimônia.

Veredicto: Kiro Crew ganha em interação rápida. Buzz compensa com rastreabilidade.

5. Custo-benefício

Buzz é gratuito (Apache 2.0). Self-hosted com Postgres, Redis, MinIO. Você paga infra e os agentes que traz (Claude Code, Codex são pagos). Existe versão hosted da Block, mas o foco é self-host.

Kiro Crew também é gratuito (MIT), mas depende do Kiro CLI (pago após 50 créditos/mês). O custo real é a assinatura Kiro.

Veredicto: Buzz ganha se você já paga agentes separadamente. Kiro Crew empata se você já usa Kiro.

6. Especialização (Skills)

Buzz tem "persona packs" — configurações de personalidade e comportamento para agentes. Mas skills como sistema formal não existe. A especialização vem dos agentes que você traz (Claude Code tem skills, Codex tem suas capacidades).

Kiro Crew tem skills como cidadão de primeira classe. O agente cria skills de padrões repetidos. Você edita como Markdown. Skills são portáveis entre projetos.

Veredicto: Kiro Crew ganha em skills formais. Buzz delega pra especialização dos agentes externos.

7. Multi-agente

Buzz foi construído pra multi-agente. Agentes são membros do workspace. Você pode ter Claude Code fazendo backend, outro agente em frontend, um terceiro revisando PRs. Todos no mesmo workspace, com identidades separadas, audit trail unificado. Um agente pode orquestrar outros.

Kiro Crew suporta múltiplas conversas e subagentes, mas é fundamentalmente um agente (ou família de agentes) trabalhando pra você. Não é um ambiente onde múltiplos agentes de diferentes origens colaboram naturalmente.

Veredicto: Buzz ganha de lavada. Multi-agente é a razão de existir.

8. Ecossistema

Buzz é novo (julho 2026), mas tem backing da Block e integração com agentes populares via ACP. Suporta Claude Code, Codex, Goose out of the box. Git nativo (NIP-34), workflows YAML, canais de chat. É um ecossistema self-contained.

Kiro Crew herda o ecossistema Kiro — MCP servers, steering files, integração com Kiro IDE. Se você já usa Kiro, a transição é natural. Mas é dependente do Kiro CLI.

Veredicto: Buzz ganha em independência (funciona com múltiplos agentes). Kiro Crew ganha em integração profunda com ecossistema Kiro/AWS.

Filosofias Opostas

A diferença fundamental:

Buzz diz: "Agentes são membros da equipe. Dê a eles o mesmo ambiente que humanos têm. Mesmos canais, mesmos repos, mesmas ferramentas. Identidade criptográfica pra você saber quem fez o quê."

Kiro Crew diz: "Agentes são assistentes pessoais que aprendem com você. Rode no seu servidor, conecte nos seus chats, trabalhe enquanto você dorme. O conhecimento é seu, não do time."

Se você quer substituir Slack + GitHub por um workspace unificado onde agentes são pares: Buzz.

Se você quer um agente pessoal que conecta nas ferramentas que você já usa: Kiro Crew.

Quando Escolher Cada Um

Escolha Buzz se:

Você quer agentes como membros da equipe, não bots
Precisa de audit trail criptográfico (compliance, segurança)
Quer unificar chat, git e CI num lugar só
Trabalha com múltiplos agentes de diferentes providers
Valoriza identidade descentralizada (Nostr)
Está construindo um time híbrido humano-agente

Escolha Kiro Crew se:

Você quer um agente pessoal que aprende com você
Prefere conectar nas ferramentas existentes (Slack, Telegram)
Valoriza memória individual e lessons persistentes
Já usa Kiro CLI ou ecossistema AWS
Quer simplicidade: mandar mensagem, receber resultado
Trabalha solo ou em time pequeno sem precisar de workspace dedicado

Use Ambos se:

Buzz como workspace do time para projetos colaborativos
Kiro Crew como agente pessoal para tarefas individuais

São complementares, não concorrentes.

Veredicto Final

Buzz é uma aposta no futuro do trabalho. A ideia de que agentes não são ferramentas, mas colegas de trabalho com identidade própria, é poderosa. Se essa visão se concretiza, Buzz está bem posicionado. Mas é novo (julho 2026), ainda em versão 0.4.x, com features planejadas mas não entregues.

Kiro Crew é pragmático. Um agente que roda no seu servidor, aprende com suas correções, e faz trabalho enquanto você não está. Não reinventa o workspace — conecta no que você já usa. Menos visionário, mais imediatamente útil.

Se você está construindo o futuro do trabalho humano-agente: Buzz. Se você quer um agente que funciona hoje: Kiro Crew.

Dados verificados em agosto de 2026. Buzz v0.4.22, Kiro Crew latest.

Kiro Crew vs Hermes Agent: AWS Enterprise ou Self-Improving Open Source?

Tue, 04 Aug 2026 00:00:00 GMT

Kiro Crew vs Hermes Agent: AWS Enterprise ou Self-Improving Open Source?

Fevereiro de 2026. A Nous Research — o lab por trás dos modelos Hermes, Nomos e Psyche — lança o Hermes Agent. Em sete semanas, alcança 151.000 stars no GitHub. Em maio, ultrapassa 152.000. O agente mais rápido da história a atingir esse marco.

O diferencial: um learning loop fechado. O agente cria skills a partir da experiência, melhora essas skills durante o uso, persiste conhecimento entre sessões, e constrói um modelo cada vez mais profundo de quem você é. Quanto mais tempo roda, mais capaz fica.

O Kiro Crew, da AWS, tem proposta similar — memória persistente, lessons que mudam comportamento, skills reutilizáveis. Mas vem de dentro da Amazon, roda sobre o Kiro CLI (pago), e foca em governança enterprise.

Duas abordagens para o mesmo problema: agentes que melhoram com o tempo.

O que São

Hermes Agent é um framework open source da Nous Research para agentes autônomos self-improving. Não é copilot de IDE nem wrapper de chatbot. É um agente que roda no seu servidor (VPS de $5, cluster GPU, ou serverless), conecta em 20+ plataformas de chat, e fica mais capaz conforme usa. O learning loop é core: o agente cria skills, melhora essas skills, persiste memória, e modela seu comportamento ao longo do tempo.

Kiro Crew é uma extensão do ecossistema Kiro da AWS. Começou como projeto interno (MeshClaw), foi adotado por 39.000 devs dentro da Amazon, e virou open source. Roda sobre o Kiro CLI (obrigatório), traz memória persistente via knowledge graph, lessons (correções viram regras), skills, cron jobs, webhooks, e dashboard web.

Ambos são agentes autônomos persistentes com aprendizado. A diferença está em como aprendem e onde rodam.

Tabela Comparativa

Critério	Hermes Agent	Kiro Crew
Tipo	Framework de agente self-improving	Extensão do Kiro CLI
Desenvolvedor	Nous Research	AWS (ex-MeshClaw)
GitHub Stars	152.000+	~5.000 (recém-lançado)
Licença	MIT	MIT
Preço	Gratuito (você paga LLM ou usa local)	Gratuito (você paga Kiro CLI)
LLM Backend	Qualquer (Nous Portal, OpenRouter, OpenAI, local)	Kiro CLI (Claude via Bedrock)
Learning Loop	Closed loop: cria → melhora → persiste	Lessons + skills (sem auto-improvement)
Memória	FTS5 + LLM summarization + Honcho user modeling	Knowledge graph + embeddings
Skills	Agentskills.io compatível, auto-criação	Markdown files, criação manual/assistida
Backends de execução	Local, Docker, SSH, Daytona, Singularity, Modal	Local, Docker
Chat Platforms	20+ (Telegram, Discord, Slack, WhatsApp, Signal, Matrix...)	6 (Slack, Telegram, Discord, Teams, WeChat, Webex)
Voice	Sim (CLI, Telegram, Discord, Discord VC)	Não
Tools built-in	60+	Via Kiro CLI + MCP
Dashboard	Não (CLI-first)	Sim (React web)
Governança/Audit	Básico	Sandbox + audit log assinado
Melhor para	Power users, devs que querem controle total	Times enterprise, usuários Kiro/AWS

Análise por Eixo

1. Código (Qualidade)

Hermes Agent não depende de modelo específico. Você pode usar Claude via Nous Portal, OpenRouter, OpenAI direto, ou modelos locais. A qualidade do código depende do modelo que você configura. Com Claude Sonnet 4.6, excelente. Com modelo local fraco, fraco. Hermes não adiciona "inteligência" — adiciona persistência, memória e aprendizado.

Kiro Crew roda sobre Kiro CLI, que usa Claude via Bedrock com o agente Auto (routing inteligente entre modelos). O workflow specs-driven adiciona validação: requisitos → design → tasks antes de codar. Lessons acumuladas mudam comportamento. O código é mais consistente ao longo do tempo porque o agente aprende suas preferências.

Veredicto: Empate com nuance. Hermes dá mais flexibilidade de modelo. Kiro Crew dá mais consistência via specs + lessons.

2. Contexto (Compreensão)

Hermes Agent tem o sistema de memória mais sofisticado do mercado:

FTS5 cross-session recall com LLM summarization
Honcho dialectic user modeling — constrói um modelo de quem você é
Skill memory — procedural memory que o agente cria e reutiliza
Periodic nudges — o agente se auto-lembra de persistir conhecimento

O learning loop é fechado: o agente não só armazena memória, ele usa a memória pra melhorar skills, que por sua vez melhoram a memória. É um ciclo de auto-aprimoramento.

Kiro Crew tem knowledge graph com embeddings e busca full-text, lessons persistentes, e skills. Mas não tem o ciclo fechado — lessons são passivas (mudam comportamento quando acionadas), não ativas (o agente não melhora lessons automaticamente).

Veredicto: Hermes ganha. O learning loop fechado é o diferencial principal do projeto.

3. Autonomia

Hermes Agent é maximamente autônomo. Roda em 6 backends diferentes (local, Docker, SSH, Daytona, Singularity, Modal). Pode rodar serverless que hiberna quando idle (custo quase zero). Delega pra subagentes em parallel workstreams. Executa código programaticamente via execute_code.

Kiro Crew é autônomo dentro de guardrails. Sandbox de OS, comandos negados por padrão, audit log de cada ação. O foco é autonomia governada — o agente pode fazer muito, mas você sabe exatamente o quê.

Veredicto: Hermes ganha em flexibilidade de execução. Kiro Crew ganha em governança.

4. Velocidade

Hermes Agent é otimizado pra eficiência. Roda em VPS de $5, pode usar serverless que hiberna. 60+ tools built-in. Programmatic Tool Calling via execute_code colapsa pipelines multi-step em single inference calls. É rápido porque é leve.

Kiro Crew tem mais overhead: gateway Python, dashboard React, banco de embeddings (~610MB). Requer mais recursos (4GB+ RAM recomendado). Mas o Kiro CLI por baixo é otimizado, e o agente Auto faz routing inteligente pra modelos mais rápidos quando possível.

Veredicto: Hermes ganha em leveza. Kiro Crew é mais pesado mas compensado pelo routing do Auto.

5. Custo-benefício

Hermes Agent é gratuito. Você paga apenas o LLM — e pode usar:

Nous Portal (subscription que inclui web search, image gen, TTS, browser)
OpenRouter (pay-per-token)
OpenAI direto
Modelos locais (custo zero)

Flexibilidade total. Quer custo zero? Rode local. Quer conveniência? Use Nous Portal.

Kiro Crew é gratuito, mas depende do Kiro CLI (50 créditos/mês free, depois pago). O custo real é a assinatura Kiro ($20-$200/mês).

Veredicto: Hermes ganha. Flexibilidade de custo incomparável.

6. Especialização (Skills)

Hermes Agent tem skills como cidadão de primeira classe:

Agentskills.io compatível — skills portáveis entre plataformas
Auto-criação — o agente cria skills a partir de padrões
Self-improvement — o agente melhora skills durante o uso
Skills Hub — comunidade compartilha skills

O ciclo é: usar → detectar padrão → criar skill → usar skill → melhorar skill. Closed loop.

Kiro Crew tem skills como arquivos Markdown. Você cria ou o agente sugere. Mas não tem auto-improvement — skills são estáticas até você editar manualmente.

Veredicto: Hermes ganha. Skills self-improving vs skills estáticas.

7. Multi-agente

Hermes Agent suporta subagentes em parallel workstreams. Delega trabalho, recebe resultados. Programmatic Tool Calling permite orquestração sofisticada.

Kiro Crew também suporta subagentes com Activity view no dashboard. Múltiplas conversas simultâneas com contexto isolado.

Veredicto: Empate técnico. Ambos suportam bem, com interfaces diferentes (CLI vs dashboard).

8. Ecossistema

Hermes Agent tem:

152.000+ stars, comunidade massiva
60+ tools built-in
20+ plataformas de chat
Agentskills.io compatibilidade
Suporte MCP
Batch processing e training com Atropos (research-ready)

Kiro Crew tem:

Ecossistema Kiro (MCP, steering files, integração com IDE)
Dashboard web
Audit log enterprise
Integração AWS nativa

Veredicto: Hermes ganha em comunidade e breadth. Kiro Crew ganha em integração enterprise/AWS.

O Learning Loop

A diferença fundamental entre os dois está no learning loop.

Hermes Agent tem um ciclo fechado de auto-aprimoramento:

Usar → Detectar padrão → Criar skill
         ↑                    ↓
   Melhorar skill ← Usar skill

O agente não só aprende — ele melhora o que aprendeu. Quanto mais tempo roda, mais capaz fica. Isso é único no mercado.

Kiro Crew tem aprendizado passivo:

Correção → Lesson salva → Lesson aplicada quando relevante

Lessons mudam comportamento, mas não melhoram sozinhas. Você precisa editar manualmente. É aprendizado, mas não auto-aprimoramento.

Se você quer um agente que fica melhor automaticamente: Hermes. Se você quer controle total sobre o que o agente aprende: Kiro Crew.

Quando Escolher Cada Um

Escolha Hermes Agent se:

Você quer o sistema de memória mais sofisticado disponível
Valoriza auto-aprimoramento (skills que melhoram sozinhas)
Quer flexibilidade total de modelo (local, cloud, qualquer provider)
Precisa de 20+ plataformas de chat
Quer voice mode (CLI, Telegram, Discord VC)
Valoriza leveza (roda em VPS de $5)
Quer comunidade massiva e skills compartilhadas

Escolha Kiro Crew se:

Você precisa de governança enterprise (audit log, sandbox)
Já usa Kiro CLI ou ecossistema AWS
Prefere dashboard web vs CLI
Quer controle manual sobre o que o agente aprende
Trabalha em time que precisa de rastreabilidade
Valoriza integração com Kiro IDE (mesma config)

Use Ambos se:

Hermes pra projetos pessoais e experimentação
Kiro Crew pra trabalho de time com compliance

São complementares se você tem contextos diferentes.

Veredicto Final

Hermes Agent é tecnicamente superior em memória e aprendizado. O learning loop fechado, as 20+ plataformas de chat, a flexibilidade de modelo, e a comunidade de 152.000+ fazem dele a escolha óbvia pra quem quer o agente mais capaz sem lock-in.

Kiro Crew é a escolha enterprise. Se você precisa explicar pro compliance o que o agente fez, se quer dashboard em vez de CLI, se já está no ecossistema AWS/Kiro — faz sentido. Menos flexível, mais controlável.

A pergunta: você quer o agente mais capaz ou o mais governável?

Para máxima capacidade e auto-aprimoramento: Hermes Agent. Para governança e integração enterprise: Kiro Crew.

Dados verificados em agosto de 2026. Hermes Agent latest, Kiro Crew latest. Stars do momento da publicação.

Kiro Crew vs OpenClaw: AWS Enterprise ou Comunidade Viral?

Tue, 04 Aug 2026 00:00:00 GMT

Kiro Crew vs OpenClaw: AWS Enterprise ou Comunidade Viral?

Janeiro de 2026. Um projeto chamado ClawdBot aparece no GitHub e explode. Renomeado para OpenClaw, alcança 382.000 stars em seis meses — quase quadruplicando desde o lançamento. Jensen Huang da NVIDIA chama de "provavelmente o lançamento de software mais importante de todos os tempos". Mais de 2.7 milhões de downloads npm numa única semana.

Enquanto isso, dentro da Amazon, um projeto interno chamado MeshClaw cresce silenciosamente entre 39.000 desenvolvedores. Seis meses depois, vira open source como Kiro Crew — a resposta enterprise da AWS para agentes autônomos persistentes.

Duas ferramentas. Mesma categoria. Filosofias radicalmente diferentes.

O que São

Ambos são agentes autônomos persistentes — rodam num servidor 24/7, mantêm memória entre sessões, conectam em plataformas de chat, e continuam trabalhando enquanto você dorme. Mas a semelhança termina aí.

OpenClaw é um framework Node.js que virou fenômeno viral. Criado por Peter Steinberger, conecta em WhatsApp, Telegram, Discord, Slack, iMessage, Signal — basicamente qualquer app de mensagem que você já usa. A proposta: um assistente pessoal de IA que vive no seu chat, controla seu browser, gerencia seu email, e vibe-coda aplicações inteiras.

Kiro Crew é uma extensão do ecossistema Kiro da AWS. Roda sobre o Kiro CLI (obrigatório), usa os mesmos steering files do Kiro IDE, e traz memória persistente, lessons (aprendizado com correções), skills reutilizáveis, cron jobs, webhooks, e um dashboard web. A proposta: um agente de codificação enterprise que mantém contexto, aprende com feedback, e integra com sua infra AWS.

Tabela Comparativa

Critério	OpenClaw	Kiro Crew
Tipo	Framework de agente autônomo (Node.js)	Extensão do Kiro CLI (Python)
Desenvolvedor	Peter Steinberger + comunidade	AWS (ex-MeshClaw interno)
GitHub Stars	382.000+	~5.000 (recém-lançado)
Licença	MIT	MIT
Preço	Gratuito (você paga o LLM)	Gratuito (você paga o Kiro CLI)
LLM Backend	Qualquer (Claude, GPT, DeepSeek, local)	Kiro CLI (Claude via Bedrock)
Chat Platforms	WhatsApp, Telegram, Discord, Slack, iMessage, Signal	Slack, Telegram, Discord, Teams, WeChat, Webex
Memória	Simples (por conversa)	Knowledge graph + embeddings + FTS
Aprendizado	Básico	Lessons (correções viram regras) + Skills
Jobs agendados	Não nativo	Cron jobs + webhooks + heartbeats
Dashboard	Não	Sim (React, local)
Controle de browser	Sim (Playwright, Puppeteer)	Via MCP servers
Governança/Audit	Básico	Sandbox + audit log assinado
Melhor para	Assistente pessoal, automação geral	Codificação enterprise, times AWS

Análise por Eixo

1. Código (Qualidade)

OpenClaw não nasceu pra ser um agente de codificação — é um assistente geral que também coda. A qualidade do código depende 100% do LLM que você configura. Com Claude Sonnet 4.6, você terá código excelente. Com um modelo local fraco, terá código fraco. OpenClaw não adiciona nada em cima — é um passthrough para o modelo.

Kiro Crew é construído sobre o Kiro CLI, que traz o workflow specs-driven da AWS. Quando você pede uma feature, o agente pode gerar specs (requisitos → design → tasks) antes de codar. Isso adiciona uma camada de rigor que OpenClaw não tem. O código é validado contra a spec, não apenas contra o prompt.

Veredicto: Kiro Crew ganha em contexto de codificação estruturada. OpenClaw é agnóstico — a qualidade depende do modelo.

2. Contexto (Compreensão)

OpenClaw mantém contexto por conversa. Não tem memória sofisticada entre sessões — se você reiniciar, perde o contexto. Projetos da comunidade adicionam persistência, mas não é core.

Kiro Crew tem um sistema de memória de três camadas:

Memory.db: banco vetorial com embeddings para busca semântica
Lessons: correções que viram regras persistentes
Skills: procedimentos reutilizáveis criados pelo próprio agente

Quando você corrige o Kiro Crew ("não, use snake_case em Python"), isso vira uma lesson que afeta todas as interações futuras. OpenClaw não aprende — cada conversa começa do zero.

Veredicto: Kiro Crew ganha com folga. A memória persistente e o aprendizado com correções são diferenciais reais.

3. Autonomia

OpenClaw é maximamente autônomo — e esse é o ponto. Ele controla seu browser, lê seu email, manda mensagens, executa código, faz deploy. A filosofia é "dê acesso e saia do caminho". Isso assusta muita gente (e com razão), mas é o que fez o projeto viralizar.

Kiro Crew é autônomo dentro de limites. Sandbox de OS, comandos negados por padrão, validação de input, bloqueio de padrões suspeitos. O agente pode fazer muito, mas cada ação é auditada e você pode configurar aprovações. É autonomia governada.

Para uso pessoal onde você confia no agente, OpenClaw é mais poderoso. Para uso em contexto profissional onde você precisa explicar o que o agente fez, Kiro Crew é mais seguro.

Veredicto: OpenClaw ganha em autonomia bruta. Kiro Crew ganha em autonomia com governança.

4. Velocidade

OpenClaw é leve — Node.js puro, sem overhead. Conecta em serviços de chat nativamente e repassa prompts direto pro LLM. A latência é essencialmente a latência do modelo que você usa.

Kiro Crew tem mais partes móveis: gateway Python, dashboard React, banco de embeddings. O modelo de embeddings (~610MB) precisa baixar na primeira execução. Requer mais RAM (4GB+ recomendado vs 2GB do OpenClaw).

Para tarefas simples de chat, OpenClaw responde mais rápido. Para tarefas complexas onde memória e contexto importam, Kiro Crew compensa o overhead com melhor compreensão.

Veredicto: OpenClaw ganha em leveza. Kiro Crew ganha em tarefas que precisam de contexto profundo.

5. Custo-benefício

OpenClaw é gratuito. Você paga apenas pelo LLM — e pode usar modelos locais (llama.cpp, Ollama) para custo zero. A comunidade mantém integrações com dezenas de providers.

Kiro Crew também é gratuito, mas depende do Kiro CLI, que tem tier gratuito de 50 créditos/mês. Pra uso sério, você vai precisar de um plano Kiro ($20-$200/mês). É grátis no software, pago no backend.

Se você quer rodar local com modelo open-weight, OpenClaw é a escolha óbvia. Se você já paga Kiro CLI ou usa AWS, Kiro Crew não adiciona custo.

Veredicto: OpenClaw ganha se você quer custo zero. Kiro Crew ganha se você já está no ecossistema Kiro/AWS.

6. Especialização (Skills)

OpenClaw não tem sistema de skills nativo. A customização vem de prompts de sistema e integrações que você configura. A comunidade criou "recipes" — configurações prontas para casos de uso — mas não é um sistema formal.

Kiro Crew tem skills como cidadão de primeira classe. O agente cria skills a partir de padrões repetidos. Você pode editar, escopar por workspace, ou deletar. Skills são arquivos Markdown no mesmo formato de steering files do Kiro IDE — portáveis e versionáveis.

Kiro Crew também herda custom agents do Kiro CLI: personas especializadas com permissões, contexto e ferramentas pré-configuradas.

Veredicto: Kiro Crew ganha. Skills como sistema formal vs customização ad-hoc.

7. Multi-agente

OpenClaw não foca em multi-agente. Você roda uma instância por pessoa. Coordenação entre múltiplos agentes não é um caso de uso central.

Kiro Crew suporta múltiplas conversas simultâneas, cada uma com contexto isolado. Delega para subagentes que retornam resultados pro agente principal. O dashboard mostra todas as conversas e tarefas em execução (Activity view).

Veredicto: Kiro Crew ganha. Multi-agente é feature core vs não existente.

8. Ecossistema

OpenClaw tem a maior comunidade de agentes autônomos do mundo. 382.000 stars, 2.7 milhões de downloads semanais, centenas de contribuidores. Se você tem um problema, alguém já resolveu. A quantidade de integrações, recipes e extensões é incomparável.

Kiro Crew é recém-lançado como open source. A comunidade ainda está se formando. Mas herda o ecossistema Kiro — MCP servers, steering files, integração com Kiro IDE. Se você já usa Kiro, a transição é natural.

Veredicto: OpenClaw ganha em comunidade e maturidade. Kiro Crew ganha em integração com ecossistema AWS/Kiro.

Filosofias Opostas

A diferença fundamental não é técnica — é filosófica.

OpenClaw é empoderamento individual. Um assistente pessoal que faz o que você manda, sem burocracia. A comunidade decide o que é aceitável. A governança é mínima por design. Isso é libertador para uso pessoal e assustador para uso corporativo.

Kiro Crew é autonomia com responsabilidade. Um agente que aprende, mas dentro de guardrails. Audit log de cada ação. Sandbox de comandos. Integração com infra enterprise. Isso é tranquilizador para times e limitante para power users.

Se você quer um agente que controle seu email e browser pessoais, OpenClaw. Se você quer um agente que ajude seu time a codar com rastreabilidade, Kiro Crew.

Quando Escolher Cada Um

Escolha OpenClaw se:

Você quer um assistente pessoal all-in-one
Prefere rodar modelos locais (custo zero)
Valoriza autonomia máxima sobre governança
Quer a maior comunidade e mais integrações
Seu caso de uso é automação geral, não só codificação
Você é dev solo ou usa para projetos pessoais

Escolha Kiro Crew se:

Você quer um agente focado em codificação enterprise
Precisa de memória persistente e aprendizado com correções
Valoriza governança, audit log e sandbox
Já usa Kiro CLI ou tem infra AWS
Trabalha em time e precisa de rastreabilidade
Quer integrar com Slack/Teams/Telegram profissional

Use Ambos se:

OpenClaw para automação pessoal (email, browser, tarefas domésticas)
Kiro Crew para trabalho de codificação com o time

Não são mutuamente exclusivos. OpenClaw é seu assistente pessoal. Kiro Crew é seu colega de equipe virtual.

Veredicto Final

OpenClaw é o fenômeno. A comunidade decidiu que agentes autônomos são o futuro, e OpenClaw é onde isso está acontecendo. Se você quer estar na fronteira, com acesso às últimas integrações e recipes da comunidade, é a escolha óbvia.

Kiro Crew é a resposta enterprise. Se você precisa explicar pro seu chefe o que o agente fez, se precisa de audit log pra compliance, se quer aprendizado que persiste entre sessões — Kiro Crew entrega o que OpenClaw não prioriza.

A pergunta não é "qual é melhor". É "qual problema você está resolvendo".

Para assistente pessoal que faz de tudo: OpenClaw. Para agente de codificação com governança de time: Kiro Crew.

Dados verificados em agosto de 2026. OpenClaw v3.x, Kiro Crew latest. Stars e downloads do momento da publicação.

Kiro Crew: O Agente que Trabalha Enquanto Você Dorme

Tue, 04 Aug 2026 00:00:00 GMT

Kiro Crew: O Agente que Trabalha Enquanto Você Dorme

Sexta-feira, fim de tarde. Você está prestes a desligar quando um colega manda uma mensagem: "aquele bug de latência voltou". Você lembra vagamente de ter resolvido algo parecido meses atrás — os logs que olhou, os testes que rodou, onde encontrou o problema. Não é difícil. Só que requer estar em vários lugares ao mesmo tempo, conectando contexto entre ferramentas.

Isso é trabalho de engenharia real. Nunca foi uma tarefa, uma sessão, um prompt. É um fluxo que atravessa repositórios, ferramentas, revisões e dias. E no momento que você sai, tudo para e espera você voltar.

O Kiro Crew assume esse trabalho. Você manda uma mensagem pedindo pra ele encontrar o que você fez da última vez, documentar e enviar pro colega. Fecha o notebook e vai curtir o fim de semana. Mais tarde, recebe a notificação de que o problema foi resolvido.

O que é o Kiro Crew

Kiro Crew é um projeto open source desenvolvido internamente na Amazon (originalmente chamado MeshClaw) que estende o Kiro CLI para funcionar como um agente autônomo persistente. Ele roda num servidor — seu laptop, uma VPS, um Raspberry Pi, um container — e continua trabalhando mesmo quando você não está olhando.

A proposta: você delega tarefas, e o agente:

Mantém contexto entre sessões — memória de preferências, projetos ativos, histórico de decisões
Aprende com correções — erros viram "lessons" que mudam comportamento futuro
Trabalha em paralelo — múltiplas conversas, múltiplos subagentes
Segue cronogramas — cron jobs, heartbeats, webhooks
Conecta seus canais — Slack, Telegram, Discord, Teams, WeChat

Em menos de 6 meses dentro da Amazon, o projeto foi adotado por mais de 39.000 desenvolvedores, com quase 500 contribuidores enviando 567 atualizações numa média de 143 commits por semana. Não cresceu por causa da arquitetura — cresceu porque as pessoas podiam moldar pra suas próprias necessidades.

Como Funciona

O Kiro Crew opera em cima do Kiro CLI via Agent Client Protocol (ACP). Você instala o Kiro CLI, faz login, e o Crew usa ele como backend para executar tarefas.

A arquitetura tem três camadas:

1. Gateway (backend Python)

O núcleo do sistema. Gerencia:

Sessões de chat — conversas persistentes com contexto
Memória — banco vetorial + full-text search para recuperar contexto relevante
Lessons e Skills — arquivos Markdown que você inspeciona, edita ou remove
Cron jobs — tarefas recorrentes com cadência definida
Webhooks — disparo de ações via eventos externos

2. Dashboard (React)

Interface web local para:

Visualizar e gerenciar conversas
Acompanhar tarefas em execução (Activity view)
Editar memória, lessons e skills
Configurar jobs e integrações
Ver audit log de todas as ações

3. Integrações de Chat

Bots para Slack, Telegram, Discord, Teams e WeChat que conectam o agente aos canais onde você já trabalha. Manda uma mensagem pro bot, e ele executa no servidor e responde.

O que o Diferencia

Memória que Sobrevive Reboot

Preferências, contexto de projeto e histórico relevante são armazenados num knowledge graph com embeddings vetoriais e busca full-text. Quando você inicia uma nova conversa, o agente recupera o que importa em vez de reler tudo do zero.

Lessons e Skills Transparentes

Correções viram lessons — arquivos Markdown que você pode ler e editar. Padrões repetidos viram skills reutilizáveis. Tudo no mesmo formato de steering files que o Kiro IDE e CLI já usam.

Trabalha Enquanto Você Descansa

Jobs recorrentes rodam em schedule. Um digest matinal pode coletar PRs abertos. Um heartbeat pode monitorar um deploy até mudar de estado. Um webhook pode iniciar trabalho quando um evento externo acontece.

Coordena Múltiplos Agentes

Rode várias conversas simultâneas, cada uma com contexto isolado. Delegue pesquisa e implementação pra subagentes que retornam resultados pro agente principal.

Apps com Interface Própria

Tem trabalho que não cabe em chat. Pra esses casos, o Crew suporta Apps — interfaces feitas sob medida que combinam UI customizada com agentes, skills e integrações. O Issue Radar triageia issues. O Task Runner executa tarefas longas. O DevFleets gerencia work trees.

Segurança desde o Commit Zero

Sandbox de OS, comandos negados por padrão, bloqueio de padrões suspeitos, validação de input, redação de credenciais, e audit log assinado de cada ação. Porque é open source, você pode auditar cada camada.

Quando Usar

O Kiro Crew faz sentido quando seu trabalho:

Atravessa sessões — migrações, investigações multi-repo, PRs que precisam de monitoramento
Precisa de memória — você não quer reexplicar contexto toda vez
Beneficia de automação — digests matinais, scans recorrentes, respostas a eventos
Requer acesso remoto — você quer mandar uma mensagem do celular e o agente executar no servidor

Não faz sentido se você só precisa de um agente de codificação local para pair programming. Pra isso, o Kiro CLI ou IDE sozinhos resolvem.

Arquitetura de Deploy

O Crew pode rodar de várias formas:

Modo	Descrição	Melhor para
Local	No seu laptop/desktop	Dev solo, testes
Remote Host	VPS, VM, servidor dedicado	Disponibilidade 24/7
Container	Docker oficial	Deploy padronizado, Coolify/Kubernetes
Home Server	Raspberry Pi, NUC	Baixo custo, controle total

Todos compartilham a mesma configuração: env vars para tokens de chat, URL do dashboard, e o Kiro CLI autenticado.

Integrações Disponíveis

Chat Platforms

Slack — app com Socket Mode
Telegram — bot com long polling
Discord — bot tradicional
Microsoft Teams — app registrado
WeChat — WeCom enterprise
Webex — integração Cisco

Acesso Remoto

SSH Tunnel — acesso do laptop
HTTPS Tunnel — acesso do celular (cloudflared, ngrok, Tailscale Funnel)
Dashboard local — interface web em localhost:5476

Extensibilidade

MCP Servers — tools externos
Webhooks — disparo por eventos
Apps — interfaces customizadas

Prós e Contras

Prós

Open source de verdade — código aberto, governança pública, contribuições aceitas
Memória persistente — contexto sobrevive sessões e restarts
Multi-plataforma de chat — trabalhe de onde você já está (Telegram, Slack, etc.)
Jobs e webhooks — automação sem babysitting
Audit log completo — transparência total de ações
Segurança built-in — sandbox, redação de secrets, validação

Contras

Complexidade de setup — mais partes móveis que um agente local
Requer infra — você precisa de um servidor rodando 24/7
Kiro CLI obrigatório — depende da autenticação AWS/Kiro
Dashboard local only — acesso remoto requer tunnel ou proxy
Em evolução rápida — 143 commits/semana significa breaking changes frequentes

Comparativo Rápido

Aspecto	Kiro CLI	Kiro Crew
Execução	Local, sessão única	Persistente, servidor
Memória	Contexto de conversa	Knowledge graph + lessons
Chat	Terminal	Slack, Telegram, Discord, etc.
Jobs	Manual	Cron, webhooks, heartbeats
Subagentes	Sim	Sim, com Activity view
UI	Terminal	Dashboard web
Open Source	Não	Sim

Próximos Passos

Se você quer um agente que funcione enquanto você não está olhando, o Kiro Crew é a opção mais completa no ecossistema Kiro. No próximo post, mostro como instalar ele no Coolify com integração Telegram — setup completo pra rodar numa VPS.

Para explorar mais sobre agentes autônomos e como escolher o certo pro seu caso, confira:

Como escolher seu agente de codificação — Critérios para escolher seu agente
Kiro IDE e CLI — Guia completo do Kiro IDE e CLI
IDE vs CLI: dois modelos de agente — IDE vs CLI: dois modelos de agente

Baseado na documentação oficial do Kiro Crew e kiro.dev/crew. Dados verificados em agosto de 2026.

Como Instalar o Kiro Crew no Coolify com Telegram

Tue, 04 Aug 2026 00:00:00 GMT

Como Instalar o Kiro Crew no Coolify com Telegram

Você quer um agente de IA que trabalhe enquanto você dorme, responda pelo Telegram, e rode na sua própria infra. O Kiro Crew faz isso — mas a documentação oficial foca em instalação manual num host Linux. Como fazer isso funcionar no Coolify, com deploy automatizado e persistência de dados?

Este guia cobre o setup completo: do container rodando no Coolify até você mandando mensagem pro bot no Telegram e recebendo respostas do agente.

Pré-requisitos

Antes de começar, você precisa de:

Coolify instalado numa VPS (Oracle Cloud, Hetzner, DigitalOcean, etc.)
Kiro CLI autenticado — rode kiro login localmente primeiro
Bot do Telegram criado — vamos configurar no tutorial
Acesso SSH ao servidor do Coolify

Sobre a Escolha de Infra

O Kiro Crew precisa de recursos razoáveis:

RAM: mínimo 2GB, recomendado 4GB+ (o modelo de embeddings sozinho usa ~610MB)
CPU: 2 vCPUs funcionam, mais ajuda em execução paralela
Disco: 5GB+ para o modelo de embeddings e dados persistentes

Uma instância Always Free da Oracle Cloud (A1 Flex com 24GB RAM) funciona perfeitamente. Se estiver apertado de recursos, considere rodar direto no host em vez de container — o overhead de Docker consome memória extra.

Passo 1: Criar o Bot do Telegram

Primeiro, crie seu bot no Telegram:

Abra o Telegram e busque por @BotFather
Mande /newbot
Escolha um nome (ex: "Meu Kiro Crew")
Escolha um username (ex: meu_kirocrew_bot)
Guarde o token que o BotFather vai te dar — formato: 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Pegar seu User ID

O Kiro Crew precisa saber quem pode usar o bot. Para descobrir seu ID:

Busque por @userinfobot no Telegram
Mande qualquer mensagem
Ele responde com seu ID numérico (ex: 123456789)

Guarde esse número — você vai usar como KIROCREW_OWNER_ID.

Passo 2: Preparar o Deploy no Coolify

No Coolify, você tem duas opções:

Opção A: Usar a Imagem Docker Oficial

A forma mais simples. No Coolify:

Vá em Projects → selecione seu projeto
Clique em + New → Docker Image
Configure:
- Image: ghcr.io/kirodotdev/kirocrew:latest
- Name: kirocrew

Opção B: Build de Imagem Customizada

Se você precisa de ferramentas extras (AWS CLI, gh, etc.), crie um Dockerfile customizado:

FROM ghcr.io/kirodotdev/kirocrew:latest

# Instalar ferramentas adicionais
RUN apt-get update && apt-get install -y \
    awscli \
    gh \
    jq \
    && rm -rf /var/lib/apt/lists/*

# Ou usar uma imagem base mais completa
# FROM ubuntu:24.04
# ... instalação completa do Kiro Crew + suas ferramentas

Pra essa opção, use Git Repository no Coolify apontando pro seu repo com o Dockerfile.

Passo 3: Configurar Variáveis de Ambiente

No Coolify, vá em Environment Variables e adicione:

# Telegram Bot
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

# ID do owner (seu user ID do Telegram)
KIROCREW_OWNER_ID=123456789

# Porta do dashboard (opcional, default 5476)
KIROCREW_PORT=5476

# Bind address (necessário em container)
KIROCREW_BIND=0.0.0.0

Variáveis Opcionais

# Se você quer expor o dashboard via HTTPS (não recomendado sem auth adicional)
# KIROCREW_DASHBOARD_URL=https://kirocrew.seudominio.com

# Para múltiplos owners
# KIROCREW_OWNER_ID=123456789,987654321

Passo 4: Configurar Volumes para Persistência

Dados do Kiro Crew ficam em ~/.kiro/crew/. No container, você precisa montar volumes para não perder dados no redeploy.

No Coolify, vá em Storages e adicione:

Source (host)	Destination (container)	Descrição
`/data/kirocrew/crew`	`/root/.kiro/crew`	Config, memória, lessons, skills
`/data/kirocrew/kiro`	`/root/.kiro`	Credenciais do Kiro CLI

Crie os diretórios no host antes do primeiro deploy:

ssh seu-servidor
sudo mkdir -p /data/kirocrew/{crew,kiro}
sudo chown -R 1000:1000 /data/kirocrew

Passo 5: Autenticar o Kiro CLI no Container

O Kiro Crew precisa do Kiro CLI autenticado. A forma mais simples é copiar suas credenciais locais para o volume:

# No seu computador local
scp -r ~/.kiro/* seu-servidor:/data/kirocrew/kiro/

Ou faça login diretamente no container após o primeiro deploy:

# No servidor
docker exec -it <container_id> kiro login

Passo 6: Configurar Rede

Opção Segura: Apenas Telegram (Recomendado)

Se você só vai acessar via Telegram, não precisa expor porta nenhuma. O bot usa long polling — ele que conecta no servidor do Telegram, não o contrário.

No Coolify:

Deixe Ports vazio ou não mapeie a porta 5476 externamente

Opção com Dashboard: SSH Tunnel

Se você quer acessar o dashboard web, use SSH tunnel em vez de expor publicamente:

# Do seu computador
ssh -L 5476:localhost:5476 seu-servidor
# Acesse http://localhost:5476

Opção Avançada: HTTPS com Cloudflare Tunnel

Se você realmente precisa de acesso remoto ao dashboard:

Configure um Cloudflare Tunnel apontando para localhost:5476
Adicione autenticação via Cloudflare Access
Configure KIROCREW_DASHBOARD_URL=https://kirocrew.seudominio.com

⚠️ Atenção: O dashboard tem autenticação por token, mas expor na internet adiciona superfície de ataque. Prefira SSH tunnel ou Telegram.

Passo 7: Deploy e Verificação

No Coolify:

Clique em Deploy
Acompanhe os logs de build

Após o deploy, verifique se está funcionando:

# Ver logs do container
docker logs -f <container_id>

# Deve mostrar algo como:
# Starting Kiro Crew gateway...
# Telegram bot connected
# Dashboard running on http://localhost:5476

Testar o Bot

No Telegram, mande uma mensagem pro seu bot:

/start

Ele deve responder com instruções de uso. Teste uma tarefa simples:

Qual a versão do Python instalada?

Passo 8: Configuração Inicial

Na primeira execução, o Kiro Crew vai:

Baixar o modelo de embeddings (~610MB) — isso demora alguns minutos
Criar os bancos de dados de memória
Inicializar a configuração padrão

Você pode rodar o setup interativo:

docker exec -it <container_id> kirocrew setup

Ou editar diretamente o config.json:

docker exec -it <container_id> cat /root/.kiro/crew/config.json

Sincronizar Estado de Outra Máquina

Se você já usava o Kiro Crew localmente e quer migrar pro servidor:

# Script oficial de sync (rode do seu computador local)
cd KiroCrew
scripts/sync-to-remote.sh usuario@seu-servidor

Isso copia:

Memória e lessons
Skills customizadas
Configurações
Histórico de sessões

Comandos Úteis do Telegram

Depois de configurado, você pode usar:

Comando	Descrição
`/kirocrew status`	Status do gateway
`/kirocrew dashboard`	Gera link temporário pro dashboard
`/kirocrew dashboard 6h`	Link válido por 6 horas
`/kirocrew jobs`	Lista cron jobs
`/kirocrew lessons`	Lista lessons aprendidas

Mensagens normais são tratadas como prompts pro agente.

Troubleshooting

Bot não responde

Verifique se o token está correto
Confira os logs: docker logs <container_id>
Verifique se KIROCREW_OWNER_ID está certo

"Embeddings not ready"

O modelo está baixando. Aguarde alguns minutos e verifique os logs:

docker logs -f <container_id> | grep -i embed

Kiro CLI não autenticado

docker exec -it <container_id> kiro login

Memória não persiste após redeploy

Verifique se os volumes estão montados corretamente:

docker inspect <container_id> | grep -A 10 Mounts

Container reiniciando em loop

Provavelmente é falta de memória. Verifique:

docker stats <container_id>

Se RAM estiver no limite, considere:

Aumentar recursos da VPS
Rodar direto no host sem Docker
Usar uma instância com mais RAM

Considerações de Segurança

O que o Kiro Crew Tem Acesso

Código: se você apontar pra um diretório, ele tem acesso total
Comandos: pode executar shell commands (com sandbox)
Rede: pode fazer requests HTTP
Secrets: redação automática, mas cuidado com o que você cola no chat

Recomendações

Não exponha o dashboard publicamente — use SSH tunnel ou Telegram
Restrinja owners — só adicione IDs de pessoas que devem ter acesso
Monitore audit log — todo comando executado é logado
Use secrets via env vars — não cole API keys no chat
Backup regular — rsync do diretório /data/kirocrew/

Setup Alternativo: Direto no Host

Se o overhead de Docker é problema ou você quer mais controle, instale direto no host:

# No servidor
git clone https://github.com/kirodotdev/KiroCrew.git
cd KiroCrew

# Build frontend
cd website && npm install && npm run build && cd ..
cp -R website/dist src/kiro_crew/static/dist

# Install backend
pip install .

# Setup
kirocrew setup
kirocrew doctor

# Rodar como serviço
kirocrew service install

Essa abordagem usa menos recursos e facilita instalar ferramentas CLI (aws, gh, etc.) diretamente no sistema.

Próximos Passos

Com o Kiro Crew rodando, você pode:

Configurar cron jobs para digests matinais
Criar skills específicas pro seu workflow
Adicionar MCP servers para ferramentas extras
Instalar Apps como Issue Radar e Task Runner

Para entender melhor o que o Kiro Crew pode fazer, leia o post conceitual:

O que é o Kiro Crew — O que é o Kiro Crew e quando usar

E para comparar com outras opções de agentes:

Kiro IDE e CLI — Guia do Kiro IDE e CLI
Claude Code — Claude Code como alternativa

Baseado na documentação oficial e experiência prática de deploy. Testado em agosto de 2026 com Coolify v4.x e Kiro Crew latest.

Kiro Hooks: A Feature Gratuita Que Muda Tudo

Sun, 26 Jul 2026 00:00:00 GMT

Kiro Hooks: A Feature Gratuita Que Muda Tudo

Todo mundo fala de specs quando fala de Kiro. Faz sentido — é o grande diferencial. Mas tem uma feature que quase ninguém menciona e que pode mudar completamente como você trabalha: Hooks.

O detalhe absurdo: hooks são gratuitos. Não contam contra seus créditos do mês.

O Que São Hooks

Hooks são automações event-driven que disparam ações do agente quando eventos específicos ocorrem no seu projeto:

Você salva um arquivo → o agente executa uma ação
Você cria um arquivo novo → o agente executa outra ação
Você deleta um arquivo → o agente reage
Você dispara manualmente → o agente executa sob demanda

O agente tem acesso ao contexto do seu projeto (código, steering files, specs) e pode fazer qualquer coisa que faria numa conversa normal: editar arquivos, rodar comandos, analisar código.

A diferença: nenhum crédito é consumido.

Por Que Hooks São Gratuitos

Hooks executam tarefas previsíveis e repetitivas — lint, formatação, atualização de docs. O custo computacional é menor que conversas abertas, e a AWS optou por incluí-los como parte da proposta de valor do Kiro.

Pra times, isso muda a conta de ROI completamente. Você pode ter dezenas de automações rodando em cada save sem estourar o orçamento.

Eventos Disponíveis

Evento	Quando Dispara
On Save	Quando você salva um arquivo que corresponde ao padrão
On Create	Quando um novo arquivo é criado
On Delete	Quando um arquivo é removido
Manual Trigger	Quando você dispara via comando ou UI

No CLI, existem eventos adicionais:

PreToolUse — antes do agente usar uma ferramenta
PostToolUse — depois do agente usar uma ferramenta
AgentSpawn — quando um subagent é criado
AgentStop — quando um subagent termina

Como Configurar um Hook

No Kiro IDE

Pressione Cmd+Shift+K (ou Ctrl+Shift+K no Windows/Linux)
Selecione "New Hook"
Configure:
- Nome: identificador único
- Trigger: evento que dispara (On Save, On Create, etc.)
- File Pattern: glob que define quais arquivos ativam o hook
- Ação: descrição em linguagem natural do que fazer

Via Arquivo

Hooks ficam em .kiro/hooks/ como arquivos YAML ou Markdown:

# .kiro/hooks/auto-lint.yaml
name: auto-lint-typescript
trigger: on_save
pattern: "src/**/*.ts"
action: |
  Execute ESLint no arquivo salvo.
  Se houver erros que podem ser corrigidos automaticamente (--fix), corrija-os.
  Se houver erros que precisam de intervenção manual, liste-os como comentários TODO no início do arquivo.

10 Exemplos Práticos

1. Lint Automático em TypeScript

name: auto-lint-ts
trigger: on_save
pattern: "src/**/*.ts"
action: |
  Execute eslint --fix no arquivo.
  Se ainda houver erros após o fix, mostre-os no Problems panel.

Quando usar: Qualquer projeto TypeScript. Economiza o ciclo de "salvar → ver erro de lint → corrigir → salvar de novo".

2. Type Check em Python

name: type-check-python
trigger: on_save
pattern: "**/*.py"
action: |
  Execute mypy no arquivo modificado.
  Se houver erros de tipo, adicione comentários # type: ignore com explicação apenas onde absolutamente necessário.
  Prefira corrigir o código a ignorar o erro.

Quando usar: Projetos Python com type hints. Pega erros de tipo no momento do save.

3. Atualizar Testes ao Modificar Código

name: update-tests
trigger: on_save
pattern: "src/modules/**/*.ts"
action: |
  Identifique o arquivo de teste correspondente em tests/.
  Se o arquivo de teste existe, analise as mudanças no código-fonte e atualize os testes para cobrir:
  - Novas funções ou métodos
  - Mudanças em assinaturas de função
  - Novos branches condicionais
  Se não existe arquivo de teste, crie um com cobertura básica.

Quando usar: Manter testes em sincronia com código sem esforço manual.

4. Atualizar Documentação de API

name: update-api-docs
trigger: on_save
pattern: "src/routes/**/*.ts"
action: |
  Analise os endpoints modificados.
  Atualize docs/api.md com:
  - Método HTTP e path
  - Parâmetros de entrada (query, body, path)
  - Formato de resposta
  - Exemplos de uso com curl
  Mantenha o estilo consistente com a documentação existente.

Quando usar: APIs REST. Docs sempre atualizadas com zero esforço.

5. Gerar Schema.yml para dbt

name: dbt-schema-gen
trigger: on_create
pattern: "models/**/*.sql"
action: |
  Analise o modelo SQL criado.
  Gere ou atualize o schema.yml correspondente com:
  - Nome do modelo
  - Descrição baseada no SQL
  - Colunas com tipos inferidos
  - Testes básicos (not_null, unique para PKs)

Quando usar: Projetos dbt. Economiza o trabalho tedioso de manter schema.yml.

6. Scan de Segurança Antes de Commit

name: security-scan
trigger: manual
action: |
  Analise todos os arquivos staged para commit.
  Procure por:
  - Credenciais hardcoded (API keys, passwords, tokens)
  - Conexões de banco sem SSL
  - Queries SQL vulneráveis a injection
  - Inputs de usuário não sanitizados
  Se encontrar problemas, liste-os com severidade e sugestão de correção.
  Não faça commit se houver problemas de severidade alta.

Quando usar: Antes de cada commit. Previne vazamento de credenciais.

7. Validar Conventional Commits

name: validate-commit-message
trigger: manual
action: |
  Analise a mensagem de commit proposta.
  Verifique se segue Conventional Commits:
  - Prefixo válido (feat, fix, docs, style, refactor, test, chore)
  - Escopo opcional entre parênteses
  - Descrição imperativa e concisa
  Se inválida, sugira uma mensagem corrigida.

Quando usar: Times que seguem Conventional Commits.

8. Atualizar Storybook ao Modificar Componente

name: update-storybook
trigger: on_save
pattern: "src/components/**/*.tsx"
action: |
  Se o componente modificado tem um arquivo .stories.tsx correspondente:
  - Verifique se todas as props estão representadas em stories
  - Adicione stories para novas variantes
  Se não tem .stories.tsx, crie um com stories básicas cobrindo:
  - Estado default
  - Estados de loading/error se aplicável
  - Variações de props principais

Quando usar: Projetos React/Vue com Storybook.

9. Estimativa de Custo CloudFormation

name: cfn-cost-estimate
trigger: on_save
pattern: "**/*.yaml"
condition: |
  Apenas se o arquivo contém AWSTemplateFormatVersion
action: |
  Analise os recursos definidos no template CloudFormation.
  Adicione um comentário no início do arquivo com estimativa mensal de custo:
  - Liste cada recurso e custo estimado
  - Some o total mensal
  - Avise sobre recursos sem tier gratuito
  Use preços da região us-east-1 como referência.

Quando usar: Projetos de infraestrutura AWS. Evita surpresas na fatura.

10. Notificação Slack em Deploy

name: deploy-notification
trigger: manual
action: |
  Colete informações do último deploy:
  - Branch/tag
  - Commits incluídos desde último deploy
  - Autor
  - Timestamp
  Formate como mensagem Slack e envie para o webhook configurado em .env (SLACK_WEBHOOK_URL).

Quando usar: Manter o time informado sobre deploys.

Hooks para Times

Hooks são arquivos em .kiro/hooks/ — versionados no Git. Quando você configura um hook, ele fica disponível para todo o time.

Isso cria consistência no automático:

Mesmo padrão de lint pra todo mundo
Mesmas verificações de segurança
Mesma estrutura de documentação

Ninguém precisa lembrar de rodar lint ou atualizar docs. O hook faz por você.

Anti-Patterns: O Que Evitar

❌ Hooks que Demoram Muito

Hooks devem ser rápidos. Se seu hook demora 30 segundos para executar, você vai desabilitar depois de 3 saves.

Solução: Quebre em hooks menores ou use trigger manual para tarefas pesadas.

❌ Hooks que Modificam Muitos Arquivos

Um hook que modifica 50 arquivos em cada save é receita para conflitos de merge e confusão.

Solução: Mantenha hooks focados. Um hook, uma responsabilidade.

❌ Hooks Sem Padrão de Arquivo Específico

# Ruim
pattern: "**/*"

# Bom
pattern: "src/modules/**/*.ts"

Hooks muito amplos disparam em contextos errados e criam ruído.

❌ Hooks que Contradizem Steering Files

Se seu steering file diz "use async/await" e seu hook converte para callbacks, você tem um problema.

Solução: Alinhe hooks com steering files. Os dois são parte do mesmo contexto.

Hooks no CLI vs IDE

Aspecto	IDE	CLI
Configuração	UI visual	Arquivos YAML
Eventos	File-based (save, create, delete)	File-based + tool-based (PreToolUse, PostToolUse)
Feedback	Visual no editor	Log no terminal
Uso	Desenvolvimento local	Automação, CI/CD

Os arquivos de hook são compatíveis entre os dois. Você pode criar no IDE e executar no CLI.

Perguntas Frequentes

Hooks realmente não consomem créditos?

Correto. Hooks são gratuitos em todos os planos, incluindo o Free.

Posso desabilitar um hook temporariamente?

Sim. No IDE, vá em Settings → Hooks e desabilite. No CLI, renomeie o arquivo para .disabled.yaml ou mova para fora da pasta.

Hooks funcionam com arquivos binários?

Não diretamente. O padrão de arquivo pode incluir binários, mas a ação do hook precisa fazer sentido para o contexto. Hooks são mais úteis para arquivos de texto.

Posso ter múltiplos hooks para o mesmo evento?

Sim. Todos os hooks que correspondem ao evento e padrão são executados.

Hooks podem falhar e bloquear o save?

Por padrão, não. Hooks executam em background. Se você quer comportamento de "gate" (bloquear se falhar), use hooks manuais antes de commit/deploy.

Próximos Passos

Agora que você entende hooks, explore outros recursos do Kiro:

Se você precisa de ajuda para configurar hooks customizados ou criar workflows de automação para seu time, conheça os serviços de consultoria em ft.ia.br.

Guia verificado em julho de 2026. Versões: Kiro IDE 0.7+, Kiro CLI 1.24+.

Como Usar o Kiro: Tutorial Completo do Zero à Produção

Sat, 25 Jul 2026 00:00:00 GMT

Como Usar o Kiro: Tutorial Completo do Zero à Produção

Este é o guia prático pra quem quer começar a usar o Kiro da AWS. Nada de teoria sobre spec-driven development — a gente vai instalar, configurar e criar seu primeiro projeto com specs funcionando de verdade.

Tempo estimado: 30 minutos do zero ao primeiro código gerado a partir de specs.

O Que Você Vai Aprender

Instalar Kiro IDE e CLI
Configurar autenticação
Criar seu primeiro projeto com specs
Configurar steering files para sua stack
Usar hooks para automação gratuita
Otimizar uso de créditos

Parte 1: Instalação

Kiro IDE (macOS, Windows, Linux)

macOS:

Acesse kiro.dev/downloads
Baixe o .dmg
Arraste para Applications
Na primeira execução, clique com botão direito → Abrir (contornar Gatekeeper)
Faça login com AWS Builder ID, Google ou GitHub

Windows:

Baixe o .exe de kiro.dev
Execute o instalador (permissões de admin)
Kiro adiciona-se ao PATH automaticamente
Faça login

Linux:

sudo dpkg -i kiro_*.deb
sudo apt-get install -f
kiro

O Kiro é baseado em Code OSS (VS Code open source). Suas extensões Open VSX e configurações do VS Code são compatíveis. Na primeira execução, você pode importar settings existentes.

Kiro CLI

O CLI funciona em qualquer sistema:

curl -fsSL https://cli.kiro.dev/install | bash

Depois, autentique:

kiro login

Isso abre o navegador para login. Uma vez autenticado, o CLI compartilha a mesma assinatura e créditos do IDE.

Verificar instalação:

kiro --version

Parte 2: Seu Primeiro Projeto com Specs

Vamos criar uma API simples de tarefas (to-do list) usando o workflow completo de specs.

Passo 1: Abra o Projeto no Kiro IDE

mkdir meu-projeto-kiro
cd meu-projeto-kiro
npm init -y

Abra no Kiro IDE: kiro . ou via menu File → Open Folder.

Passo 2: Inicie uma Nova Spec

No Kiro IDE, pressione Cmd+Shift+S (ou Ctrl+Shift+S no Windows/Linux) para abrir o painel de Specs.

Digite seu prompt em linguagem natural:

Crie uma API REST de tarefas (to-do) com:
- CRUD completo (criar, listar, atualizar, deletar)
- Validação de campos obrigatórios
- Filtro por status (pendente, concluído)
- Ordenação por data de criação

Passo 3: Revise os Requisitos

O Kiro gera requirements.md com user stories em formato EARS:

## User Stories

### US-001: Criar Tarefa
QUANDO o usuário enviar POST /tasks com título válido
O SISTEMA DEVE criar a tarefa com status "pendente"
E retornar a tarefa criada com id único

### US-002: Listar Tarefas
QUANDO o usuário enviar GET /tasks
O SISTEMA DEVE retornar todas as tarefas
E suportar filtro por query param ?status=pendente|concluido

[...]

Revise, adicione edge cases que faltaram, e dê o OK. Este é o momento mais importante — você está definindo o contrato do que vai ser construído.

Passo 4: Revise o Design

Com requisitos aprovados, o Kiro analisa seu codebase e gera design.md:

## Arquitetura

### Endpoints
- POST /tasks - Criar tarefa
- GET /tasks - Listar tarefas (com filtros)
- GET /tasks/:id - Buscar tarefa
- PUT /tasks/:id - Atualizar tarefa
- DELETE /tasks/:id - Deletar tarefa

### Schema
```typescript
interface Task {
  id: string;
  title: string;
  description?: string;
  status: 'pending' | 'completed';
  createdAt: Date;
  updatedAt: Date;
}

Validação

title: required, min 1 char, max 200 chars
description: optional, max 1000 chars
status: enum validation

[...]


Revise a arquitetura. Se algo não faz sentido para seu contexto, edite antes de aprovar.

### Passo 5: Execute as Tarefas

O Kiro gera `tasks.md` com implementação sequenciada:

```markdown
## Tarefas

- [ ] T1: Criar schema do banco (migration)
- [ ] T2: Implementar modelo Task
- [ ] T3: Criar endpoint POST /tasks
- [ ] T4: Criar endpoint GET /tasks com filtros
- [ ] T5: Criar endpoint GET /tasks/:id
- [ ] T6: Criar endpoint PUT /tasks/:id
- [ ] T7: Criar endpoint DELETE /tasks/:id
- [ ] T8: Adicionar testes unitários
- [ ] T9: Adicionar validação de input

Clique em "Execute" em cada tarefa. O Kiro implementa, e você revisa o diff antes de aceitar.

Dica: Se uma implementação tomou rumo errado, use checkpointing para voltar ao estado anterior sem perder trabalho.

Parte 3: Steering Files

Steering files são instruções que ficam salvas sobre seu projeto. Em vez de explicar suas convenções toda hora que abre um chat, você documenta uma vez e o Kiro lê sempre.

Criar Steering Files

Crie a pasta .kiro/steering/ na raiz do projeto:

mkdir -p .kiro/steering

Exemplo: Convenções Node.js/TypeScript

Crie .kiro/steering/conventions.md:

# Convenções do Projeto

## Stack
- Runtime: Node.js 22+
- Linguagem: TypeScript strict mode
- Framework: Express.js
- ORM: Prisma
- Testes: Vitest

## Padrões de Código
- Sempre usar async/await (nunca callbacks ou .then)
- Validação de input com Zod em todos os endpoints
- Tratamento de erros com try/catch e middleware de error handling
- Logs estruturados com pino

## Estrutura de Pastas
- src/modules/{feature}/ — cada feature isolada
- src/shared/ — utilitários compartilhados
- src/infra/ — configurações de banco, cache, etc.

## Git
- Commits seguem Conventional Commits
- Branch naming: feature/xxx, fix/xxx, chore/xxx

## Não Fazer
- Nunca usar any em TypeScript
- Nunca commitar credenciais
- Nunca usar console.log em produção

O Kiro lê esses arquivos automaticamente e segue suas convenções em toda interação.

Steering Global vs Local

.kiro/steering/ no projeto → aplicado a esse projeto
~/.kiro/steering/ no home → aplicado a todos os projetos

Parte 4: Hooks (Automação Gratuita)

Hooks são automações que disparam ações do agente quando eventos ocorrem. E não contam contra seus créditos — são completamente gratuitos.

Eventos Disponíveis

On save — quando você salva um arquivo
On create — quando um novo arquivo é criado
On delete — quando um arquivo é removido
Manual trigger — quando você dispara manualmente

Exemplo: Atualizar Testes ao Salvar

No Kiro IDE, pressione Cmd+Shift+K → "New Hook":

Nome: update-tests-on-save
Trigger: On Save
File Pattern: src/**/*.ts
Ação: Se o arquivo modificado é um módulo, atualize o arquivo de teste correspondente em tests/ para cobrir as mudanças

Exemplo: Lint Automático em Python

Nome: auto-lint-python
Trigger: On Save
File Pattern: **/*.py
Ação: Execute ruff check e ruff format no arquivo. Se houver erros de lint que podem ser corrigidos automaticamente, corrija-os.

Exemplo: Docs ao Modificar API

Nome: update-api-docs
Trigger: On Save
File Pattern: src/routes/**/*.ts
Ação: Atualize o arquivo docs/api.md com a documentação atualizada dos endpoints modificados

Hooks São Commitáveis

Hooks ficam em .kiro/hooks/ e são versionados no Git. Toda a equipe se beneficia das mesmas automações.

Parte 5: Kiro CLI para o Dia a Dia

O CLI complementa o IDE para tarefas rápidas e automação.

Sessão Interativa

cd meu-projeto
kiro chat

Você entra num loop de conversa:

> Explique a arquitetura do módulo de autenticação

O módulo de autenticação está em src/modules/auth/ e consiste em:
[...]

> Adicione suporte a refresh token

Execução Headless (CI/CD)

kiro --print "Analise os erros de lint e corrija automaticamente"

O agente executa sem interação — perfeito para pipelines.

Custom Agents

Crie agentes especializados em .kiro/agents/:

# .kiro/agents/security-reviewer.yaml
name: security-reviewer
description: Revisa código para problemas de segurança
allowedTools:
  - read_file
  - search_files
  - analyze_code
systemPrompt: |
  Você é um especialista em segurança de aplicações.
  Analise código buscando:
  - SQL injection
  - XSS
  - Credenciais hardcoded
  - Validação de input insuficiente

Use com:

kiro chat --agent security-reviewer

Parte 6: Otimização de Créditos

Use o Modo Auto

O modo Auto (padrão) roteia automaticamente para o modelo mais eficiente para cada tarefa. Se você forçar Claude Opus em vez de Auto, o custo sobe significativamente.

Hooks São Gratuitos

Mova automações recorrentes para hooks em vez de fazer manualmente. Lint, formatação, atualização de docs — tudo isso pode ser hook.

Specs Economizam Retrabalho

O investimento de créditos em specs se paga quando você evita 3-4 ciclos de "não era isso que eu queria".

Free Tier: 50 Créditos

O tier gratuito é apertado para uso intensivo de specs. Para trabalho real, considere o Pro ($20/mês com 1.000 créditos).

Dica: Uma interação simples pode consumir menos de 1 crédito (mínimo 0,01). Specs completas consomem mais.

Próximos Passos

Antes de avançar, vale registrar uma capacidade nova do ecossistema: o Kiro consta entre os clientes compatíveis com Agent Plugins 1.0.0, com suporte a Agent Skills e MCP por stdio, Streamable HTTP e SSE legado. A AWS também anunciou compatibilidade do AWS Agent Toolkit com o padrão.

Isso permite distribuir o núcleo de Skills e MCP em um pacote comum, mas hooks e custom agents do Kiro continuam sendo recursos específicos. O guia Agent Plugins 1.0: padrão aberto para Skills e MCP explica essa fronteira.

Agora você tem:

Kiro IDE e CLI instalados
Seu primeiro projeto com specs
Steering files configurados
Hooks automatizando tarefas

Para aprofundar:

Se você precisa de ajuda para configurar Kiro no seu time ou criar workflows customizados, conheça os serviços de consultoria em ft.ia.br.

Tutorial verificado em julho de 2026. Versões: Kiro IDE 0.7+, Kiro CLI 1.24+.

GitHub Copilot ou Kiro? O Comparativo Definitivo 2026

Fri, 24 Jul 2026 00:00:00 GMT

GitHub Copilot ou Kiro? O Comparativo Definitivo 2026

Duas filosofias opostas de desenvolvimento com IA. De um lado, o Copilot — o mais popular do mundo, focado em entregar rápido. Do outro, o Kiro — a IDE da AWS que faz diferente: primeiro pensa, depois escreve código.

Se você está em dúvida entre os dois, este comparativo vai direto ao ponto.

TL;DR — A Resposta em 30 Segundos

GitHub Copilot ($10/mês): melhor custo-benefício para dia-a-dia. Completions ilimitadas, funciona em 9+ IDEs, execução imediata.
Kiro ($20/mês): melhor para features complexas e times AWS. Specs antes de código, rastreabilidade, hooks gratuitos.

A escolha não é sobre qual é "o melhor" — é sobre qual encaixa no seu jeito de trabalhar:

Bug fixes, refactoring, testes → Copilot
Features greenfield que cruzam serviços → Kiro
Time heterogêneo (JetBrains, Neovim, VS Code) → Copilot
Stack AWS-first → Kiro

Dá para usar os dois? Sim. $30/mês combinados e você tem o melhor dos mundos.

A Grande Diferença: Vibe Coding vs Spec-Driven

GitHub Copilot representa o que muitos chamam de vibe coding. Você descreve o que quer, e o agente executa imediatamente. Quer um endpoint? Digita o prompt e código aparece. Rápido, direto, sem fricção.

Kiro inverte essa lógica com spec-driven development. Antes de escrever código, o Kiro gera requisitos estruturados (requirements.md), design técnico (design.md) e tarefas sequenciadas (tasks.md). Só depois implementa. É planejamento forçado.

A consequência prática:

Copilot é mais rápido para tarefas pontuais
Kiro produz menos retrabalho em features complexas

Uma avaliação publicada no site do Martin Fowler resume bem: usar Kiro para um bug fix simples "é como usar um martelo para quebrar uma noz". Mas para features que cruzam múltiplos serviços, o investimento de 20-40 minutos em specs pode economizar horas de ida-e-volta.

Tabela Comparativa

Critério	GitHub Copilot	Kiro
Preço entrada	$10/mês (Pro)	$20/mês (Pro)
Completions	Ilimitadas (Pro)	Via créditos
Premium requests	300/mês (Pro)	1.000 créditos/mês (Pro)
IDEs suportadas	9+ (VS Code, JetBrains, Neovim, Xcode, Eclipse)	IDE própria + CLI + ACP
Specs	Não nativo	Nativo (EARS notation)
Autonomia	Coding Agent cria PRs	Specs + implementação autônoma
Multi-agente	Agent HQ (Pro+/Enterprise)	Workflow sequencial
MCP	Sim (VS Code, JetBrains)	Sim
Hooks	Não	Sim (gratuitos)
Integração cloud	GitHub nativo	AWS nativo
GovCloud	Não documentado	Documentado

Análise por Perfil

Desenvolvedor Individual

Escolha Copilot se:

Você quer o menor preço com máximo valor ($10/mês)
Trabalha em projetos existentes mais do que greenfield
Prefere velocidade sobre planejamento
Usa IDEs variadas (JetBrains, Neovim, Xcode)

Escolha Kiro se:

Você trabalha primariamente com AWS
Constrói features complexas que cruzam serviços
Valoriza rastreabilidade de decisões
Prefere planejamento antes de execução

Time de Produto

Escolha Copilot se:

O time usa IDEs diferentes (JetBrains, VS Code, etc.)
Velocidade de entrega é a prioridade
Workflow já está integrado com GitHub (Issues, PRs, Actions)

Escolha Kiro se:

O time precisa de audit trail de decisões técnicas
Stack é AWS-native
Features frequentemente cruzam múltiplos serviços
Precisa de governança sobre o que o agente faz

Enterprise / Regulado

Escolha Copilot se:

Precisa de integração com GitHub Enterprise
Time grande com IDEs heterogêneas

Escolha Kiro se:

Precisa de GovCloud
Requisitos de rastreabilidade (compliance)
Integração profunda com IAM Identity Center

O Que a Comunidade Diz

Uma análise de discussões no Reddit (r/vibecoding, r/ChatGPT) mostra um padrão:

"Use Copilot quando você quer sugestões. Use Claude Code ou Kiro quando você quer que ele realmente faça algo."

O Copilot lidera em popularidade bruta. Mas para trabalhos que exigem contexto de projeto e execução autônoma, ferramentas spec-driven como Kiro aparecem como alternativa.

Dado interessante: a equipe .NET da Microsoft reportou taxa de sucesso de ~67-72% com o Copilot Coding Agent no repositório dotnet/runtime após ajustes de ambiente. Agentes ainda precisam de supervisão.

Preço vs Valor

GitHub Copilot

Plano	Preço	Completions	Premium Requests
Free	$0	2.000/mês	50/mês
Pro	$10/mês	Ilimitadas	300/mês
Pro+	$39/mês	Ilimitadas	1.500/mês
Business	$19/seat/mês	Ilimitadas	300/user/mês

Kiro

Plano	Preço	Créditos	Overage
Free	$0	50/mês	N/A
Pro	$20/mês	1.000/mês	$0,04/crédito
Pro+	$40/mês	2.000/mês	$0,04/crédito
Power	$200/mês	10.000/mês	$0,04/crédito

A matemática:

Copilot Pro a $10/mês é o melhor custo-benefício do mercado para uso diário
Kiro Free com 50 créditos é apertado para uso intensivo de specs
Para uso sério de Kiro, o Pro a $20/mês é o mínimo recomendado

Bônus Kiro: Hooks são gratuitos — não contam contra créditos. Se você usa automações pesadas, isso muda a conta.

E Se Usar os Dois?

Não é excludente. $30/mês combinados (Copilot Pro + Kiro Pro) pode fazer sentido se:

Você usa Copilot para o dia-a-dia (completions, chat, bug fixes)
Você usa Kiro para features estruturais que precisam de planejamento
Seu time tem preferências diferentes

O Copilot continua rodando na sua IDE preferida. O Kiro entra quando você precisa pensar antes de codar.

Veredicto

Para a maioria dos desenvolvedores, GitHub Copilot Pro a $10/mês é a escolha padrão. É mais barato, funciona em qualquer editor, e resolve a maioria das tarefas sem fricção. A integração com GitHub é um multiplicador de produtividade que nenhuma outra ferramenta replica.

Kiro justifica seu preço maior em cenários específicos:

Features greenfield complexas
Equipes que precisam de audit trail
Organizações AWS-first
Projetos regulados que exigem rastreabilidade

A pergunta certa não é "qual é o melhor?" — é "qual faz sentido pro seu contexto?"

Perguntas Frequentes

Copilot funciona para spec-driven development?

Não nativamente. Você pode criar templates de spec e pedir ao Copilot para segui-los via custom instructions, mas não há pipeline estruturado como o Kiro.

O tier gratuito do Kiro é viável?

Dificilmente para uso intensivo. 50 créditos/mês cobrem exploração, não trabalho diário. Para uso real, Pro ($20/mês) é o mínimo.

Qual é melhor para monorepos grandes?

Copilot tem vantagem. O Coding Agent lê o repositório inteiro, e a integração com GitHub permite trabalhar em múltiplas issues simultaneamente.

Posso usar Kiro com JetBrains?

Sim, via ACP e CLI. Mas o workflow completo de specs é otimizado para a IDE nativa do Kiro.

Os dois usam os mesmos modelos de IA?

Não exatamente. Copilot oferece GPT-5.x, Claude Opus/Sonnet, e Gemini. Kiro usa Claude Sonnet/Opus via Amazon Bedrock com modo Auto que combina modelos especializados.

Se você quer implementar agentes de codificação no seu time com a estratégia certa para cada cenário, a ft.ia.br ajuda a montar esse setup. Consultoria focada em produtividade com IA para equipes de desenvolvimento.

Dados verificados em julho de 2026. Preços: github.com/features/copilot/plans e kiro.dev/pricing.

Kiro CLI ou IDE? As Diferenças Que Ninguém Te Conta

Wed, 22 Jul 2026 00:00:00 GMT

Kiro CLI ou IDE? As Diferenças Que Ninguém Te Conta

Você já decidiu pelo Kiro. Ótimo. Agora vem a pergunta que todo mundo faz: CLI, IDE, ou os dois?

A resposta curta: depende mais de como você trabalha do que do que você constrói.

TL;DR — A Resposta em 30 Segundos

Kiro IDE: specs visuais, Powers com um clique, checkpointing, Property-Based Testing. Para features complexas onde você quer rastreabilidade.
Kiro CLI: terminal-first, modo headless, subagents, scriptável. Para automação, CI/CD e quem vive no terminal.
Mesma assinatura: os dois compartilham créditos e steering files. Você pode usar ambos sem pagar duas vezes.

Se você quer a decisão rápida:

Features greenfield complexas → IDE
Automação e DevOps → CLI
Time heterogêneo → os dois

Agora vamos aos detalhes.

A Diferença Fundamental

O Kiro IDE é visual e orientado a specs. Você abre a IDE, descreve uma feature em linguagem natural, e o Kiro gera um pipeline estruturado: requirements.md → design.md → tasks.md → código. Cada etapa tem revisão humana. É planejamento antes de implementação.

O Kiro CLI é terminal-first e orientado a execução. Você abre o terminal, digita kiro chat, e conversa com o agente sobre seu código. Para automação, usa kiro --print "prompt" e o agente executa sem interação. É velocidade e integração com pipelines.

A filosofia é diferente. O IDE te pergunta: "bora planejar antes?" O CLI pergunta: "o que você quer que eu faça agora?"

O Que Só o IDE Faz

Powers (Extensibilidade com Um Clique)

Powers são pacotes que combinam MCP servers + steering files + hooks em uma instalação instantânea. Com mais de 60 powers disponíveis (Figma, Supabase, Terraform, Datadog, Stripe, serviços AWS), o IDE vira um especialista no seu stack sem configuração manual.

O pulo do gato: powers carregam sob demanda. O Kiro avalia quais são relevantes para sua conversa e ativa só esses. Nada de context overload.

O CLI ainda não suporta Powers — está no roadmap, mas sem data.

Checkpointing

Cada mudança que o agente faz gera um checkpoint. Se a implementação tomou um rumo errado no passo 7 de 10, você volta ao passo 6 sem perder o trabalho anterior. No CLI, você recomeça.

Property-Based Testing (PBT)

O Kiro IDE extrai propriedades das suas specs EARS e gera centenas de test cases aleatórios. É verificação automatizada de que o código realmente implementa o que a spec define.

Nenhum concorrente (Cursor, Copilot, Claude Code) oferece isso nativamente.

Multi-Root Workspaces

Projetos com múltiplos repositórios? O IDE navega entre todos os roots configurados. Ideal para monorepos e microserviços.

O Que Só o CLI Faz

Modo Headless

kiro --print "Analise os logs de CI, encontre a causa raiz e aplique o fix."

O agente executa sem intervenção humana. Perfeito para pipelines de CI/CD. Configure no GitHub Actions, CodeCatalyst, ou qualquer sistema de build.

Subagents Nativos

O CLI suporta múltiplos agentes especializados rodando em paralelo com progress tracking em tempo real. Você pode encadear invocações:

kiro --print "Analise a arquitetura" --agent backend-specialist
kiro --print "Gere testes de integração" --agent test-engineer
kiro --print "Atualize a documentação" --agent docs-writer

Hooks de Controle

No CLI, hooks são orientados a controle operacional: veto via exit code 2 em PreToolUse, logging em AgentSpawn, validação de output em PostToolUse. É governança programática.

Integração Nativa com Shell

Pipes, scripts, cron jobs, tmux — o CLI se encaixa onde você já está. Não precisa trocar de contexto para uma IDE gráfica.

Tabela Comparativa

Critério	Kiro IDE	Kiro CLI
Tipo	IDE standalone (Code OSS)	Terminal agent
Specs	Nativo (requirements → design → tasks)	Lê specs existentes
Powers	60+ com install one-click	Não disponível (planejado)
Hooks	Event-driven (file save/create/delete)	Pre/Post tool use, AgentSpawn
MCP	Suporte completo	Suporte completo
Modo headless	Não	Sim (`kiro --print`)
CI/CD	Não	Scriptável
Checkpointing	Rollback visual por step	Não
Property-Based Testing	Integrado com specs	Não
Multi-root workspace	Sim	Não
Custom Agents	Via `.kiro/agents/`	Via `.kiro/agents/`
Steering Files	`.kiro/steering/`	`.kiro/steering/`
Melhor para	Features complexas, rastreabilidade	Automação, scripts, DevOps

Quando Usar Cada Um: Flowchart de Decisão

Você está trabalhando em...
│
├─ Feature nova que cruza múltiplos serviços?
│  └─ SIM → Kiro IDE (specs vão evitar retrabalho)
│
├─ Bug fix ou refactor pontual?
│  └─ SIM → Kiro CLI (overhead de spec não vale)
│
├─ Pipeline de CI/CD automatizado?
│  └─ SIM → Kiro CLI (modo headless)
│
├─ Projeto AWS com Lambda, CDK, CloudFormation?
│  └─ SIM → Kiro IDE (Powers nativos da AWS)
│
├─ Trabalha primariamente no terminal (tmux, ssh)?
│  └─ SIM → Kiro CLI (onde você já está)
│
├─ Time precisa de audit trail de decisões?
│  └─ SIM → Kiro IDE (specs são documentação)
│
└─ Quer o melhor dos dois mundos?
   └─ Use os dois — mesma assinatura

Casos de Uso Reais

DevOps / SRE

Use o CLI. Automação headless em pipelines, análise de logs de erro, rollbacks automatizados, scripts de manutenção. O IDE só atrapalha quando você está em SSH num servidor remoto.

# Hook de CI que usa Kiro CLI para review
kiro --print "Review this PR for security issues and suggest fixes" \
  --agent security-reviewer

Backend Developer

Use o IDE para features, CLI para fixes. Feature nova com 3 endpoints e integração com banco? IDE com specs. Bug no endpoint de autenticação? CLI direto.

Full-Stack Developer

Use os dois. IDE para planejamento de features complexas. CLI para ajustes rápidos no frontend enquanto o backend está compilando.

Data Engineer

Use o IDE. Pipelines de dados que cruzam S3, Glue, Redshift, Lambda — o overhead de specs se paga em horas de debug evitadas. Powers AWS são matadores aqui.

Usando os Dois Juntos

A mesma assinatura funciona nos dois. Steering files são compartilhados. Custom agents rodam em ambos. Você não precisa escolher um para sempre.

O workflow que muitos times adotam:

IDE para planejamento e features — specs para pensar, design docs para comunicar, implementação task por task
CLI para execução e automação — code reviews em PRs, geração de testes em CI, análise de erros, tarefas rápidas

Preços (Compartilhados)

Plano	Preço	Créditos/mês
Free	$0	50
Pro	$20/mês	1.000
Pro+	$40/mês	2.000
Power	$200/mês	10.000

Os créditos são compartilhados entre IDE, CLI e Web. Overage: $0,04 por crédito adicional nos planos pagos.

Veredicto

Kiro IDE e CLI não competem — eles se complementam.

O IDE é onde você pensa e constrói. O CLI é onde você executa e automatiza.

Para a maioria dos desenvolvedores, a recomendação é:

Comece pelo IDE se você trabalha com features complexas ou quer entender o diferencial do Kiro (specs)
Adicione o CLI quando precisar de automação ou preferir terminal
Use os dois se seu trabalho mistura planejamento e execução operacional

A pergunta certa não é "qual é melhor?" — é "qual combina com o momento do seu trabalho?"

Perguntas Frequentes

Posso usar os dois com a mesma assinatura?

Sim. IDE, CLI e Web compartilham a mesma assinatura, os mesmos créditos e os mesmos steering files.

O CLI vai ganhar suporte a Powers?

Está no roadmap, mas sem data confirmada. Por enquanto, Powers são exclusivos do IDE.

Qual consome mais créditos?

Depende do uso. Specs no IDE consomem mais por feature (refinamento + design + tasks + implementação), mas podem reduzir retrabalho. O CLI consome menos por interação individual.

Hooks contam como créditos?

Não. Hooks são gratuitos — não contam contra sua cota mensal. Isso vale para IDE e CLI.

Posso migrar steering files do IDE para o CLI?

Não precisa migrar. Os dois leem de .kiro/steering/. É o mesmo arquivo.

Se você precisa de ajuda para configurar Kiro IDE e CLI no seu time, criar custom agents especializados, ou montar pipelines de CI/CD com agentes, conheça os serviços de consultoria em ft.ia.br.

Dados verificados em julho de 2026. Versões: Kiro IDE 0.7+, Kiro CLI 1.24+.

ARD — Agentic Resource Discovery: A Camada que Faltava no Ecossistema de Agentes

Wed, 22 Jul 2026 00:00:00 GMT

ARD — Agentic Resource Discovery: A Camada que Faltava no Ecossistema de Agentes

Imagine um hotel cinco estrelas com 200 quartos, spa, três restaurantes e um centro de conferências. Agora imagine que o concierge não tem acesso à lista de serviços. Ele sabe atender — é treinado, educado, eficiente — mas quando o hóspede pergunta "vocês têm um chef japonês?", ele precisa ligar para cada setor, um por um, perguntando se existe. Multiplique isso por 50 hóspedes simultâneos.

Esse é o estado atual do ecossistema de agentes IA.

Temos o MCP para um agente chamar ferramentas. Temos o A2A para agentes conversarem entre si. Mas quando um agente precisa responder "quem, nesse ecossistema, sabe fazer o que eu preciso?" — não há protocolo padrão. Ele depende de configuração manual, listas estáticas ou, pior, hardcode de endpoints.

O ARD — Agentic Resource Discovery é a especificação que resolve esse gap. É a lista de serviços do hotel, atualizada em tempo real, com verificação de identidade e busca semântica. Publicada em 17 de junho de 2026 como v0.9 (Draft), já conta com contribuições de Google, Microsoft, Hugging Face, GoDaddy, GitHub, Cisco, Databricks, NVIDIA, Salesforce, ServiceNow e Snowflake.

Não é coincidência que essas empresas estejam todas na mesa. O discovery é o gargalo que impede agentes de operarem em ecossistemas abertos. Sem ele, cada integração é um contrato bilateral negociado manualmente. Com ele, a web de agentes funciona como a web de documentos: publicou, está descobrível.

O que é ARD

ARD é uma especificação aberta (Apache 2.0) que define como agentes de IA descobrem capabilities, ferramentas e outros agentes disponíveis em um ecossistema. Foi construída sobre o ai-catalog standard da Linux Foundation AI Catalog Working Group.

Os autores — Junjie Bu (Google), R.V. Guha (Microsoft) e Shaun Smith (Hugging Face) — atacam um problema fundamental: à medida que o número de agentes e ferramentas cresce, o discovery manual não escala.

O repositório oficial fica em github.com/ards-project/ard-spec (398 stars, 46 forks, 91 commits em julho de 2026), com documentação em agenticresourcediscovery.org.

A arquitetura se apoia em duas primitivas:

Catálogo estático — um arquivo ai-catalog.json que cada publisher hospeda no seu domínio
Registry dinâmico — uma API com endpoint POST /search para busca semântica em tempo real

Pense no catálogo como a plaquinha na porta do quarto de hotel ("Suíte Master, capacidade 4 pessoas, vista mar"). O registry é o sistema de reservas que cruza sua busca ("quarto com vista mar para amanhã") com tudo que está disponível.

Catálogo Estático: ai-catalog.json

O ponto de entrada mais simples do ARD é o catálogo estático. Você cria um arquivo JSON e hospeda em /.well-known/ai-catalog.json no seu domínio. Qualquer agente que conheça essa convenção pode fazer discovery automático dos seus recursos.

Aqui está a estrutura real de um catálogo:

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Acme Corp AI",
    "identifier": "did:web:acme.corp"
  },
  "entries": [
    {
      "identifier": "urn:air:acme.corp:agents:invoice-processor",
      "displayName": "Invoice Processor Agent",
      "type": "application/a2a-agent-card+json",
      "url": "https://agents.acme.corp/invoice-processor/.well-known/agent.json",
      "description": "Processa faturas em PDF, extrai dados estruturados e reconcilia com o ERP",
      "capabilities": ["pdf-extraction", "data-reconciliation", "erp-integration"],
      "representativeQueries": [
        "processar fatura em PDF e extrair dados",
        "reconciliar nota fiscal com ERP"
      ],
      "trustManifest": {
        "identity": "spiffe://acme.corp/agents/invoice-processor",
        "identityType": "spiffe",
        "attestations": [
          { "type": "SOC2-Type2", "uri": "https://trust.acme.corp/reports/soc2.pdf" },
          { "type": "GDPR", "uri": "https://trust.acme.corp/compliance/gdpr" }
        ]
      }
    },
    {
      "identifier": "urn:air:acme.corp:tools:sentiment-analysis",
      "displayName": "Sentiment Analysis Tool",
      "type": "application/mcp-server-card+json",
      "url": "https://tools.acme.corp/sentiment/mcp.json",
      "description": "Análise de sentimento multilíngue via MCP server",
      "capabilities": ["text-analysis", "multilingual", "batch-processing"],
      "representativeQueries": [
        "analisar sentimento de reviews em português",
        "classificar tom de mensagens de suporte"
      ]
    }
  ]
}

Observe os pontos-chave:

type diferencia o tipo de recurso. O ARD suporta application/a2a-agent-card+json (agentes A2A), application/mcp-server-card+json (MCP servers), application/ai-skill, application/ai-registry+json e application/ai-catalog+json
capabilities permite busca por competência, não só por nome
representativeQueries são exemplos de perguntas em linguagem natural que o recurso responde — os registries usam esses exemplos para construir embeddings semânticos e ranquear resultados
trustManifest inclui identidade verificável e attestations de compliance
Cada entry exige exatamente um de url (referência remota) ou data (artefato inline) — nunca ambos

O catálogo estático é determinístico e cacheável. Não exige infraestrutura além de um web server. Um desenvolvedor indie pode publicar um ai-catalog.json no mesmo domínio onde já hospeda seu site e tornar seus tools descobríveis por qualquer agente que implemente ARD.

Mecanismos de Discovery

Para que agentes encontrem o catálogo, o ARD define quatro mecanismos de discovery:

Well-Known URI — /.well-known/ai-catalog.json (o padrão primário)
Agentmap em robots.txt — diretiva Agentmap: apontando para o catálogo
HTML Link Tag — <link rel="ai-catalog" href="/ai-catalog.json"> no head
DNS Service Binding records — para discovery a nível de infraestrutura

Isso é deliberado. O catálogo funciona como o robots.txt funciona para crawlers: uma convenção simples que qualquer agente sabe onde buscar.

Registry Dinâmico: POST /search

O catálogo estático resolve o caso de "eu conheço o domínio e quero saber o que ele oferece". Mas e quando você precisa buscar "quem no ecossistema faz análise de sentimento em português?"

Para isso existe o registry dinâmico. O ARD define uma API com três endpoints:

Endpoint	Método	Obrigatório?	Função
`/search`	POST	✅ Sim	Busca semântica com filtros
`/explore`	POST	Opcional	Agregações e facets
`/agents`	GET	Opcional	Listagem determinística completa

O endpoint obrigatório é o POST /search. Aqui está um request real:

{
  "query": {
    "text": "process invoices and extract structured data from PDF documents",
    "filter": {
      "type": ["application/a2a-agent-card+json"],
      "trustManifest.attestations.type": ["SOC2-Type2"]
    }
  },
  "federation": "auto",
  "pageSize": 5
}

E a resposta:

{
  "results": [
    {
      "identifier": "urn:air:acme.corp:agents:invoice-processor",
      "displayName": "Invoice Processor Agent",
      "type": "application/a2a-agent-card+json",
      "url": "https://agents.acme.corp/invoice-processor/.well-known/agent.json",
      "description": "Processa faturas em PDF, extrai dados estruturados e reconcilia com o ERP",
      "score": 92,
      "source": "https://registry.acme.corp/api/v1/"
    },
    {
      "identifier": "urn:air:fintech.io:agents:doc-extractor",
      "displayName": "Document Extraction Service",
      "type": "application/a2a-agent-card+json",
      "url": "https://api.fintech.io/.well-known/agent.json",
      "description": "Extração de dados de documentos financeiros com OCR avançado",
      "score": 78,
      "source": "https://finder.external.org/api/"
    }
  ],
  "referrals": [
    {
      "identifier": "urn:air:nlweb.ai:registry:public",
      "displayName": "Public Agent Finder",
      "type": "application/ai-registry+json",
      "url": "https://finder.nlweb.ai/search"
    }
  ],
  "pageToken": "eyJwYWdlIjogMn0="
}

O campo score merece atenção: é um valor de 0 a 100 representando relevância semântica da busca — não é um trust score. Um agente com score 92 é altamente relevante para a query textual, mas a decisão de confiar nele depende do trustManifest.

Repare no array referrals na resposta: quando o registry está no modo referrals ou auto, ele pode retornar ponteiros para outros registries que o cliente pode consultar. Isso é a federação em ação.

Identificadores URN: Endereçamento Global de Recursos

Cada recurso no ARD recebe um identificador único no formato URN (Uniform Resource Name) ancorado ao domínio do publisher:

urn:air:<publisher>:<namespace>:<resource-name>

Exemplos concretos:

URN	O que identifica
`urn:air:acme.corp:agents:invoice-processor`	Agente de processamento de faturas da Acme
`urn:air:huggingface.co:tools:text-generation`	Tool de geração de texto do Hugging Face
`urn:air:snowflake.com:agents:cortex-analyst`	Agente Cortex Analyst da Snowflake

O design é domain-anchored por uma razão: o domínio funciona como raiz de confiança. Se o URN diz urn:air:acme.corp:..., você sabe que o publisher controla acme.corp e pode verificar a identidade via DNS/TLS. Não existe um registro central — o namespace é tão distribuído quanto a própria web.

Isso resolve o problema de colisão de nomes sem exigir uma autoridade centralizada. Dois publishers podem ter um agente chamado "invoice-processor" sem conflito, porque o domínio os diferencia.

Trust Manifest: Verificação Criptográfica

Discovery sem trust é um vetor de ataque. Se qualquer agente pode se listar em um registry, como o consumidor sabe que aquele "Invoice Processor" não é um impostor?

O ARD resolve isso com o trustManifest — um objeto de metadados criptográficos que acompanha cada entry do catálogo. Ele cobre três dimensões:

1. Identidade

O publisher prova quem é através de mecanismos padronizados:

HTTPS FQDN — o mais simples: o recurso está no domínio X, e o TLS do domínio X prova ownership
SPIFFE IDs — identidade workload-level para ambientes cloud-native (ex: spiffe://acme.corp/agents/invoice-processor)
DIDs (Decentralized Identifiers) — para cenários onde identidade descentralizada é necessária

2. Attestations

Certificações e compliance verificáveis. Cada attestation tem um type e um uri apontando para o documento de prova:

{ "type": "SOC2-Type2", "uri": "https://trust.acme.corp/reports/soc2.pdf" }
{ "type": "HIPAA-Audit", "uri": "https://trust.acme.corp/compliance/hipaa" }
{ "type": "GDPR", "uri": "https://trust.acme.corp/compliance/gdpr" }

Não é um campo free-text. O formato estruturado permite que um agente consumidor filtre programaticamente por compliance requirements antes de consumir o recurso.

3. Proveniência

Metadados sobre a origem do recurso: quem criou, quando foi publicado, qual versão da spec implementa, histórico de atualizações.

O trustManifest não substitui uma avaliação de segurança completa — mas dá ao agente consumidor informações verificáveis para tomar decisões de trust automaticamente. Um agente enterprise pode ser configurado com uma política: "só consumir recursos com attestation SOC2 e identidade via SPIFFE". O registry filtra antes de retornar resultados.

Federação: Como Registries Conversam

Em produção, não vai existir um único registry global. Empresas terão registries privados, provedores de cloud terão registries públicos, comunidades open-source terão os deles. A spec define três modos de federação para interconexão:

Modo	Comportamento	Use case
auto	Merge automático — o registry combina resultados locais com resultados de registries federados	Discovery amplo, maximiza cobertura
referrals	Retorna ponteiros para outros registries em vez de resultados diretos	Quando o registro federado exige autenticação separada
none	Só resultados locais, sem federação	Ambientes isolados, compliance strict

Na prática, federação funciona assim: seu agente faz POST /search no registry corporativo. O registry verifica localmente, e se estiver no modo auto, também consulta registries federados (ex: o registry público do Hugging Face). Os resultados voltam unificados, com indicação de origem.

O modo referrals é mais conservador — o registry diz "não tenho isso, mas o registry X pode ter" e retorna o endpoint dele. O agente decide se quer seguir o referral. Isso é útil quando registries federados exigem autenticação própria ou operam sob jurisdições diferentes.

O modo none existe para ambientes regulados onde nenhum dado deve sair do perímetro — bancos, hospitais, governo. O registry funciona como catálogo interno e ponto final.

ARD vs MCP vs A2A: O Stack Completo

"Mais um protocolo? Por que não resolve tudo com MCP?"

Porque cada um resolve uma camada diferente — e as três são necessárias:

Dimensão	MCP	A2A	ARD
Pergunta que responde	"Como chamo essa tool?"	"Como falo com esse agente?"	"Quem sabe fazer o que eu preciso?"
Camada	Execução	Comunicação	Discovery
Analogia	O telefone	A língua franca	A lista telefônica
Publisher	Anthropic	Google	Google + Microsoft + Hugging Face
Timing	Nov 2024	Abr 2025	Jun 2026
Pré-requisito	—	—	MCP e/ou A2A

ARD não substitui MCP ou A2A. É a camada que senta na frente deles. O fluxo completo funciona assim:

ARD — Agente busca "quem processa faturas em PDF com compliance SOC2?"
A2A — Agente inicia comunicação com o Invoice Processor descoberto
MCP — Durante a conversa, o Invoice Processor chama tools de OCR e ERP via MCP

Sem ARD, o passo 1 é manual — um humano configura quais agentes cada sistema conhece. Com ARD, esse discovery acontece programaticamente, em tempo real, com verificação de trust.

Os três protocolos resolvem camadas diferentes: MCP deu braços aos agentes (tools). A2A deu voz (comunicação peer-to-peer). ARD dá visão (discovery do ecossistema).

Quem Já Implementou

A spec tem pouco mais de um mês desde a publicação, mas as implementações já estão em produção ou em beta avançado:

Hugging Face — A implementação de referência. O Discover Tool (hf discover search) faz busca semântica sobre os Spaces, retornando agentes e tools no formato ARD. Se você já usa o Hugging Face, pode testar hoje.

Snowflake — Cortex Agents com auto-registro ARD. Quando você deploya um agente via Cortex, ele se registra automaticamente no registry corporativo, ficando descobrível por outros agentes do mesmo tenant.

Google Cloud — Agent Registry no Gemini Enterprise Agent Platform. Anunciado na Cloud Next '26, disponível em breve. Será o registry nativo para quem usa Vertex AI Agent Builder.

GoDaddy — Agent Name Service (ANS), uma abordagem fascinante que usa DNS e PKI existentes como infra de identidade para agentes. Parceria com Cloudflare e Infoblox. Em vez de inventar uma nova camada de identidade, reutiliza a infraestrutura de nomes que já opera na internet há décadas.

IETF — O draft draft-hood-agtp-ard-00 está em processo de formalização, sinalizando que o ARD pode se tornar um padrão da internet (RFC), não só uma spec de indústria.

Implementações independentes — O Suganthan.com publicou um ai-catalog.json no seu domínio e relatou que um agente externo o descobriu automaticamente e interagiu com seus recursos — validando o modelo de discovery descentralizado na prática. Isso demonstra que ARD não é só para big tech: qualquer publisher com um domínio e um JSON pode participar do ecossistema.

O que Muda pra Você

Se você trabalha com agentes de IA — como desenvolvedor, arquiteto, ou product owner — o ARD altera o jogo em três dimensões:

Se você publica ferramentas ou agentes

Publicar um ai-catalog.json no seu domínio é o novo "SEO para agentes". Assim como você otimiza páginas para o Google encontrá-las, agora precisa publicar metadados estruturados para agentes encontrarem seus serviços.

O custo é mínimo — um arquivo JSON estático no well-known path. O retorno potencial é descobribilidade automática por qualquer agente que implemente ARD. Se você mantém um MCP server público ou um agente A2A, o catálogo é o que conecta esse recurso ao ecossistema sem depender de cadastro manual em marketplaces terceiros.

Se você constrói sistemas multi-agente

Discovery dinâmico via registry significa que seu orquestrador não precisa de uma lista estática de agentes disponíveis. Ele pode buscar capabilities em tempo real, adaptar-se a novos agentes que aparecem no ecossistema, e respeitar políticas de trust automaticamente.

Isso transforma arquiteturas multi-agente de "configuração manual para cada integração" para "discovery e composição em runtime".

Se você opera agentes em enterprise

O trust manifest é a peça que faltava para governança. Políticas corporativas podem ser expressas como filtros de registry: "só agentes com SPIFFE ID do nosso cluster", "só recursos com SOC2 e GDPR", "federar com o registry da consultoria X mas não com registries públicos".

Isso dá ao security team controle programático sobre quais recursos os agentes internos podem descobrir e consumir — sem bloquear a agilidade dos times que deployam novos agentes.

MCP para execução, A2A para comunicação, ARD para discovery. Cada camada resolve um problema distinto, e juntas formam a infraestrutura para agentes operarem em ecossistemas abertos — não em silos configurados à mão.

O ARD v0.9 ainda é draft. Vai evoluir, schemas vão mudar, e haverá edge cases não cobertos. Mas o modelo mental — catálogo estático para publishers, registry dinâmico para busca, trustManifest para segurança, federação para escala — já está claro. E já está em produção.

Se você publica tools ou agentes: crie seu ai-catalog.json. Se você consome: comece a integrar busca via registry. O custo de adoção é baixo, e o ecossistema não vai esperar.

Como Publicar ai-catalog.json: Torne Seus Agentes Descobríveis

Wed, 22 Jul 2026 00:00:00 GMT

Como Publicar ai-catalog.json: Torne Seus Agentes Descobríveis

Você construiu um MCP server, publicou uma skill, expôs uma API com capacidades de IA. Mas como um agente descobre que seu serviço existe? A resposta, desde junho de 2026, é o ai-catalog.json — um manifesto padronizado que funciona como o DNS do ecossistema de agentes. Você hospeda, agentes descobrem. Sem cadastro em marketplace, sem intermediários.

O ai-catalog.json é para agentes o que o robots.txt foi para crawlers: um contrato público que diz "aqui estão minhas capacidades, é assim que você se conecta". A diferença é que, em vez de dizer o que não acessar, você declara o que pode ser usado.

Pré-requisitos

Antes de criar seu catálogo, você precisa ter algo para expor. O ai-catalog.json é um manifesto — ele descreve o que existe, não cria funcionalidade. Você precisa de pelo menos um destes:

Um MCP server rodando (local ou remoto)
Uma skill publicada em repositório
Um agente A2A com endpoint acessível
Uma API que agentes podem consumir

Se você ainda não tem nenhum desses, volte quando tiver. O catálogo vem depois da implementação.

Anatomia do ai-catalog.json

O manifesto tem uma estrutura enxuta: um objeto host que identifica quem publica, e um array entries com os serviços disponíveis.

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Nome do Publicador"
  },
  "entries": []
}

Esse é o esqueleto mínimo válido. Vamos detalhar cada parte.

O objeto host

O host descreve quem está publicando o catálogo. Apenas displayName é obrigatório — o resto é opcional mas recomendado para catálogos em produção.

Campo	Obrigatório	Descrição
`displayName`	Sim	Nome legível do publicador
`identifier`	Não	DID ou domínio do publicador
`documentationUrl`	Não	URL da documentação geral
`logoUrl`	Não	URL do logotipo
`trustManifest`	Não	Manifesto de confiança para verificação

Cada entry no array

Cada item em entries representa um serviço, agente ou skill que você expõe. Quatro campos são obrigatórios:

Campo	Obrigatório	Descrição
`identifier`	Sim	URN único no formato `urn:air:<publisher>:<namespace>:<agent-name>`
`displayName`	Sim	Nome legível para humanos e agentes
`type`	Sim	Media type do serviço
`url` ou `data`	Sim (um dos dois)	Referência externa OU dados inline — mutuamente exclusivos

Os campos opcionais adicionam contexto para melhorar o discovery:

Campo	Descrição
`description`	Texto livre sobre o que o serviço faz
`tags`	Array de tags para categorização
`capabilities`	Capacidades específicas do serviço
`representativeQueries`	2-5 exemplos de perguntas que o serviço responde
`version`	Versão semântica do serviço
`updatedAt`	Timestamp ISO 8601 da última atualização
`metadata`	Objeto livre para dados extras
`trustManifest`	Manifesto de confiança específico da entry

O formato URN

O identificador segue o padrão AIR (Agent Identifier Registry):

urn:air:<publisher>:<namespace>:<agent-name>

Exemplos reais:

urn:air:hf.co:alice-dev:weather-agent — publicado no Hugging Face
urn:air:github.com:meu-user:minha-skill — publicado no GitHub
urn:air:meudominio.com:tools:api-converter — publicado em domínio próprio

Media types válidos

O campo type define que tipo de serviço a entry representa:

Media Type	Para quê
`application/mcp-server-card+json`	MCP servers
`application/a2a-agent-card+json`	Agentes A2A (Agent-to-Agent)
`application/ai-skill`	Skills de agentes
`application/ai-catalog+json`	Catálogos nested (federação)
`application/ai-registry+json`	Registries dinâmicos

Passo 1: Criar o Manifesto

Vamos a três exemplos práticos cobrindo os casos mais comuns.

Exemplo 1: MCP server com dados inline

Se seu MCP server é simples e você quer que os metadados fiquem direto no catálogo, use o campo data:

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Alice's AI Tools",
    "documentationUrl": "https://alice-dev.github.io/docs"
  },
  "entries": [
    {
      "identifier": "urn:air:hf.co:alice-dev:weather-agent",
      "displayName": "Weather Agent",
      "type": "application/mcp-server-card+json",
      "description": "Simple weather lookup using open data",
      "tags": ["weather", "open-data", "lookup"],
      "representativeQueries": [
        "What's the weather in São Paulo?",
        "Current temperature in Berlin",
        "Will it rain tomorrow in Tokyo?"
      ],
      "data": {
        "name": "Weather Agent",
        "description": "Simple weather lookup using open data",
        "tools": [
          {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "inputSchema": {
              "type": "object",
              "properties": {
                "city": { "type": "string" }
              },
              "required": ["city"]
            }
          }
        ]
      }
    }
  ]
}

O campo data contém a estrutura completa do MCP server card — nome, descrição e lista de tools com seus schemas. Agentes que encontram esse catálogo já sabem exatamente como invocar seu server.

Exemplo 2: Skill referenciada por URL

Se sua skill vive em um repositório e você não quer duplicar metadados, use url:

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Alice's AI Tools"
  },
  "entries": [
    {
      "identifier": "urn:air:github.com:alice-dev:pptx-creator",
      "displayName": "pptx-creator",
      "type": "application/ai-skill",
      "url": "https://github.com/alice-dev/pptx-creator",
      "description": "Create professional PowerPoint presentations following brand guidelines.",
      "tags": ["presentations", "pptx", "automation"],
      "representativeQueries": [
        "Create a slide deck for my quarterly review",
        "Generate a pitch presentation with 10 slides"
      ],
      "version": "2.1.0",
      "updatedAt": "2026-07-15T10:00:00Z"
    }
  ]
}

Com url, o agente sabe onde buscar os detalhes completos. Você mantém o catálogo leve e a fonte da verdade no repositório.

Exemplo 3: Agente A2A com endpoint

Para um agente que aceita comunicação Agent-to-Agent:

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Minha Empresa IA",
    "identifier": "minhaempresa.com.br",
    "logoUrl": "https://minhaempresa.com.br/logo.png"
  },
  "entries": [
    {
      "identifier": "urn:air:minhaempresa.com.br:agents:tradutor-juridico",
      "displayName": "Tradutor Jurídico PT-EN",
      "type": "application/a2a-agent-card+json",
      "url": "https://api.minhaempresa.com.br/.well-known/agent.json",
      "description": "Traduz documentos jurídicos entre português e inglês com terminologia especializada.",
      "tags": ["translation", "legal", "pt-br", "en"],
      "capabilities": ["document-translation", "terminology-glossary"],
      "representativeQueries": [
        "Traduza este contrato para inglês",
        "Qual a tradução jurídica de 'cláusula resolutória'?",
        "Revise a tradução deste parecer"
      ],
      "version": "1.0.0",
      "updatedAt": "2026-07-20T14:30:00Z"
    }
  ]
}

Note que url e data são mutuamente exclusivos — use um ou outro, nunca os dois na mesma entry.

Catálogo com múltiplas entries

Na prática, você vai ter mais de um serviço. Basta adicionar ao array:

{
  "specVersion": "1.0",
  "host": {
    "displayName": "DevTools Corp",
    "identifier": "devtools.io",
    "documentationUrl": "https://docs.devtools.io"
  },
  "entries": [
    {
      "identifier": "urn:air:devtools.io:mcp:code-reviewer",
      "displayName": "Code Reviewer",
      "type": "application/mcp-server-card+json",
      "url": "https://devtools.io/.well-known/mcp/code-reviewer.json",
      "description": "Automated code review with security focus",
      "representativeQueries": [
        "Review this pull request for security issues",
        "Find potential SQL injection vulnerabilities"
      ]
    },
    {
      "identifier": "urn:air:devtools.io:skills:test-generator",
      "displayName": "Test Generator",
      "type": "application/ai-skill",
      "url": "https://github.com/devtools-io/test-generator",
      "description": "Generate comprehensive test suites from source code",
      "representativeQueries": [
        "Generate unit tests for this module",
        "Create integration tests for the auth flow"
      ]
    }
  ]
}

Passo 2: Hospedar em /.well-known/

O local canônico para o manifesto é /.well-known/ai-catalog.json. É o primeiro lugar que agentes vão procurar — a mesma convenção que .well-known/security.txt ou .well-known/openid-configuration.

O Content-Type deve ser application/json.

Nginx

Adicione ao bloco server do seu domínio:

location /.well-known/ai-catalog.json {
    alias /var/www/meusite/ai-catalog.json;
    default_type application/json;
    add_header Access-Control-Allow-Origin "*";
    add_header Cache-Control "public, max-age=3600";
}

O header CORS (Access-Control-Allow-Origin: *) é importante — agentes fazem requisições de domínios diferentes. O Cache-Control de 1 hora é um bom default; ajuste conforme a frequência de atualização do seu catálogo.

Cloudflare Pages

Se seu site está no Cloudflare Pages, crie o arquivo na pasta public/.well-known/:

public/
└── .well-known/
    └── ai-catalog.json

Adicione um _headers na raiz do public/ para configurar os headers:

/.well-known/ai-catalog.json
  Content-Type: application/json
  Access-Control-Allow-Origin: *
  Cache-Control: public, max-age=3600

O Cloudflare Pages serve arquivos estáticos da pasta public/ sem necessidade de configuração de rotas.

Vercel

No Vercel, coloque o arquivo em public/.well-known/ai-catalog.json e adicione ao vercel.json:

{
  "headers": [
    {
      "source": "/.well-known/ai-catalog.json",
      "headers": [
        { "key": "Content-Type", "value": "application/json" },
        { "key": "Access-Control-Allow-Origin", "value": "*" },
        { "key": "Cache-Control", "value": "public, max-age=3600" }
      ]
    }
  ]
}

Confirmação rápida

Depois do deploy, teste com curl:

curl -I https://seudominio.com/.well-known/ai-catalog.json

Você deve ver 200 OK com Content-Type: application/json. Se vir 404, o arquivo não está no path certo. Se vir 301/302, garanta que o redirect final chega no JSON.

Passo 3: Adicionar Sinais de Discovery

O well-known URI é o mecanismo primário, mas existem sinais complementares que aumentam a probabilidade de agentes encontrarem seu catálogo. Pense neles como redundância — cada um cobre um cenário diferente de discovery.

robots.txt

Adicione a diretiva Agentmap ao seu robots.txt:

User-agent: *
Allow: /

Agentmap: https://seudominio.com/.well-known/ai-catalog.json

Crawlers de agentes que respeitam o robots.txt vão encontrar seu catálogo mesmo sem acessar o well-known path diretamente. Funciona de forma análoga ao Sitemap: que você já usa para SEO.

HTML link tag

No <head> das suas páginas (especialmente a homepage), adicione:

<link rel="ai-catalog" href="/.well-known/ai-catalog.json">

Agentes que renderizam ou parsam HTML vão detectar essa tag. É útil quando o agente está navegando seu site e precisa descobrir o catálogo a partir de qualquer página.

DNS Service Binding

Para discovery no nível de infraestrutura, sem depender de HTTP:

_catalog._agents.seudominio.com.  IN  SVCB  1 seudominio.com. (
    alpn="h2,h3" path="/.well-known/ai-catalog.json"
)

O record DNS _catalog._agents permite que agentes descubram seu catálogo via resolução DNS antes mesmo de fazer uma requisição HTTP. É o mecanismo mais robusto, mas também o mais avançado — implemente apenas se já tem familiaridade com records SRV/SVCB.

Qual usar?

Para a maioria dos casos, o well-known URI + robots.txt + HTML link cobrem 99% dos cenários. O DNS é para quem quer cobertura total em ambientes enterprise ou redes privadas.

Passo 4: Validar com Ferramentas Oficiais

Antes de considerar o deploy feito, valide a estrutura do seu manifesto.

Validação de schema com ajv-cli

O repositório do ai-catalog standard inclui schemas JSON Schema que você pode usar diretamente:

npx ajv-cli validate \
  -s spec/schemas/ai-catalog.schema.json \
  -d ./ai-catalog.json

Se o manifesto estiver correto, a saída será limpa. Se houver erros — campo obrigatório faltando, tipo errado, URL e data na mesma entry — o ajv mostra exatamente onde está o problema.

Teste de conformance completo

Para uma verificação mais rigorosa que vai além da estrutura (testa resolução de URLs, formatos de URN, media types válidos):

./conformance/bin/conformance-test manifest ./ai-catalog.json

Esse teste é mais pesado — faz requisições reais para URLs declaradas e valida que respondem corretamente. Use em staging antes de publicar.

Validação manual rápida

Se quiser apenas checar se o JSON é válido e tem a estrutura básica:

cat ai-catalog.json | python3 -m json.tool > /dev/null && echo "JSON válido"

E uma checagem rápida dos campos obrigatórios:

cat ai-catalog.json | python3 -c "
import json, sys
data = json.load(sys.stdin)
assert 'specVersion' in data, 'Falta specVersion'
assert 'host' in data, 'Falta host'
assert 'displayName' in data['host'], 'Falta host.displayName'
assert 'entries' in data, 'Falta entries'
for i, e in enumerate(data['entries']):
    assert 'identifier' in e, f'Entry {i}: falta identifier'
    assert 'displayName' in e, f'Entry {i}: falta displayName'
    assert 'type' in e, f'Entry {i}: falta type'
    assert ('url' in e) != ('data' in e), f'Entry {i}: precisa de url OU data (não ambos, não nenhum)'
print(f'✓ Válido: {len(data[\"entries\"])} entries')
"

Passo 5: Testar com Hugging Face Discover

O Hugging Face Discover é um search engine que indexa ai-catalog.json de domínios públicos. É a forma mais rápida de verificar se seu catálogo está acessível e bem formatado "do lado de fora".

Verificar se o HF já tem seu catálogo

Faça um POST para o endpoint de busca:

curl -X POST https://huggingface-hf-discover.hf.space/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "text": "nome-do-seu-servico"
    },
    "pageSize": 5
  }'

Se seu catálogo já foi indexado, a resposta vai incluir suas entries. Se não aparecer nada, o indexador ainda não passou pelo seu domínio — pode levar algumas horas após a primeira publicação.

Como funciona o discovery no HF

O Hugging Face mantém um crawler que periodicamente busca /.well-known/ai-catalog.json em domínios conhecidos. O próprio HF publica o seu em:

https://huggingface.co/.well-known/ai-catalog.json

O Discover também expõe um endpoint MCP para que outros agentes possam buscar programaticamente:

https://huggingface-hf-discover.hf.space/mcp

Isso significa que um agente conectado ao MCP do HF Discover pode buscar seus serviços em runtime — exatamente o cenário que o ai-catalog.json resolve.

Teste end-to-end

Para simular o que um agente faria ao encontrar seu catálogo:

# 1. Busca o catálogo
curl -s https://seudominio.com/.well-known/ai-catalog.json | jq '.entries[].displayName'

# 2. Verifica se o HF Discover encontra
curl -s -X POST https://huggingface-hf-discover.hf.space/search \
  -H "Content-Type: application/json" \
  -d '{"query": {"text": "weather agent"}, "pageSize": 3}' | jq '.results[:3]'

Se os dois passos funcionam, seu catálogo está operacional.

Boas Práticas para representativeQueries

O campo representativeQueries é opcional, mas é o que mais impacta a qualidade do discovery. Agentes usam essas queries para decidir se seu serviço é relevante para o que o usuário pediu. Pense nelas como os exemplos de invocação de uma skill — quanto mais realistas, melhor o matching.

Regras de ouro

2 a 5 queries por entry. Menos que 2 não dá contexto suficiente. Mais que 5 dilui a relevância.

Use linguagem natural, não comandos técnicos. O agente vai comparar a query do usuário com seus exemplos. Usuários não dizem "invoke get_weather with params city=SP" — dizem "como está o tempo em São Paulo?".

// ❌ Ruim — linguagem de desenvolvedor
"representativeQueries": [
  "call get_weather API",
  "fetch weather data for location"
]

// ✓ Bom — linguagem de usuário
"representativeQueries": [
  "What's the weather in São Paulo?",
  "Will it rain tomorrow in New York?",
  "Current temperature in Berlin"
]

Cubra cenários diferentes, não variações da mesma pergunta. Cada query deve representar um caso de uso distinto.

// ❌ Ruim — três formas de dizer a mesma coisa
"representativeQueries": [
  "Translate this document",
  "Can you translate this?",
  "Please translate"
]

// ✓ Bom — três cenários diferentes
"representativeQueries": [
  "Translate this contract to English",
  "What's the legal term for 'cláusula resolutória' in English?",
  "Review the translation accuracy of this legal brief"
]

Inclua o idioma que seus usuários realmente usam. Se seu serviço atende brasileiros, queries em português. Se é global, misture.

Seja específico sobre o domínio. "Analyze this" não ajuda. "Analyze the SEO performance of this landing page" ajuda muito.

Próximos Passos: trustManifest para Enterprise

Para uso pessoal ou projetos open-source, o catálogo básico é suficiente. Mas em contextos enterprise — onde agentes precisam decidir se confiam no seu serviço — existe o trustManifest.

O trust manifest é um objeto que pode aparecer tanto no host (nível do publicador) quanto em cada entry (nível do serviço). Ele declara informações verificáveis sobre identidade e procedência.

Estrutura do trustManifest

Campo	Obrigatório	Descrição
`identity`	Sim	Identificador verificável (DID, domínio, org ID)
`identityType`	Não	Tipo do identificador (e.g., "domain", "did:web")
`attestations`	Não	Array de atestações de terceiros
`provenance`	Não	Array de informações de procedência
`signature`	Não	Assinatura criptográfica do manifesto

Exemplo prático

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Empresa Verificada Ltda",
    "identifier": "did:web:empresa-verificada.com.br",
    "trustManifest": {
      "identity": "did:web:empresa-verificada.com.br",
      "identityType": "did:web",
      "attestations": [
        {
          "type": "domain-verification",
          "verifier": "cloudflare.com",
          "issuedAt": "2026-06-01T00:00:00Z"
        }
      ],
      "provenance": [
        {
          "type": "source-repository",
          "url": "https://github.com/empresa-verificada/ai-services"
        }
      ]
    }
  },
  "entries": []
}

O trust manifest permite que agentes enterprise apliquem políticas de confiança — "só conectar a serviços com domínio verificado", "exigir assinatura criptográfica", "aceitar apenas atestações de CAs conhecidas". Na prática, é o que separa um ecossistema de "confia em tudo" de um que opera com critério.

Para começar, publique sem trust manifest. Quando seus consumidores forem organizações com políticas de segurança, adicione. O padrão é progressivo — funciona sem, melhora com.

Resumo do Fluxo

Cinco passos para tornar seus serviços descobríveis:

Crie o ai-catalog.json com host + entries
Hospede em /.well-known/ai-catalog.json com CORS habilitado
Sinalize via robots.txt, HTML link tag e (opcionalmente) DNS
Valide com ajv-cli ou conformance test
Teste com Hugging Face Discover

O ai-catalog.json é a primitiva mais simples do ecossistema de interoperabilidade de agentes. Um arquivo JSON estático, sem auth, sem SDK, sem vendor lock-in. Publique o seu, teste com o HF Discover, e veja agentes encontrarem seus serviços sem que você precise fazer mais nada.

Build → Scale → Govern → Optimize: O Ciclo de Vida dos Agentes Enterprise

Sat, 18 Jul 2026 00:00:00 GMT

TL;DR: Construir um agente de IA é a parte fácil. O que separa protótipos de sistemas em produção são quatro estágios distintos — Build, Scale, Govern e Optimize — que formam um ciclo contínuo. 88% dos agentes enterprise morrem no piloto porque as equipes dominam o primeiro estágio e ignoram os outros três. Este post detalha o que cada etapa exige de verdade, usando o Gemini Enterprise Agent Platform como referência concreta, mas com princípios que se aplicam a qualquer stack.

O Problema: Todo Mundo Sabe Construir, Quase Ninguém Sabe Operar

Existe uma estatística incômoda circulando nos relatórios de 2026: segundo dados da Forrester e da Anaconda, 88% dos agentes de IA enterprise não sobrevivem à fase de piloto. Não é que as equipes não saibam programar. É que construir é apenas o primeiro ato de uma peça com quatro.

O ciclo Build → Scale → Govern → Optimize resolve exatamente esse gap. Ele nomeia os quatro estágios que toda equipe precisa atravessar para levar um agente do "funciona no meu notebook" ao "opera em produção com confiança do negócio".

Pense assim: construir uma casa é empilhar tijolos e levantar paredes. Mas torná-la habitável exige encanamento, fiação elétrica, sistema de segurança e manutenção periódica. Uma casa sem encanamento é só uma escultura — bonita, mas inabitável. Um agente sem os três estágios posteriores ao Build é a mesma coisa: uma demo impressionante que nunca vira produto.

O artigo "13 hands-on demos to build on Gemini Enterprise Agent Platform" do Google Cloud (julho 2026) apresenta essas 13 demos organizadas exatamente nesse ciclo. Vou usar essa estrutura como mapa, extraindo os princípios que se aplicam independente do cloud provider que você usa.

Vamos estágio por estágio.

Build: Da Ideia ao Agente Funcional

É aqui que a maioria das equipes se sente em casa. Você define o que o agente faz, quais tools ele acessa, como ele raciocina. O terreno dos SDKs, dos notebooks e dos hackathons internos.

ADK: Code-First e Multi-Linguagem

O Google Agent Development Kit (ADK) é a ferramenta central desse estágio na plataforma Gemini. A filosofia é code-first: você escreve agentes como código, não como configurações em uma UI. Python e Java são suportados nativamente, e o ADK 2.0 trouxe a graph-based workflow API — onde você define fluxos como grafos dirigidos.

from google.adk import Agent, Tool
from google.adk.workflows import Graph, Node

# Agente básico com ADK
expense_agent = Agent(
    name="expense-reviewer",
    model="gemini-2.5-pro",
    tools=[
        Tool(name="check_policy", fn=check_expense_policy),
        Tool(name="approve_expense", fn=approve_in_erp),
    ],
    instructions="Revise despesas contra a política corporativa. Aprove automaticamente se < R$500 e dentro da política."
)

Isso é um agente funcional. Roda no seu laptop. Responde perguntas. Até impressiona na demo de sexta-feira. Mas se você parar aqui, ele morre na segunda-feira seguinte quando alguém perguntar "como a gente coloca isso em produção?".

Padrões Arquiteturais do Build

As demos do Google Cloud mostram quatro padrões fundamentais nesse estágio:

Agente básico — um LLM com tools. É o "Hello World" dos agentes. Funciona, mas é frágil.
Event-driven com human-in-the-loop — o agente processa eventos (um email chegou, um ticket abriu) e pausa quando precisa de aprovação humana. Esse padrão é crítico: agentes enterprise raramente têm autoridade para decidir tudo sozinhos.
MCP para acesso a dados — o Model Context Protocol padroniza como agentes acessam dados de sistemas externos. Em vez de cada agente reimplementar conectores, você expõe dados via MCP servers.
A2UI (Agent-to-UI) — agentes que geram interfaces dinâmicas para o usuário, em vez de só texto. Quando o agente precisa coletar dados estruturados, ele renderiza um formulário em vez de pedir "me diga o valor, a data e a categoria".

O Ponto Cego do Build

Aqui está o que a maioria dos times ignora: o melhor agente de build não vale nada se morrer no deploy. Você pode ter o prompt perfeito, as tools mais elegantes, a lógica mais sofisticada — mas se não existir um caminho claro do código para produção, você tem um protótipo eterno.

O Build é necessário, mas é o estágio mais superestimado. O valor real está nos três estágios seguintes.

Scale: Do Laptop ao Tráfego Real

Escalar um agente não é só "colocar num servidor maior". É resolver uma série de problemas que simplesmente não existem quando você roda localmente: gerenciamento de sessão, estado persistente, concorrência, deploys sem downtime e discovery entre agentes.

Agent Runtime: Infra Gerenciada

O Agent Runtime do Google Cloud é a camada que executa seus agentes em produção. Scaling automático, health checks, restart automático. Pense nele como o Kubernetes dos agentes — você declara o que quer, a plataforma garante que acontece.

Na prática, isso resolve:

Scaling automático — seu agente de atendimento recebe 50 requests às 3h da manhã e 5.000 às 10h. O runtime escala sem intervenção.
Session management — cada conversa mantém estado isolado. Usuário A não vê dados do Usuário B.
Graceful degradation — quando o LLM está lento, o runtime gerencia filas e timeouts em vez de derrubar tudo.

Memory Bank: Estado Cross-Session

Um dos problemas mais subestimados de agentes em produção é memória entre sessões. O usuário volta dois dias depois — o agente lembra do contexto anterior? Sem Memory Bank, você precisa reimplementar RAG do zero — vector store, chunking, retrieval — para cada agente.

O Memory Bank resolve isso como primitiva de plataforma. O agente persiste fatos relevantes e os recupera automaticamente na próxima interação.

from google.adk.memory import MemoryBank

# O agente lembra contexto cross-session automaticamente
agent = Agent(
    name="customer-support",
    memory=MemoryBank(
        scope="per-user",
        retention="90d",
        auto_summarize=True
    )
)

Agentes Long-Running

Nem todo agente responde em segundos. Um agente de onboarding de cliente pode levar 3 dias coletando documentos. Um agente de análise financeira pode processar dados por horas.

Agentes long-running pausam, retomam e sobrevivem a restarts. Se o servidor reinicia no meio de um workflow de 72 horas, o agente retoma de onde parou. Isso exige checkpointing de estado — algo que frameworks locais simplesmente não oferecem.

Agent Registry: Discovery Cross-Org

Quando você tem 5 agentes, organização é trivial. Quando tem 500 espalhados por 20 times, você precisa de um catálogo. O Agent Registry é esse catálogo: um registro central onde cada agente declara suas capacidades, e outros agentes (ou humanos) podem descobri-lo.

Isso é particularmente relevante quando você adota A2A (Agent-to-Agent) — agentes chamando outros agentes. Sem registry, cada integração é point-to-point. Com registry, agentes se descobrem dinamicamente.

Agents CLI: Deploy One-Command

# Do notebook ao Cloud Run com um comando
agents deploy expense-reviewer \
  --runtime cloud-run \
  --scaling min=1,max=50 \
  --memory-bank enabled \
  --registry publish

O Agents CLI elimina o gap entre "funciona localmente" e "está em produção". Um comando. Sem Dockerfiles manuais, sem terraform verboso, sem 47 steps no CI/CD.

Exemplo Concreto: O Agente de Despesas

Imagine o ciclo completo: você construiu um agente que revisa despesas (Build). Agora precisa escalá-lo:

Deploy via CLI no Cloud Run
Memory Bank habilitado para lembrar políticas de gasto por departamento
Long-running habilitado para despesas que precisam de múltiplas aprovações
Registrado no Agent Registry para que o agente de RH possa chamá-lo via A2A
Dashboard de observabilidade com métricas de latência, taxa de aprovação e erros

Em 15 minutos você saiu do notebook para um sistema que atende 200 funcionários simultaneamente. Isso é Scale.

Govern: Guardrails Sem Sufocar a Inovação

É nesse estágio que a maioria dos projetos morre de verdade. Não por falta de tecnologia — por falta de governança proporcional. Times de segurança bloqueiam tudo. Ou, pior, não bloqueiam nada e um incidente acontece.

Governança não é um portão binário (aberto/fechado). É um espectro que depende do risco.

Agent Gateway: Identidade por Agente

O Agent Gateway trata cada agente como um cidadão de primeira classe na sua rede. Cada agente tem identidade própria (não herda creds do desenvolvedor), se comunica via mTLS, e acessa recursos via IAM com least privilege.

Na prática:

O agente de FAQ só acessa a base de conhecimento pública
O agente de despesas acessa o ERP com permissão de leitura e escrita limitada
O agente de RH acessa dados sensíveis com auditoria completa

Identity-Aware Proxy (IAP) garante que agentes acessando APIs internas passam pela mesma camada de autenticação que humanos. Sem atalhos.

Model Armor: Proteção em Tempo Real

Model Armor é a camada que inspeciona inputs e outputs em busca de:

Prompt injection — tentativas de manipular o agente via input malicioso
Data leakage — o agente tentando exfiltrar dados sensíveis nas respostas
Jailbreak attempts — tentativas de fazer o agente ignorar suas instruções

# Configuração de Model Armor
armor:
  input_filters:
    - prompt_injection_detection: high
    - pii_redaction: enabled
  output_filters:
    - data_leakage_prevention: enabled
    - toxicity_check: medium
  actions:
    on_violation: block_and_log

O diferencial é que essa inspeção acontece em tempo real, não como auditoria pós-fato. O agente é impedido de responder antes de vazar dados.

Secure Agentic Coding: TDD para Agentes

O Google introduziu o conceito de Secure Agentic Coding — uma abordagem onde agentes que escrevem ou executam código passam por camadas de validação:

TDD (Test-Driven Development) — o agente gera testes antes do código
STRIDE threat model — análise automática de ameaças em cada tool call
PreToolUse gates — callbacks que validam parâmetros antes de executar uma tool

from google.adk.security import PreToolUseGate

def validate_db_query(tool_name, params):
    """Gate que impede queries destrutivas"""
    if tool_name == "execute_sql":
        query = params.get("query", "").upper()
        if any(kw in query for kw in ["DROP", "DELETE", "TRUNCATE"]):
            raise SecurityViolation(
                f"Query destrutiva bloqueada: {query[:50]}..."
            )

agent.add_gate(PreToolUseGate(validate_db_query))

Governança Proporcional ao Risco

O princípio mais importante desse estágio: não trate um chatbot FAQ igual a um agente com acesso ao banco de dados de produção.

Um agente que responde perguntas sobre documentação pública precisa de:

Rate limiting
Logging básico
Filtro de toxicidade

Já um agente que executa transações financeiras precisa de:

Identidade mTLS
Model Armor completo
Human-in-the-loop para valores acima de um threshold
Audit trail imutável
PreToolUse gates em toda tool destrutiva

A proporção é: quanto maior o blast radius de um erro, mais camadas de proteção. Parece óbvio escrito assim, mas na prática a maioria dos times aplica a mesma régua para todos os agentes — e o resultado é ou segurança insuficiente para agentes críticos, ou burocracia paralisante para agentes simples.

Se você leu o post sobre por que agentes morrem no piloto, vai reconhecer esse padrão. A governança mal calibrada é uma das top 3 causas de morte de projetos. Times de segurança dizem "não pode" sem calibrar o risco, e o projeto morre na gaveta.

Optimize: O Flywheel que Nunca Para

Deploy em produção não é o fim — é o começo do trabalho de verdade. Agentes em produção degradam. Modelos são atualizados. Usuários encontram edge cases. Sem um ciclo de otimização contínua, seu agente fica pior com o tempo, não melhor.

AutoRaters: Avaliação Automatizada em Escala

O Google DeepMind desenvolveu os AutoRaters — modelos que avaliam a qualidade de outputs de outros modelos. Em vez de humanos revisarem milhares de respostas manualmente, AutoRaters fazem triagem:

Esta resposta está factualmente correta?
O agente seguiu as instruções?
A resposta contém alucinação?
O tom é adequado para o contexto enterprise?

AutoRaters não substituem avaliação humana, mas escalam ela. Humanos revisam os casos ambíguos que o AutoRater flagga, não cada resposta individual.

O Ciclo de 5 Estágios

A otimização contínua segue um pipeline estruturado:

OTel Traces → Inferência de Qualidade → Grade Automática → Clustering → Otimizações

OTel Traces — cada interação do agente gera traces OpenTelemetry: latência, tokens usados, tools chamadas, decisões tomadas.
Inferência de qualidade — AutoRaters processam esses traces e geram scores de qualidade por dimensão (factualidade, relevância, completude, segurança).
Grade automática — cada interação recebe uma nota. A distribuição ao longo do tempo mostra se o agente está melhorando ou degradando.
Clustering — interações com notas baixas são agrupadas por padrão. "70% das falhas são em perguntas sobre reembolso internacional" é mais acionável que "o agente tem accuracy de 82%".
Otimizações — baseado nos clusters, você ajusta prompts, adiciona tools, melhora exemplos ou atualiza dados. E o ciclo recomeça.

A pergunta-chave em toda otimização é: "você melhorou 3 exemplos ou quebrou 10 outros?" Sem um framework de avaliação automatizado, é impossível responder isso com confiança.

A2A Protocol: Pipelines Cross-Language

O Agent-to-Agent (A2A) protocol é o HTTP dos agentes. Ele padroniza como agentes de diferentes frameworks se comunicam. Para otimização, isso é fundamental — permite construir pipelines onde:

Um agente ADK faz o processamento principal
Um agente LangGraph faz avaliação de qualidade
Um agente CrewAI faz a análise de clusters

Cada time usa o framework que domina, e A2A conecta tudo.

# Pipeline de otimização multi-framework via A2A
pipeline:
  - agent: expense-reviewer  # ADK
    protocol: a2a
    role: primary
    
  - agent: quality-evaluator  # LangGraph
    protocol: a2a
    role: evaluator
    input: primary.output
    
  - agent: pattern-analyzer   # CrewAI
    protocol: a2a
    role: analyzer
    input: evaluator.low_scores

Multi-Framework: A Realidade das Organizações

Nenhuma organização grande usa um só framework. O time de ML usa LangGraph. O time de produto usa ADK. O time de dados usa CrewAI. A2A permite que isso funcione sem forçar migração.

Otimização cross-framework significa que um agente avaliador pode monitorar agentes de qualquer stack. O pipeline de melhoria contínua é agnóstico ao framework de implementação.

Como Esse Ciclo Se Aplica Fora do Google Cloud

Talvez você esteja pensando: "legal, mas eu uso AWS" ou "minha empresa está no Azure". O ponto central é este: os quatro estágios são universais. As implementações são específicas de cada plataforma.

AWS Bedrock AgentCore

A AWS anunciou o AgentCore seguindo essa mesma lógica:

Build → Bedrock Agents com tool use
Scale → Runtime gerenciado, memory e identity
Govern → Guardrails, IAM por agente
Optimize → Evaluation framework integrado

Azure AI Foundry

A Microsoft convergiu para o mesmo modelo:

Build → Azure AI Agent Service, Semantic Kernel
Scale → Managed runtime, session state
Govern → Content Safety, Azure RBAC
Optimize → AI Studio evaluations

LangGraph Platform

Até plataformas open-source seguem o padrão:

Build → LangGraph SDK
Scale → LangGraph Cloud, checkpointing
Govern → LangSmith guardrails (mais limitado)
Optimize → LangSmith analytics e datasets

O Framework de Decisão

Mais do que a plataforma em si, o que importa é ter uma resposta clara para cada estágio:

Estágio	Pergunta-chave
Build	Como desenvolvedores criam e testam agentes localmente?
Scale	Como o agente vai de 1 a 10.000 requests sem reescrever código?
Govern	Como controlamos acesso, auditamos ações e prevenimos incidentes?
Optimize	Como sabemos se o agente está melhorando ou degradando ao longo do tempo?

Se você tem respostas concretas (não "a gente resolve depois") para as quatro, está no caminho certo. Se alguma está em branco, é ali que seu agente vai morrer.

A analogia com DevOps dez anos atrás é inevitável. Em 2014, muitas equipes sabiam escrever código mas não sabiam operar. CI/CD, observabilidade, infrastructure-as-code — tudo isso virou table stakes. Estamos no mesmo ponto com agentes: AgentOps está se tornando table stakes, e o ciclo Build→Scale→Govern→Optimize é o framework mental que organiza essa disciplina.

Próximos Passos

Se esse post te deu a visão macro do ciclo, aqui estão os caminhos para aprofundar cada estágio:

Build

Google ADK: Guia Prático para Começar — setup, primeiro agente, tools e deploy local
Agent Frameworks vs Coding Agents: Quando Usar Cada Um — entenda quando um framework faz sentido e quando código puro é melhor

Scale & Govern

Por Que Agentes Morrem no Piloto — os 7 padrões de falha que matam agentes antes de chegarem a produção
MCP na Prática — como Model Context Protocol resolve o problema de acesso a dados em escala

Optimize

Guia Google ADK — inclui seção sobre AutoRaters e avaliação de qualidade

Quer ajuda para implementar esse ciclo?

O ciclo Build→Scale→Govern→Optimize exige decisões técnicas e organizacionais que variam muito conforme o time, stack, compliance e budget. Se você está montando ou escalando uma prática de agentes enterprise e quer um parceiro técnico que já passou por esse caminho, vamos conversar.

Baseado no artigo "13 hands-on demos to build on Gemini Enterprise Agent Platform" (Google Cloud, 17 de julho de 2026) e em experiência prática com deploys enterprise de agentes de IA.

Agents CLI: Guia Definitivo da CLI que Transforma Seu Coding Agent em Especialista Google ADK

Sat, 18 Jul 2026 00:00:00 GMT

TL;DR — O Agents CLI é uma CLI open-source do Google que se instala no seu coding agent (Claude Code, Codex, Antigravity) e injeta 7 skills especializadas para scaffold, evaluate, deploy, monitor, register, secure e iterate agentes ADK. Você descreve o que quer em plain English, o coding agent faz o resto. Zero context-switch. Tudo do editor.

Overview: O que é o Agents CLI

Imagine que seu coding agent — Claude Code, Codex CLI, Google Antigravity — acordasse amanhã sabendo tudo sobre o Agent Development Kit (ADK), o Agent Platform, Cloud Trace, AutoRaters e o Agent Registry.

Não sabendo "em teoria". Sabendo executar. Scaffold, deploy, evaluate, monitor. Tudo.

É exatamente isso que o Agents CLI faz.

O conceito

O Agents CLI não é mais uma CLI que você opera manualmente no terminal. É uma CLI que se instala dentro do seu coding agent e expõe 7 skills especializadas. Quando você pede "crie um agente de atendimento ao cliente com ADK", o coding agent já sabe como fazer — porque o Agents CLI injetou o conhecimento.

A proposta: descreva o que quer em plain English (ou português mesmo) e o coding agent cuida do scaffold, evaluate, deploy e monitor. Sem sair do editor. Sem abrir console. Sem copiar comandos de documentação.

O diferencial

Existem dezenas de CLIs no ecossistema de agentes. O que torna o Agents CLI diferente é o público-alvo: não é para humanos operarem diretamente — é para coding agents operarem em seu nome.

Você nunca precisa aprender a sintaxe. Você nunca precisa lembrar flags. Você conversa com seu coding agent, e ele usa as skills por baixo.

Compatibilidade

O Agents CLI funciona com qualquer coding agent que suporte extensibilidade:

Claude Code — via instalação de skills/extensões
Codex CLI — via sistema de plugins
Google Antigravity — integração nativa
Qualquer coding agent com suporte a instruções externas

Open-source e gratuito

O Agents CLI é open-source e gratuito. Você paga apenas pelos recursos de infraestrutura que usar no Google Cloud (compute, storage, etc.) — a CLI em si não tem custo.

🔗 Documentação oficial: https://google.github.io/agents-cli/guide/getting-started/

Tutorial: Instalando e Usando o Agents CLI

Vamos do zero ao agente em produção. Passo a passo, sem enrolação.

Pré-requisitos

Antes de começar, você precisa de:

Um coding agent compatível — Claude Code, Codex CLI ou Google Antigravity instalado e funcionando
Conta Google Cloud — com um projeto ativo e billing habilitado (para deploy)
gcloud CLI configurado — autenticado e com projeto default setado

# Verificar se gcloud está configurado
gcloud auth list
gcloud config get-value project

Se o gcloud não estiver configurado, rode:

gcloud auth login
gcloud config set project SEU_PROJETO_ID

Passo 1: Instalação

A instalação é diferente para cada coding agent, mas igualmente simples.

Claude Code

# Instalar o Agents CLI como extensão no Claude Code
claude code --install-skill agents-cli

# Ou via configuração manual
echo '{"skills": ["google/agents-cli"]}' >> ~/.claude/skills.json

Codex CLI

# Instalar via plugin system do Codex
codex plugin install @google/agents-cli

# Verificar instalação
codex plugin list

Google Antigravity

# Integração nativa — basta atualizar
antigravity update

# O Agents CLI já vem incluído nas versões recentes
antigravity skills list

Após a instalação, seu coding agent ganha 7 skills novas automaticamente. Você pode verificar pedindo ao agent:

"Liste as skills do Agents CLI disponíveis"

O agent vai responder com: scaffold, evaluate, deploy, monitor, register, secure e iterate.

Passo 2: Scaffold de um Novo Agente

Aqui é onde a mágica começa. Ao invés de criar manualmente a estrutura de projeto, você descreve o que quer.

No seu coding agent, diga:

"Crie um agente de atendimento ao cliente com ADK. 
Ele deve responder perguntas sobre pedidos, processar devoluções 
e escalar para humanos quando necessário."

O Agents CLI (via skill scaffold) vai gerar:

customer-support-agent/
├── agent.py              ← Lógica principal do agente
├── tools/
│   ├── order_lookup.py   ← Tool para consultar pedidos
│   ├── return_process.py ← Tool para processar devoluções
│   └── escalation.py    ← Tool para escalar para humano
├── prompts/
│   └── system.txt       ← System prompt otimizado
├── config/
│   ├── agent.yaml       ← Configuração ADK
│   └── deploy.yaml      ← Configuração de deploy
├── eval/
│   ├── test_cases.json  ← Casos de teste iniciais
│   └── eval_config.yaml ← Configuração dos AutoRaters
├── requirements.txt
└── README.md

Não é um template genérico. O scaffold é contextualizado pela descrição que você deu. As tools já têm a estrutura correta, o system prompt já menciona os casos de uso, e os test cases já cobrem os cenários descritos.

Você pode iterar imediatamente:

"Adicione uma tool para consultar status de entrega via API dos Correios"

E o coding agent atualiza o projeto mantendo a coerência.

Passo 3: Evaluate com AutoRaters

Antes de colocar em produção, você precisa avaliar se o agente funciona bem. O Agents CLI integra os AutoRaters — os mesmos sistemas de avaliação usados internamente pelo Google e DeepMind.

Peça ao coding agent:

"Avalie o agente de atendimento ao cliente. 
Rode os AutoRaters contra os casos de teste."

O ciclo de avaliação segue 5 etapas:

1. Prepare Data

O Agents CLI prepara os dados de teste. Se você não tem casos prontos, ele gera automaticamente baseado na descrição do agente:

"Gere 20 casos de teste para o agente, cobrindo 
happy paths e edge cases"

2. Inference

Roda o agente contra cada caso de teste e captura as respostas completas (incluindo chain-of-thought, tool calls e outputs).

3. Grade

Os AutoRaters avaliam cada resposta em múltiplas dimensões:

Correção factual — a resposta está certa?
Aderência à instrução — seguiu o system prompt?
Qualidade da tool use — usou as tools certas, na ordem certa?
Safety — não gerou conteúdo problemático?
Tone — manteve o tom esperado?

4. Analyze

Agrega os resultados e identifica padrões de falha:

📊 Resultados da Avaliação:
- Correção: 92% (18/20 cases passed)
- Tool Use: 85% (17/20 correct tool selection)
- Safety: 100% (0 violations)
- Tone: 95% (19/20 on-brand)

⚠️  Falhas concentradas em:
- Casos de devolução com múltiplos itens (2 falhas)
- Consulta de pedido com ID inválido (1 falha)

5. Optimize

Com base nas falhas identificadas, o coding agent sugere (e implementa) melhorias:

"Otimize o agente para lidar melhor com devoluções 
de múltiplos itens"

O Agents CLI ajusta o system prompt, melhora a tool de devoluções e re-roda a avaliação para confirmar a melhoria.

Passo 4: Deploy para Agent Runtime

Chegou a hora de ir para produção. O deploy com Agents CLI é um comando — mas um comando inteligente.

Peça ao coding agent:

"Faça deploy do agente de atendimento para produção"

Dry Run primeiro (sempre)

O Agents CLI sempre faz um dry run antes do deploy real:

🔍 Dry Run — Deploy Preview:

Target: Agent Runtime (us-central1)
Project: meu-projeto-gcp
Agent: customer-support-agent v1.0.0

Resources que serão criados:
- Cloud Run service: customer-support-agent
- Cloud Trace: auto-configured
- Cloud Logging: auto-configured
- BigQuery dataset: agent_analytics
- Agent Registry entry: customer-support-agent

Estimated cost: ~$0.03/1000 requests (compute only)

Proceed with deploy? [waiting for confirmation]

Só depois da sua confirmação o deploy acontece:

"Sim, pode deployar"

O que acontece no deploy

O Agents CLI não apenas faz deploy do código. Ele configura automaticamente:

Cloud Trace — tracing distribuído para cada request ao agente
Cloud Logging — logs estruturados com contexto de sessão
BigQuery Agent Analytics — dataset para métricas de uso e performance
Agent Registry — registro do agente para discovery por outros serviços

✅ Deploy concluído!

Endpoint: https://customer-support-agent-xyz.run.app
Registry: projects/meu-projeto/agents/customer-support-agent
Dashboard: https://console.cloud.google.com/agent-analytics/...

Observabilidade ativa:
- Trace: ✅ 
- Logging: ✅
- Analytics: ✅

Passo 5: Monitor em Produção

Com o agente em produção, o Agents CLI mantém a observabilidade ativa por padrão.

Observabilidade automática

Você não precisa configurar nada. No momento do deploy, o Agents CLI já conectou:

Cloud Trace — cada interação do agente gera um trace completo (latência por step, tool calls, LLM calls)
Cloud Logging — logs estruturados com session_id, user_id, intent_detected, tools_used
BigQuery Agent Analytics — tabela de eventos para análise custom

Consultar métricas via coding agent

"Como está o agente de atendimento nas últimas 24h?"

O coding agent consulta o BigQuery e responde:

📊 Customer Support Agent — Últimas 24h:

Requests: 1,847
Latência média: 2.3s (P99: 4.8s)
Taxa de sucesso: 96.2%
Escalações para humano: 12.4%
Tool errors: 0.8%

Top intents:
1. Consulta de pedido (43%)
2. Status de entrega (28%)
3. Devolução (18%)
4. Outros (11%)

Alertas e dashboards

O Agents CLI configura alertas básicos automaticamente:

Error rate > 5% — alerta imediato
Latência P99 > 10s — alerta de performance
Tool failure rate > 3% — alerta de integração

Você pode customizar pedindo ao coding agent:

"Adicione um alerta quando a taxa de escalação para humano 
passar de 20%"

Deep Dive: As 7 Skills do Agents CLI

O tutorial mostrou o fluxo ponta a ponta. Aqui vamos olhar cada skill individualmente — o que ela resolve, como pensa, e onde brilha (ou não).

1. scaffold — O ponto de partida

A scaffold traduz uma descrição em linguagem natural numa estrutura de projeto ADK completa. Não estamos falando de um mkdir glorificado: ela interpreta requisitos, cria tools coerentes com o que você descreveu, gera system prompt contextualizado, monta configuração de deploy e já entrega test cases iniciais para avaliação.

O detalhe que faz diferença: se você descreve "um agente de triagem que classifica tickets em P1/P2/P3", as tools geradas já têm a lógica de classificação, não apenas stubs vazios.

"Scaffold um agente de triagem de suporte técnico que classifica 
tickets em P1/P2/P3, extrai informações relevantes e roteia 
para o time correto"

Mesmo que você já tenha código parcial, a scaffold complementa o que falta sem sobrescrever o existente. Na prática, funciona como um par que monta a infraestrutura enquanto você foca na lógica de negócio.

2. evaluate — O gatekeeper antes do deploy

Ninguém deveria deployar um agente sem antes responder: "ele funciona?" A evaluate roda os AutoRaters do Google/DeepMind contra o agente — os mesmos sistemas usados internamente para avaliar modelos.

O ciclo é denso: gera ou usa test cases existentes, executa inference do agente contra cada caso, aplica AutoRaters multi-dimensionais (correção, safety, tone, tool use), produz relatório com métricas agregadas e identifica padrões de falha com sugestões de correção.

"Avalie o agente com foco em safety e correção factual. 
Use os 50 test cases do diretório eval/"

Uma observação prática: rode avaliações não só antes do deploy, mas depois de qualquer mudança significativa no prompt ou nas tools. O que parece uma alteração inofensiva às vezes quebra edge cases que estavam passando.

3. deploy — Um comando, toda a infra

A skill que mais encurta distância entre "funciona no meu laptop" e "funciona em produção". Ela valida o projeto (lint, type check, dependency check), faz dry run mostrando exatamente o que será criado, executa o deploy para Cloud Run via Agent Runtime e configura Cloud Trace, Cloud Logging e BigQuery automaticamente.

"Deploy o agente para produção em us-east1. 
Use a configuração de staging para dry run primeiro."

Dois detalhes importantes. Primeiro: ela chama register e secure internamente, então você não precisa lembrar de fazer essas etapas separadamente. Segundo: o dry run é obrigatório — não existe "deploy direto" sem preview.

4. monitor — Olhos no agente 24/7

Depois do deploy, monitor vira a skill do dia-a-dia. Ela configura dashboards no Cloud Monitoring, cria alertas baseados em thresholds, consulta BigQuery Agent Analytics sob demanda, gera relatórios de performance periódicos e identifica degradação de qualidade em produção.

"Mostre as métricas do agente na última semana. 
Destaque qualquer degradação vs semana anterior."

O uso mais valioso não é ver métricas bonitas — é pegar degradações silenciosas. Um agente pode manter 95% de sucesso geral e estar falhando em 40% de um intent específico. O monitor conectado ao BigQuery revela isso.

5. register — Tornando o agente descobrível

Agentes que existem isolados são úteis. Agentes que outros serviços podem descobrir e consumir são mais úteis. A register cria uma entrada no Agent Registry com metadata completo: capabilities, inputs/outputs, protocolos suportados, versionamento semântico e documentação de API gerada automaticamente.

"Registre o agente no Agent Registry com versão 1.2.0. 
Ele aceita requests JSON e retorna markdown."

Na prática, a skill deploy já chama register internamente. O uso manual faz sentido quando você precisa atualizar metadata sem redeployar — por exemplo, marcar uma versão como deprecated ou atualizar a descrição de capabilities.

6. secure — A camada que você não pode esquecer

Expor um agente para usuários externos sem segurança configurada é pedir problemas. A secure resolve isso: configura Agent Gateway como proxy de segurança, ativa Model Armor para filtrar inputs/outputs perigosos, configura mTLS para comunicação entre serviços, define rate limiting e quotas, aplica políticas de acesso (IAM) e audita conformidade.

"Configure segurança para o agente de atendimento. 
Rate limit de 100 req/min por usuário, 
Model Armor ativo para PII detection."

A skill deploy aplica segurança básica por padrão. A secure serve para ir além: quando seu agente lida com dados sensíveis, quando é exposto publicamente, ou quando compliance exige configurações específicas.

7. iterate — Melhoria contínua com evidência

A última skill fecha o ciclo. Em vez de melhorar o agente no escuro, iterate puxa logs de falhas recentes do Cloud Logging, agrupa por padrão (mesmo tipo de input, mesma tool, mesmo intent), propõe correções específicas, implementa no código, re-avalia com AutoRaters e faz deploy da versão corrigida.

"O agente está falhando em perguntas sobre política de 
cancelamento. Itere para melhorar."

É a diferença entre "acho que o agente precisa de ajuste" e "o agente falhou 12 vezes neste pattern, aqui está a correção testada". Use quando o monitor apontar degradação, ou como prática regular — toda sexta-feira, por exemplo.

Como Funciona Por Baixo

O Agents CLI não é mágico — é bem arquitetado.

Quando você instala o Agents CLI no seu coding agent, ele injeta instruções estruturadas que o agent passa a entender. Cada skill é um conjunto de:

Trigger patterns — quando ativar a skill (ex: "deploy", "avalie", "scaffolde")
Procedure — sequência de comandos gcloud/adk para executar
Validation — checks de pré e pós-execução
Error handling — o que fazer quando algo falha

Quando você pede "deploy meu agente", o coding agent:

Reconhece o trigger → skill deploy
Lê o procedimento da skill
Executa os comandos gcloud/adk no terminal
Valida o resultado
Reporta sucesso ou falha com contexto

A tradução é transparente. Se quiser ver exatamente o que está acontecendo:

"Mostre os comandos que o deploy vai executar antes de rodar"

E o coding agent lista:

# Comandos que serão executados pela skill deploy:
gcloud run deploy customer-support-agent \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="AGENT_VERSION=1.0.0"

gcloud agent-platform register \
  --agent-id customer-support-agent \
  --version 1.0.0 \
  --capabilities "text-generation,tool-use"

bq mk --dataset agent_analytics

gcloud logging sinks create agent-logs \
  bigquery.googleapis.com/projects/meu-projeto/datasets/agent_analytics

Nenhuma caixa preta.

Avaliação: Spider Chart

Avaliamos o Agents CLI em 8 eixos relevantes para uma CLI de desenvolvimento de agentes:

Eixo	Score	Justificativa
Facilidade de Início	9/10	Instala em 1 minuto, zero config adicional necessária
Integração com Coding Agents	10/10	Funciona em Claude Code, Codex e Antigravity nativamente
Produção/Deploy	9/10	One-command deploy com observabilidade auto-configurada
Avaliação/Testing	9/10	AutoRaters de nível Google/DeepMind integrados
Governança	8/10	Agent Gateway + Model Armor configurados automaticamente
Documentação	7/10	Recém-lançado, documentação em crescimento ativo
Flexibilidade	7/10	Focado em GCP/ADK — não é genérico multi-cloud
Comunidade	6/10	Projeto novo, comunidade ainda em formação

Score Geral: 8.1/10

O Agents CLI acerta onde importa: a experiência de desenvolvimento. O fluxo "descreva → scaffold → evaluate → deploy → monitor" é o mais fluido que existe hoje para agentes ADK.

Os pontos fracos — documentação e comunidade — são temporais. O projeto é novo. A limitação de flexibilidade (GCP-only) é arquitetural e provavelmente permanente, mas se você já está no ecossistema Google, isso não é um problema; é coerência.

Prós e Contras

✅ Prós

Zero context-switch — Tudo acontece no seu editor. Sem console do GCP, sem navegar documentação, sem copiar comandos. O coding agent é a interface para tudo.

Lifecycle completo em 7 skills — Do scaffold ao monitor, passando por evaluate, deploy, register, secure e iterate. Cada etapa crítica do desenvolvimento de agentes tem uma skill dedicada.

AutoRaters sem custo adicional — Os mesmos sistemas de avaliação usados internamente pelo Google e DeepMind, de graça. Honestamente, isso sozinho já justifica instalar o Agents CLI — a alternativa é construir sua própria pipeline de avaliação do zero.

Agnóstico de coding agent — Claude Code, Codex, Antigravity — funciona em todos. Você não fica preso a um editor.

Observabilidade que vem de fábrica — Cloud Trace, Cloud Logging e BigQuery Agent Analytics configurados no deploy. Quantos projetos seus estão em produção sem observabilidade porque "ia configurar depois"?

Dry run obrigatório — Toda operação destrutiva mostra preview antes de executar. Parece óbvio, mas a quantidade de CLIs que não fazem isso é impressionante.

Open-source — Código aberto, sem licença proprietária, sem vendor lock na ferramenta em si.

❌ Contras

GCP only. Ponto. — Se você usa AWS ou Azure, o Agents CLI não vai te ajudar diretamente. Não existe plano anunciado para suportar AWS Bedrock Agents, Azure AI Agent Service ou outras plataformas.

Projeto novo, arestas esperadas — Como todo lançamento recente, prepare-se para bugs ocasionais, breaking changes e gaps de funcionalidade. Nada que impeça o uso, mas calibre expectativas.

Documentação rasa em cenários avançados — O básico está coberto. Cenários de edge case, configurações não-standard, debugging complexo? Você vai ter que experimentar. A comunidade ainda não produziu volume significativo de conteúdo auxiliar.

Exige gcloud configurado — Se sua máquina de dev não tem gcloud setup, é um pré-requisito antes de qualquer skill funcionar. Não é complexo, mas pode travar quem está testando rápido.

Veredicto

Para quem já usa GCP + ADK: instale hoje. A redução de fricção é grande. O que antes levava horas de configuração manual agora acontece em minutos, conversando com seu coding agent.

Para quem usa outro cloud: vale estudar o modelo. A ideia de CLI que injeta skills em coding agents é poderosa independente do vendor. O padrão vai se espalhar.

Quando Usar o Agents CLI

✅ Use quando:

Você já usa Google Cloud como cloud principal
Quer deploy rápido de agentes ADK sem configuração manual
Sua equipe usa coding agents (Claude Code, Codex, Antigravity) no dia-a-dia
Precisa de avaliação rigorosa com AutoRaters antes de ir para produção
Quer observabilidade sem configurar manualmente Trace/Logging/Analytics
Está começando com ADK e quer o caminho mais rápido do zero ao deploy
Tem múltiplos agentes e quer padronizar o fluxo de desenvolvimento

❌ NÃO use quando:

Sua stack é AWS ou Azure — o Agents CLI não suporta outros clouds
Seus agentes não são ADK — se usa LangChain, CrewAI, AutoGen puro, o Agents CLI não é o tool certo
Precisa de multi-cloud — deployar o mesmo agente em GCP + AWS não é suportado
Não usa coding agents — se você prefere operar CLIs diretamente, use o gcloud + adk CLI padrão
Quer controle granular sobre cada flag de deploy — o Agents CLI abstrai muita coisa, o que pode incomodar quem quer controlar tudo manualmente

Próximos Passos

Se o Agents CLI te interessou, esses conteúdos complementam:

Guia Definitivo do Google ADK — entenda o framework por baixo do Agents CLI
Ciclo Build-Scale-Govern-Optimize — a filosofia do Agent Platform que o Agents CLI implementa
Documentação oficial do Agents CLI — referência técnica completa

Experimente hoje

O caminho mais rápido:

# 1. Instale no seu coding agent (exemplo: Claude Code)
claude code --install-skill agents-cli

# 2. Peça para scaffoldar um agente simples
# "Crie um agente que responde perguntas sobre meu produto"

# 3. Avalie
# "Rode os AutoRaters contra o agente"

# 4. Se passou, deploy
# "Deploy para produção"

Em menos de 30 minutos você vai do zero ao agente em produção com observabilidade completa. Sem exagero — o gargalo é decidir o que o agente faz, não configurar infra.

Quer acompanhar as novidades do ecossistema de agentes AI? Acesse ft.ia.br para análises, guias e tutoriais sobre as ferramentas que estão moldando o futuro do desenvolvimento de software.

Google ADK: Guia Definitivo para Agentes Multi-Linguagem

Sat, 18 Jul 2026 00:00:00 GMT

TL;DR — O Google ADK é um framework open-source (Apache 2.0) para construir, debugar e deployar agentes de IA. Funciona em cinco linguagens (Python, TypeScript, Go, Java, Kotlin), integra nativamente com Vertex AI, suporta MCP e o protocolo A2A para comunicação entre agentes, e vem com uma UI de debugging embutida. Se você já opera dentro do ecossistema Google Cloud, o ADK elimina semanas de boilerplate. Se não opera — continue lendo mesmo assim, porque a arquitetura vale o estudo.

Overview: O que é o Google ADK e por que ele existe

O Google entrou na corrida dos agent frameworks em 2025 com o Agent Development Kit. Enquanto CrewAI (2023) e LangGraph (2024) já disputavam atenção, o ADK chegou com uma proposta diferente: não ser apenas mais uma lib Python, mas um framework multi-linguagem com runtime de produção integrado ao Google Cloud.

Em maio de 2026, o ADK Python 2.0 alcançou General Availability. Hoje o framework acumula mais de sete milhões de downloads e conta com repositórios oficiais em Python, TypeScript, Go, Java e Kotlin. A Google usa internamente o mesmo framework para construir os agentes dentro do Agentspace e do Customer Engagement Suite — não é um side project jogado no GitHub para ganhar stars.

O pitch oficial, direto do site: "Build production agents, not prototypes." E honestamente? A arquitetura entrega o que promete.

A LangChain resume bem: "Choose Google ADK if you're GCP-native and want an opinionated, batteries-included agent runtime with built-in debugging UIs." Essa frase captura a essência — opinionated, batteries-included, debugging nativo. Se você já navega o ecossistema Google, o ADK não é uma escolha; é quase uma consequência natural.

Tutorial: Seu primeiro agente ADK em 10 minutos

Chega de contexto. Vamos colocar um agente pra rodar.

Pré-requisitos

Python 3.9+ (para o exemplo; funciona igual em Java 17+, Go 1.21+, Node 18+)
Uma API key do Gemini (pegue em ai.google.dev)
Terminal com acesso à internet

Passo 1: Instalação

# Recomendo usar um virtual environment
python -m venv .venv && source .venv/bin/activate

# Instalar o ADK
pip install google-adk

Para as outras linguagens:

# TypeScript/Node
npm install @google/adk

# Go
go get google.golang.org/adk

# Java — adicione ao pom.xml
# <dependency>
#   <groupId>com.google.adk</groupId>
#   <artifactId>google-adk</artifactId>
# </dependency>

Passo 2: Criar o projeto

O ADK vem com CLI própria. Crie a estrutura do projeto:

adk create my_agent
cd my_agent

Isso gera a seguinte árvore:

my_agent/
├── __init__.py
├── agent.py
└── .env

Passo 3: Definir o agente

Abra agent.py e substitua pelo seguinte:

from google.adk import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name="pesquisador",
    model="gemini-2.0-flash",
    instruction="""Você é um assistente de pesquisa técnica.
    Quando o usuário perguntar sobre um tópico, use o Google Search
    para encontrar informações atualizadas e sintetize em português.""",
    tools=[google_search],
)

Repare: nome, modelo, instrução, ferramentas. Quatro campos. Sem YAML de 200 linhas, sem chains encadeados, sem abstrações sobre abstrações. O ADK abraça a filosofia code-first — seu agente é código Python normal.

Passo 4: Configurar a API key

echo "GOOGLE_API_KEY=sua-chave-aqui" > .env

Passo 5: Rodar

Duas opções:

# CLI interativa (terminal)
adk run my_agent

# Web UI com debugging visual
adk web my_agent

A segunda opção abre um browser em localhost:8000 com a interface de desenvolvimento — traces, eventos, estado da sessão, tudo visível em tempo real.

Pronto. Seu agente está rodando, fazendo buscas e sintetizando respostas. Dez minutos, talvez menos.

Deep Dive: Anatomia do ADK

Agora que você tem um agente funcionando, vamos destrinchar o que acontece por baixo do capô.

Agents: Três sabores de inteligência

O ADK não trata "agente" como sinônimo de "wrapper em volta de um LLM". São três tipos distintos:

LLM Agents — Os mais comuns. Recebem um modelo, instrução e ferramentas. Raciocinam, planejam, decidem qual tool chamar. Seu pesquisador do tutorial é um desses.

Workflow Agents — Determinísticos. Não usam LLM para decidir o fluxo, mas sim lógica de código. O ADK 2.0 trouxe graph-based workflows: você compõe nós de execução (agentes ou funções puras) em um grafo dirigido com branching explícito. Pense em um DAG, mas com a possibilidade de inserir raciocínio AI em nós específicos.

Custom Agents — Herdam de BaseAgent e implementam lógica de orquestração arbitrária. Quando nem o grafo nem o agente simples resolvem seu caso, você desce um nível.

Essa separação é inteligente. Nem todo problema precisa de um LLM decidindo próximos passos — às vezes você quer fluxo previsível com bolsos de inteligência. O ADK torna isso natural.

Tools: A mão do agente no mundo real

Um agente sem ferramentas é um chatbot caro. O ADK oferece três categorias:

Function Tools — Funções Python decoradas que o agente pode chamar. Você escreve a função, documenta o que ela faz, e o LLM decide quando usá-la:

from google.adk.tools import tool

@tool
def consultar_estoque(produto_id: str) -> dict:
    """Consulta o estoque atual de um produto pelo ID."""
    # Sua lógica aqui
    return {"produto_id": produto_id, "quantidade": 42}

MCP Tools — O ADK é um MCP client nativo. Conecte qualquer MCP server e seus tools ficam disponíveis automaticamente para o agente. Sem adapter code, sem wrappers manuais. E o inverso também funciona: você pode expor tools ADK como um MCP server. A interoperabilidade é bidirecional.

OpenAPI Tools — Aponte para um spec OpenAPI e o ADK auto-gera tools a partir dos endpoints. Integração com APIs legadas sem escrever uma linha de código de integração.

Quer saber mais sobre MCP e ferramentas para agentes? Confira nosso guia sobre ferramentas, tools e MCP servers.

Sessions e Memory: Contexto como código

O ADK trata contexto como algo estruturado, não como concatenação bruta de strings até o context window estourar. A arquitetura separa:

Sessions — Conversas individuais com ID único, isoladas por usuário e aplicação. Cada sessão mantém estado (key-value) acessível por qualquer agente no pipeline. O ADK 2.0 trouxe rewind: você pode rebobinar uma sessão para antes de uma invocação anterior.
State — Dicionário compartilhado dentro da sessão. Agentes leem e escrevem livremente. É o "barramento de dados" entre sub-agents num pipeline sequencial.
Events — Cada ação (mensagem do usuário, resposta do agente, chamada de tool) vira um evento imutável na sessão. O log completo de execução fica disponível para debugging e auditoria.
Memory — Memória de longo prazo, cross-session. O agente lembra informações de interações passadas sem você precisar reimplementar RAG do zero.

A mágica está na forma como o framework filtra automaticamente eventos irrelevantes, sumariza conversas antigas, e faz lazy-load de artefatos pesados. Você não pensa em token budget — o ADK pensa por você.

A2A Protocol: Agentes que falam entre si

Aqui as coisas ficam interessantes de verdade. O Agent-to-Agent (A2A) é um protocolo aberto que o Google desenvolveu para comunicação entre agentes — independente de linguagem, framework ou infraestrutura.

Pense no A2A como o HTTP do mundo agêntico. Três conceitos centrais:

Agent Cards — JSON servido em /.well-known/agent.json que descreve as capacidades do agente (nome, skills, formatos de I/O). Qualquer agente pode fazer discovery de outro.
JSON-RPC 2.0 — Protocolo de comunicação. Um agente manda message/send com dados estruturados, o outro responde. Simples como uma API REST, porém com semântica agêntica.
Task Lifecycle — Cada interação é um Task com estados bem definidos: submitted → working → completed/failed. Funciona para chamadas síncronas e assíncronas.

Na prática, isso significa que seu agente Python pode chamar um agente Go como se fosse um sub-agent local:

from google.adk.agents import SequentialAgent
from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

# Agente Go remoto, exposto via A2A
compliance_agent = RemoteA2aAgent(
    name="compliance_validator",
    agent_card="http://go-agent:8888/.well-known/agent.json",
    description="Valida contratos contra políticas corporativas."
)

# Pipeline: extrai → valida → reporta
pipeline = SequentialAgent(
    name="contract_pipeline",
    sub_agents=[extractor_agent, compliance_agent, report_agent],
)

O RemoteA2aAgent abstrai completamente a comunicação de rede. Você não escreve HTTP client, não serializa JSON-RPC, não lida com retry manual. O ADK cuida disso.

Para entender como esse padrão de orquestração se encaixa em arquiteturas maiores, leia sobre harness e loop — arquitetura de agentes.

MCP Integration: Ferramentas sem fronteiras

O Model Context Protocol já se tornou o padrão de facto para exposição de ferramentas a agentes. O ADK trata MCP como cidadão de primeira classe:

Como client: Configure um MCP server e todos os tools dele ficam disponíveis para seu agente automaticamente. O ADK faz discovery dos tools, registra schemas, e o LLM sabe chamá-los.

Como server: Exponha os tools do seu agente ADK como um MCP server. Outros frameworks (LangChain, CrewAI, qualquer MCP client) podem consumir seus tools sem saber que são ADK por baixo.

Essa bidirecionalidade é um diferencial real. Você não fica preso num ecossistema fechado. Construiu um tool no ADK? Qualquer framework MCP-compatible pode usá-lo. Encontrou um MCP server útil? Plug direto no seu agente.

Debugging UI: Visibilidade total, de graça

Vou ser direto: a UI de debugging do ADK é provavelmente o maior diferencial prático em relação a outros frameworks. Enquanto a maioria te dá print() e reza, o ADK vem com:

Trace viewer — Visualização de cada passo da execução: qual tool foi chamado, com quais parâmetros, o que retornou, quanto tempo levou.
Event inspector — Stream de todos os eventos da sessão em tempo real.
State viewer — Estado atual da sessão, atualizado a cada interação.
Visual Builder — Interface drag-and-drop para prototipagem rápida de agentes (novo no ADK Web).
Evaluation dashboard — Rode testes automatizados contra seu agente e veja métricas de qualidade.

Execute adk web e tudo isso aparece no browser. Zero configuração. Compare com a experiência de debugar um agente LangChain onde você precisa configurar LangSmith, criar conta, gerenciar API keys separadas, e torcer para o trace capturar o que você precisa. No ADK, é built-in.

A Infoworld capturou bem: "The ADK includes a command-line interface and a developer UI for running agents, inspecting execution steps (events, state changes), debugging interactions, and visualizing agent definitions."

Multi-Agent Workflows: Orquestração real

O ADK 2.0 trouxe quatro padrões de orquestração multi-agente:

Sequential — Agentes executam em ordem fixa. Output de um alimenta o próximo via state compartilhado.
Parallel — Agentes rodam simultaneamente. Útil para buscar informações de múltiplas fontes ao mesmo tempo.
Loop — Execução iterativa até uma condição ser satisfeita. Refinamento progressivo.
Collaborative — Um coordenador delega dinamicamente para sub-agentes baseado no contexto. O mais flexível e o mais complexo.
Graph-based (ADK 2.0) — Composição explícita de nós e edges com decision branching. Combina nós determinísticos com nós de raciocínio AI.

A opção de graph-based workflows é particularmente poderosa. Você ganha a previsibilidade de um DAG com a flexibilidade de inserir LLMs onde faz sentido. Nem tudo precisa ser "autônomo" — às vezes você quer que o agente seja inteligente no nó 3, mas previsível nos nós 1, 2, 4 e 5.

Gemini Enterprise Agent Platform: O ADK em Produção

Em 17 de julho de 2026, o Google Cloud apresentou 13 demos ao vivo que reposicionaram o ADK. O framework deixou de ser "só" uma ferramenta de desenvolvimento — virou o pilar Build de uma plataforma maior: a Gemini Enterprise Agent Platform.

O Google rebrandeou toda a superfície do Vertex AI voltada para agentes em uma plataforma unificada com quatro pilares: Build (ADK), Scale (Agent Runtime + Gateway), Govern (Registry + Model Armor), e Optimize (AutoRaters + observabilidade). Cada pilar é um produto em si, mas juntos cobrem o pipeline completo: do código no seu editor até o agente rodando em produção com governança enterprise.

Vou destrinchar cada peça. O conjunto é ambicioso — resta ver quanto disso já funciona bem fora de demos controladas.

Agent Runtime: Deploy sem pensar em infra

O antigo Agent Engine do Vertex AI evoluiu. Agora se chama Agent Runtime e a proposta é direta: você faz deploy do seu agente ADK e o Runtime cuida de infraestrutura, auto-scaling, session management, health checks e failover.

# Deploy direto do editor para o Agent Runtime
agents deploy --runtime managed --region us-central1

# O Runtime gerencia:
# - Scaling automático baseado em load
# - Session persistence cross-pod
# - Health monitoring + auto-restart
# - Memory Bank para contexto de longo prazo

A integração com Memory Bank é o que mais muda a experiência prática. Antes, persistir memória cross-session exigia configurar seu próprio backend (Firestore, Redis, PostgreSQL). Agora o Agent Runtime oferece Memory Bank como serviço nativo — seu agente lembra de interações passadas e mantém contexto entre sessões sem código extra de sua parte.

Para quem vem de arquiteturas serverless: pense no Agent Runtime como o Cloud Run dos agentes. Você entrega o container (ou nem isso — o Runtime builda a partir do código ADK), e ele lida com o resto. A diferença é que o Runtime entende semântica de agentes. Ele sabe o que é uma session, entende checkpoints, gerencia state de forma inteligente. Não é um container runner genérico — é um agent-native runtime.

Na prática, isso resolve a complexidade operacional de manter agentes stateful em produção. Session affinity, graceful shutdown sem perder contexto, scaling sem corromper estado — são problemas reais que quem já tentou deploy manual conhece bem. O Agent Runtime absorve essa camada.

Um ponto de atenção: quanto mais você delega para o managed runtime, mais dependente fica do GCP. Se portabilidade entre clouds é requisito, vale pesar isso antes de abraçar o Memory Bank nativo.

Agent Gateway: Segurança enterprise

Se o Runtime é o "como rodar", o Agent Gateway é o "quem pode rodar o quê".

Cada agente deployado recebe uma identidade única — não uma API key genérica, mas identidade criptográfica com mTLS end-to-end. Agente A falando com Agente B tem comunicação autenticada e encriptada nos dois lados, sem certificados manuais.

O Gateway empilha três camadas de proteção:

IAP Authentication — Identity-Aware Proxy na frente de cada agente. Usuários e serviços provam identidade antes de tocar no agente.
IAM Authorization — Políticas granulares: "Este agente pode chamar aquele tool." "Este usuário pode invocar este agente, mas não aquele." O mesmo RBAC do GCP, aplicado a agentes.
Model Armor — Inspeciona todo conteúdo que entra e sai do agente em tempo real. Detecta prompt injection, data leakage, tentativas de jailbreak, e informação sensível vazando nas respostas. Funciona como um WAF, mas para agentes.

# Configuração de segurança no deploy
# O Agent Gateway aplica automaticamente:
# - mTLS entre todos os agentes no mesh
# - IAP auth para chamadas externas
# - Model Armor scanning em requests/responses
# - Audit logging completo via Cloud Audit Logs

Para setores regulamentados (saúde, finanças, governo), o Agent Gateway endereça o argumento mais comum do time de segurança: "como garantimos governança?". Não é mais "confia no prompt engineering" — é audit trail completo com políticas declarativas.

Agent Registry: Discovery de agentes

Cenário real: 50 agentes deployados por 10 times na mesma organização. Como um agente novo descobre quais existentes pode chamar? Como evitar duplicação?

O Agent Registry resolve com auto-registro. Quando você faz deploy via Agents CLI, o agente aparece no Registry com seu Agent Card (do protocolo A2A). Outros agentes fazem discovery, verificam capabilities e estabelecem comunicação — programaticamente.

A analogia mais precisa: é o DNS dos agentes. Você não hardcoda URLs. Pergunta ao Registry "quem sabe fazer compliance check?" e ele retorna agentes registrados com essa capability, ranqueados por relevância e autorização.

Para organizações grandes, isso destranca composição entre times. Cada time constrói agentes especializados, registra no Registry, e o resto da organização pode montar pipelines usando esses agentes como blocos — sem reunião de alinhamento, sem wiki de integrações.

A ressalva honesta: discovery automático funciona bem quando Agent Cards são bem escritos. Se a descrição do agente for vaga ("faz coisas de compliance"), o Registry devolve resultados igualmente vagos. A qualidade do catálogo depende de disciplina dos times que publicam.

AutoRaters: Avaliação de qualidade com o DeepMind

AutoRaters é um sistema de avaliação desenvolvido em parceria com o DeepMind. A diferença fundamental de abordagens como "pedir pro LLM avaliar a própria resposta": são modelos especializados, treinados especificamente para avaliar outputs de agentes.

O ciclo opera em flywheel de 5 estágios:

┌─────────────────────────────────────────────────────────────┐
│                    AutoRaters Flywheel                        │
│                                                              │
│  1. Prepare Data                                             │
│     └── OTel traces + casos manuais + cenários sintetizados  │
│                          ↓                                   │
│  2. Run Inference                                            │
│     └── Executar o agente contra o dataset                   │
│                          ↓                                   │
│  3. Grade com AutoRaters                                     │
│     └── Modelos especializados avaliam qualidade             │
│                          ↓                                   │
│  4. Analyze Failure Clusters                                 │
│     └── Agrupar falhas por padrão, identificar root causes   │
│                          ↓                                   │
│  5. Targeted Optimizations                                   │
│     └── Prompt tuning, tool refinement, guardrails           │
│                                                              │
│  ↺ Repetir continuamente                                     │
└─────────────────────────────────────────────────────────────┘

O que diferencia dos frameworks de eval tradicionais (RAGAS, DeepEval): os AutoRaters não são um Gemini genérico com prompt de "avalie esta resposta de 1 a 10". São modelos calibrados para detectar alucinações, avaliar fidelidade factual, medir relevância contextual e verificar aderência a instruções.

O input também é mais robusto — o sistema puxa traces reais de produção (via OpenTelemetry), combina com casos de teste manuais curados por humanos, e gera cenários adversariais sintetizados. Avaliação tridimensional: produção real + golden set + stress test.

Quem já tentou medir objetivamente se um agente "está bom" sabe a dor. AutoRaters atacam esse problema de forma estruturada. Não é perfeito — nenhum sistema de eval automático é — mas a abordagem de modelos especializados por dimensão de qualidade é mais confiável do que general-purpose LLM-as-judge.

A2UI: Agentes que renderizam interfaces

A2UI (Agent-to-UI) permite que o agente renderize componentes de interface reais durante a conversa. Não markdown com tabela — componentes interativos: layouts responsivos, charts dinâmicos, menus clicáveis, formulários com validação.

O agente decide, no contexto da conversa, que a melhor forma de apresentar a informação é visual. Renderiza o componente. O usuário interage, e essa interação volta como input para o agente.

Exemplo concreto: um agente de analytics que, em vez de despejar números em texto, renderiza um dashboard com filtros interativos. Ou um agente de reservas que mostra um calendário visual com disponibilidades clicáveis. A2UI dissolve a fronteira entre "chatbot de texto" e "aplicação visual".

A ideia é ousada: a interface não é desenhada a priori, mas gerada pelo agente baseada no contexto da interação. O frontend vira um canvas dinâmico.

Dito isso — isso foi demonstrado em condições de demo. Quão bem esses componentes renderizados se comportam em cenários reais (acessibilidade, responsividade em devices variados, consistência visual com o design system da empresa) ainda precisa de validação em produção. O conceito é poderoso; a maturidade do output é a incógnita.

Agents CLI: Seu editor como command center

O Agents CLI é a ponte entre o ambiente local e a Gemini Enterprise Agent Platform. Instala como extensão em qualquer coding agent — Claude Code, Codex, Antigravity — e entrega 7 operações diretamente no editor:

Scaffold — Criar novos agentes com templates e boilerplate configurado
Deploy — Push direto para Agent Runtime com configuração declarativa
Evaluate — Rodar AutoRaters localmente antes de deployar
Monitor — Ver logs, traces e métricas do agente em produção
Discover — Buscar agentes no Registry por capability
Connect — Configurar comunicação A2A entre agentes
Secure — Aplicar políticas de Model Armor e Gateway

# Instalação do Agents CLI
pip install agents-cli

# Scaffold um novo agente
agents new meu-agente --template multi-tool --runtime managed

# Deploy para produção
agents deploy --env production --region us-central1

# Avaliar qualidade antes do deploy
agents evaluate --dataset tests/golden_set.yaml --autorater quality-v2

# Monitorar em tempo real
agents monitor meu-agente --tail --metrics latency,quality

O valor prático: antes, você alternava entre terminal, console GCP, dashboards de monitoramento. Com o Agents CLI, o ciclo inteiro acontece de dentro do editor. Mesma filosofia do kubectl para Kubernetes — uma CLI que é sua interface primária com a plataforma.

Temos um guia dedicado cobrindo tudo: Guia Definitivo: Agents CLI.

Padrão Long-running: Agentes que não perdem o fio

Contribuição menos vistosa, mas talvez a mais relevante para produção real: suporte nativo a agentes long-running. Agentes que pausam, esperam (horas, dias, semanas), retomam, e mantêm contexto intacto.

Três padrões foram demonstrados:

1. Durable State Machines — O agente opera como uma state machine com estados persistidos. Cada transição é atômica e durável. Se o runtime reiniciar, o agente retoma do estado exato onde parou.

from google.adk import Agent
from google.adk.patterns import DurableStateMachine

onboarding_agent = Agent(
    name="customer_onboarding",
    model="gemini-2.0-flash",
    pattern=DurableStateMachine(
        states=["collecting_info", "awaiting_approval", "provisioning", "done"],
        initial="collecting_info",
        # Cada transição é persistida automaticamente
        # O agente pode ficar dias em "awaiting_approval"
    ),
)

2. Event-driven Idle Time — O agente hiberna até receber um evento externo. Não consome recursos enquanto aguarda. Um webhook, um email, uma aprovação manual — qualquer evento acorda o agente e ele continua de onde parou.

3. Checkpoint-and-Resume com Persistent Sessions — Para workflows complexos com progresso incremental, checkpointing automático garante que nenhum trabalho é perdido. Mesmo que o processo caia, o último checkpoint é restaurado.

Esses padrões existem porque processos de negócio reais não são síncronos. Onboarding de cliente que leva 3 dias. Aprovação de contrato esperando assinatura do jurídico. Compliance review com input humano em etapas. Agentes que orquestram esses fluxos não podem ser stateless ou efêmeros — precisam ser duráveis.

O que isso significa na prática

A Gemini Enterprise Agent Platform leva o ADK de "framework para escrever código de agente" para "plataforma end-to-end para operar agentes em produção". A analogia mais próxima: ter o React (lib de UI) versus ter o Vercel (plataforma que roda, escala, monitora e otimiza seu app React).

Se antes a equação era ADK (código) + você (infra, segurança, monitoring, eval), agora é ADK (código) + Agent Platform (tudo o resto). A mensagem do Google é clara: "Foque no que seu agente FAZ. Nós cuidamos de como ele RODA."

Para quem acompanha o ecossistema de agent frameworks, esse é o movimento mais agressivo de um cloud provider até agora. A AWS com o Bedrock AgentCore e a Azure com o AI Foundry seguem a mesma direção, mas o Google chegou primeiro com o pacote mais integrado — e com a vantagem do ADK open-source como fundação.

O contraponto justo: plataforma integrada também significa acoplamento. Quanto mais você adota (Runtime, Gateway, Registry, AutoRaters), mais difícil fica migrar. O ADK em si é open-source e roda em qualquer lugar. Mas a plataforma ao redor dele é GCP puro. Essa distinção importa na hora de decidir quanto do stack você abraça.

Spider Chart: ADK em 8 eixos

Como o ADK se posiciona em relação aos critérios que importam? Aqui vai minha avaliação (1-10):

           Facilidade de Início
                  8
                  │
    Debugging ────┼──── Multi-linguagem
        9         │         9
                  │
  Ecossistema ────┼──── Produção/Deploy
      8           │         9
                  │
   Flexibilidade──┼──── Documentação
        7         │         8
                  │
            Comunidade
                6

Eixo	Score	Justificativa
Facilidade de Início	8/10	CLI scaffolding + quickstarts excelentes. A curva sobe quando você precisa de multi-agent
Multi-linguagem	9/10	Python, TS, Go, Java, Kotlin — nenhum concorrente oferece isso
Produção/Deploy	9/10	Deploy com um comando para Vertex AI, Cloud Run ou GKE. Container em qualquer lugar
Documentação	8/10	Docs oficiais sólidas + codelabs no Google Developers. Poderia ter mais exemplos em Go/Java
Comunidade	6/10	9.2k stars, crescendo. Mas ainda não tem a massa crítica de LangChain
Flexibilidade	7/10	Model-agnostic na teoria, otimizado pra Gemini na prática. Funciona com Claude, Ollama, etc.
Ecossistema	8/10	MCP nativo, A2A, OpenAPI tools, integração com Vertex AI, Apigee Gateway
Debugging	9/10	UI embutida incomparável. Traces, events, state — tudo sem config adicional

Score geral: 8.0/10 — Framework enterprise-ready com a melhor experiência de debugging do mercado.

Prós e Contras

Prós

Multi-linguagem de verdade — Cinco linguagens com paridade de features. Times enterprise com stacks heterogêneos não precisam forçar Python em todo mundo.
Debugging UI embutida — Não é um add-on pago, não é um SaaS separado. Vem com o framework, funciona com adk web, e mostra tudo que importa.
A2A + MCP nativos — Os dois protocolos que estão definindo interoperabilidade entre agentes. O ADK suporta ambos como cidadãos de primeira classe.
Deploy one-click — adk deploy joga direto no Agent Runtime (ex-Vertex AI Agent Engine). Container em Cloud Run ou GKE com Dockerfile gerado.
Gemini Enterprise Agent Platform — Não é só um framework. É um ecossistema completo: Agent Runtime (infra), Agent Gateway (segurança), Agent Registry (discovery), AutoRaters (qualidade), A2UI (interfaces). Nenhum concorrente oferece esse nível de plataforma integrada.
Agents CLI — Uma CLI que instala em qualquer coding agent e te dá scaffold, deploy, evaluate, monitor, discover — tudo sem sair do editor. A ponte entre código local e produção enterprise.
Mesma ferramenta que o Google usa internamente — Não é um projeto experimental. O Agentspace e o Customer Engagement Suite rodam ADK.
Graph Workflows (ADK 2.0) — Combina fluxo determinístico com raciocínio AI. Padrão que faz sentido para produção onde previsibilidade importa.
Agentes Long-running nativos — Suporte built-in para agentes que pausam, esperam (dias/semanas), retomam e nunca perdem contexto. Essencial para processos de negócio reais.
Open-source Apache 2.0 — Sem lock-in na licença. Use, modifique, distribua.

Contras

Viés para Gemini — Model-agnostic no papel, mas a experiência com modelos Gemini é visivelmente melhor. Integração com Claude/OpenAI funciona, mas não é o happy path.
Comunidade ainda nascente — LangChain tem anos de vantagem em massa crítica, Stack Overflow answers, e blog posts. Encontrar ajuda para edge cases do ADK pode exigir mergulho no código-fonte.
Exemplos desbalanceados — Python domina o repositório de samples (~30 agentes). TypeScript, Go e Java têm significativamente menos exemplos.
Curva de aprendizado — O framework é extenso. Agents, workflows, graphs, sessions, memory, tools, callbacks, plugins, evaluation... A superfície é grande. Vai levar tempo até você se sentir fluente.
Vertex AI pricing — O framework é grátis, mas o runtime gerenciado cobra por uso. Dependendo do volume, pode pesar no budget.

Quando usar o Google ADK

✅ Use quando:

Seu time já opera no Google Cloud / Vertex AI
Você precisa de agentes em múltiplas linguagens (time Python + time Go, por exemplo)
Debugging e observabilidade são críticos (regulamentação, compliance, auditoria)
Você quer pipelines multi-agente com comunicação cross-language via A2A
Precisa de deploy managed com escala automática
Quer interoperabilidade com MCP servers existentes
Está construindo sistemas de agentes para enterprise, não protótipos de hackathon

❌ NÃO use quando:

Você quer um protótipo rápido e não se importa com produção — frameworks mais leves como CrewAI ou o Agents SDK da OpenAI vão te dar velocity maior no início
Seu time é 100% Python e não precisa de multi-linguagem — LangGraph pode ser suficiente com menos overhead
Você está fortemente investido em AWS ou Azure — os SDKs nativos (Bedrock AgentCore, Azure AI Foundry) terão integração mais profunda com seus serviços
Precisa rodar modelos locais como prioridade — O ADK funciona com Ollama/vLLM, mas não é o foco
Comunidade e ecossistema maduro são mais importantes que features — LangChain ainda ganha nesse quesito

Comparação rápida com alternativas

Cenário	Melhor opção
GCP-native, enterprise, multi-lang	Google ADK
AWS-native, agentes serverless	Amazon Bedrock AgentCore
Azure-native, copilots	Azure AI Foundry Agents
Python-only, máxima flexibilidade	LangGraph
Protótipo rápido, simplicidade	CrewAI ou OpenAI Agents SDK
Orquestração de coding agents	Ver nosso guia de agent frameworks vs coding agents

Próximos passos

Se este guia te convenceu a explorar o ADK, aqui vai um roadmap sugerido:

Rode o quickstart — 10 minutos, zero custo. pip install google-adk && adk create. Sinta a ergonomia.
Explore o ADK Crash Course — O Google publicou um codelab completo que vai do básico ao expert.
Instale o Agents CLI — pip install agents-cli e ganhe superpoderes de scaffold, deploy e evaluate direto do editor. Veja nosso Guia Definitivo: Agents CLI para o setup completo.
Construa um multi-agent pipeline — Pegue o exemplo de customer service no repositório google/adk-samples e adapte pro seu domínio. Isso vai te forçar a entender sessions, state, e tools de verdade.
Integre um MCP server — Pegue qualquer MCP server público e conecte ao seu agente. Vai te mostrar o poder da interoperabilidade sem esforço.
Experimente A2A — Se trabalha com times multi-linguagem, tente o padrão do contract compliance pipeline. Python + Go colaborando via protocolo aberto.
Deploy no Agent Runtime — Quando estiver confortável localmente, agents deploy é um comando. Ganhe escala, observabilidade, Agent Gateway e Memory Bank de graça (billing à parte, claro).
Explore os 13 codelabs da Agent Platform — O Google liberou 13 codelabs hands-on cobrindo cada componente da Gemini Enterprise Agent Platform. Desde Agent Runtime setup até AutoRaters flywheel, passando por Agent Gateway mTLS, Registry discovery, A2UI components, e padrões long-running. São o melhor caminho para dominar a plataforma completa — cada codelab leva 30-60 minutos e vai do zero ao deploy funcional.
Configure AutoRaters — Antes de ir pra produção de verdade, monte seu golden dataset e rode o flywheel de avaliação. agents evaluate --autorater quality-v2 vai te mostrar onde seu agente falha antes que seus usuários descubram.

Recursos oficiais

Documentação ADK — Referência completa
ADK Samples — ~30 exemplos em Python, mais em TS/Go/Java
Google Codelabs ADK — Tutoriais hands-on progressivos
13 Codelabs Agent Platform — Codelabs dedicados à Gemini Enterprise Agent Platform (Agent Runtime, Gateway, Registry, AutoRaters, A2UI, Agents CLI, Long-running patterns)
A2A Protocol — Spec do protocolo agent-to-agent
Agents CLI Docs — Referência oficial do CLI

Opinião final

O ADK não é o framework mais fácil de aprender. Não é o que tem mais hype no Twitter. Não vai te dar aquele dopamine hit de um agente rodando em 3 linhas de código.

Mas é, provavelmente, o framework mais completo e production-ready que existe hoje para quem quer construir sistemas de agentes sérios. A combinação de multi-linguagem + A2A + MCP + debugging UI + managed runtime não existe em nenhum concorrente com a mesma coesão.

Lembra quando o React parecia overkill perto do jQuery? "Por que preciso de toda essa complexidade?" — e então seu app cresceu e você agradeceu por ter escolhido a ferramenta que escalava. O ADK é essa escolha para agentes.

Só não caia na armadilha de achar que precisa do ADK para tudo. Um chatbot simples não precisa de graph workflows. Um protótipo de hackathon não precisa de A2A cross-language. Use a ferramenta certa para o problema certo.

Mas quando o problema for sério, o ADK está pronto.

Quer receber guias como esse direto no seu inbox? Assine a newsletter em ft.ia.br — análises técnicas sem enrolação, toda semana.

Seu Primeiro Agente com LangGraph: Tutorial Passo a Passo

Sat, 04 Jul 2026 00:00:00 GMT

TL;DR — Neste tutorial você vai construir um agente de pesquisa funcional com LangGraph que busca informações na web, avalia se tem dados suficientes e gera um relatório estruturado. O fluxo completo: instalar dependências → definir estado → criar nós de processamento → conectar arestas → adicionar lógica condicional → compilar e executar o grafo. Código completo e pronto para rodar no final do artigo.

O Que Vamos Construir

Vamos criar um agente de pesquisa que faz algo que nenhuma cadeia linear de prompts consegue: ele toma decisões sozinho sobre quando parar de buscar informação.

O fluxo funciona assim:

Recebe um tópico de pesquisa
Gera consultas de busca relevantes
Pesquisa na web usando a API Tavily
Analisa os resultados encontrados
Decide se precisa buscar mais — se sim, volta ao passo 2 com consultas refinadas
Quando tem informação suficiente, escreve um relatório estruturado

Essa capacidade de loop — buscar, avaliar, decidir e voltar — é exatamente o que separa um agente de um simples chain de prompts. É o padrão que empresas como Klarna, Uber e Replit usam em produção com LangGraph desde 2025.

O LangGraph modela esse comportamento como um grafo dirigido: cada etapa é um nó (função Python), cada transição é uma aresta, e as decisões do agente são arestas condicionais. Você define a estrutura, o framework cuida do estado, persistência e fluxo de controle.

Pré-requisitos

Antes de começar, confirme que você tem:

Python 3.11 ou superior — LangGraph 1.x exige essa versão mínima
Uma chave de API da OpenAI — usamos gpt-4o-mini por custo-benefício (funciona com qualquer LLM compatível)
Uma chave de API da Tavily — para busca web (o plano gratuito dá 1.000 buscas por mês)
Familiaridade básica com Python — funções, dicionários, type hints

Se você nunca trabalhou com agentes antes, vale dar uma olhada no artigo sobre arquitetura de harness e loop para entender o modelo mental por trás do que vamos implementar.

Instalação

Crie um diretório para o projeto e configure um ambiente virtual:

mkdir langgraph-pesquisa
cd langgraph-pesquisa
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

Instale as dependências com versões fixas:

pip install langgraph==0.3.34 \
    langchain-openai==0.3.12 \
    langchain-community==0.3.7 \
    tavily-python==0.5.0 \
    python-dotenv==1.1.0

Nota: O pacote langgraph no PyPI está na versão 0.3.x como runtime instalável, embora o framework seja comercialmente identificado como LangGraph 1.0+. Fixe versões em produção para evitar breaking changes.

Crie um arquivo .env na raiz do projeto para suas chaves:

OPENAI_API_KEY=sk-sua-chave-openai-aqui
TAVILY_API_KEY=tvly-sua-chave-tavily-aqui

Teste a instalação:

import langgraph
print(f"LangGraph versão: {langgraph.__version__}")

Se o número de versão aparecer sem erros, estamos prontos.

Definir o Estado

O estado é a memória de trabalho do agente — um dicionário tipado que flui pelo grafo inteiro. Cada nó lê dele e escreve nele. Essa é a decisão de design mais importante: o estado define o que seu agente sabe e consegue rastrear.

Crie um arquivo agente.py:

"""Agente de pesquisa construído com LangGraph."""

import os
from typing import TypedDict, Annotated
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.checkpoint.memory import MemorySaver
from tavily import TavilyClient

load_dotenv()

# --- Schema do Estado ---

class EstadoPesquisa(TypedDict):
    """Memória de trabalho do agente."""
    messages: Annotated[list, add_messages]   # Histórico de conversação
    topico: str                                # O que estamos pesquisando
    consultas: list[str]                       # Queries já executadas
    fontes: list[dict]                         # Resultados brutos da busca
    analise: str                               # Análise das fontes
    relatorio_final: str                       # Relatório final de pesquisa
    iteracao: int                              # Quantas rodadas de pesquisa fizemos
    max_iteracoes: int                         # Limite de segurança contra loops infinitos

Pontos importantes sobre essa definição:

messages usa a anotação add_messages — isso faz o LangGraph acumular mensagens ao invés de substituí-las. O histórico de conversação cresce naturalmente.
iteracao e max_iteracoes previnem loops infinitos. Isso não é opcional — qualquer agente que pode fazer loop precisa de um freio de emergência.
Cada campo tem propósito claro. Quando você precisar debugar o agente (e vai precisar), nomes descritivos economizam horas.

Criar os Nós

Nós são funções Python simples que recebem o estado atual e retornam uma atualização parcial. Sem classes base, sem decoradores obrigatórios. Cada nó faz uma coisa só.

Setup do LLM e Cliente de Busca

# --- Setup ---

llm = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0.1,  # Temperatura baixa para pesquisa factual
)

tavily = TavilyClient(api_key=os.getenv("TAVILY_API_KEY"))

Nó 1: Gerar Consultas de Busca

# --- Nós ---

def gerar_consultas(state: EstadoPesquisa) -> dict:
    """Transforma o tópico em consultas de busca específicas."""
    topico = state["topico"]

    # Em iterações posteriores, refina baseado no que já encontramos
    contexto_existente = ""
    if state.get("analise"):
        contexto_existente = (
            f"\n\nJá sabemos o seguinte:\n{state['analise']}\n\n"
            "Gere consultas para preencher lacunas no nosso conhecimento."
        )

    response = llm.invoke([
        SystemMessage(content=(
            "Você é um assistente de pesquisa. Gere 3 consultas de busca "
            "específicas e diversas para pesquisar o tópico dado. "
            "Retorne apenas as consultas, uma por linha. "
            "Sem numeração, sem texto extra."
            f"{contexto_existente}"
        )),
        HumanMessage(content=f"Tópico de pesquisa: {topico}"),
    ])

    novas_consultas = [
        q.strip() for q in response.content.strip().split("\n") if q.strip()
    ]

    return {
        "consultas": state.get("consultas", []) + novas_consultas,
        "messages": [response],
    }

Repare no padrão de comportamento adaptativo: na primeira execução, o nó gera consultas amplas. Em rodadas posteriores, ele lê sua própria análise anterior e gera consultas para preencher lacunas. O agente literalmente fica mais inteligente a cada loop.

Nó 2: Buscar na Web

def buscar_web(state: EstadoPesquisa) -> dict:
    """Executa as consultas de busca e coleta resultados."""
    consultas = state.get("consultas", [])
    # Busca apenas o último lote de consultas (últimas 3)
    consultas_recentes = consultas[-3:]
    todos_resultados = state.get("fontes", [])

    for consulta in consultas_recentes:
        try:
            response = tavily.search(
                query=consulta,
                max_results=3,
                include_raw_content=False,
            )
            for resultado in response.get("results", []):
                # Evita URLs duplicadas
                if not any(f["url"] == resultado["url"] for f in todos_resultados):
                    todos_resultados.append({
                        "titulo": resultado.get("title", ""),
                        "url": resultado.get("url", ""),
                        "conteudo": resultado.get("content", ""),
                        "consulta": consulta,
                    })
        except Exception as e:
            # Loga mas não crasha — o agente trabalha com resultados parciais
            print(f"Busca falhou para '{consulta}': {e}")

    return {"fontes": todos_resultados}

A deduplicação e o tratamento de erros são intencionais. Se uma API de busca falhar, o agente continua com os resultados que tem. Resiliência é parte do design.

Nó 3: Analisar Resultados

def analisar_resultados(state: EstadoPesquisa) -> dict:
    """Analisa os resultados e avalia se temos informação suficiente."""
    fontes = state.get("fontes", [])

    if not fontes:
        return {
            "analise": "Nenhum resultado encontrado. Preciso tentar consultas diferentes.",
            "iteracao": state.get("iteracao", 0) + 1,
        }

    # Formata as fontes para o LLM
    texto_fontes = ""
    for i, fonte in enumerate(fontes, 1):
        texto_fontes += (
            f"\n[{i}] {fonte['titulo']}\n"
            f"URL: {fonte['url']}\n"
            f"{fonte['conteudo']}\n"
        )

    response = llm.invoke([
        SystemMessage(content=(
            "Você é um analista de pesquisa. Analise os resultados de busca "
            "sobre o tópico dado. Forneça:\n"
            "1. Principais descobertas (o que sabemos)\n"
            "2. Lacunas (o que ainda precisamos descobrir)\n"
            "3. Nível de confiança (baixo/médio/alto) no nosso entendimento geral\n\n"
            "Seja específico e cite números das fontes."
        )),
        HumanMessage(content=f"Tópico: {state['topico']}\n\nFontes:{texto_fontes}"),
    ])

    return {
        "analise": response.content,
        "iteracao": state.get("iteracao", 0) + 1,
        "messages": [response],
    }

Nó 4: Escrever Relatório

def escrever_relatorio(state: EstadoPesquisa) -> dict:
    """Escreve um relatório estruturado com base nas descobertas."""
    fontes = state.get("fontes", [])
    analise = state.get("analise", "")

    texto_fontes = ""
    for i, fonte in enumerate(fontes, 1):
        texto_fontes += (
            f"\n[{i}] {fonte['titulo']}\n"
            f"URL: {fonte['url']}\n"
            f"{fonte['conteudo']}\n"
        )

    response = llm.invoke([
        SystemMessage(content=(
            "Você é um redator de pesquisa. Escreva um relatório claro e "
            "bem estruturado com base na análise e fontes fornecidas. Inclua:\n"
            "- Resumo executivo (2-3 frases)\n"
            "- Principais descobertas com citações [1], [2], etc.\n"
            "- Conclusões\n"
            "- Lista de fontes\n\n"
            "Escreva para um público técnico. Seja factual e específico."
        )),
        HumanMessage(content=(
            f"Tópico: {state['topico']}\n\n"
            f"Análise:\n{analise}\n\n"
            f"Fontes:{texto_fontes}"
        )),
    ])

    return {
        "relatorio_final": response.content,
        "messages": [response],
    }

Montar o Grafo

Aqui é onde o LangGraph brilha. Conectamos os nós com arestas e definimos o fluxo linear básico:

# --- Construir o Grafo ---

workflow = StateGraph(EstadoPesquisa)

# Adicionar nós
workflow.add_node("gerar_consultas", gerar_consultas)
workflow.add_node("buscar_web", buscar_web)
workflow.add_node("analisar_resultados", analisar_resultados)
workflow.add_node("escrever_relatorio", escrever_relatorio)

# Adicionar arestas lineares
workflow.add_edge(START, "gerar_consultas")
workflow.add_edge("gerar_consultas", "buscar_web")
workflow.add_edge("buscar_web", "analisar_resultados")
workflow.add_edge("escrever_relatorio", END)

Até aqui temos um fluxo linear: START → gerar_consultas → buscar_web → analisar_resultados → ... → escrever_relatorio → END. O que falta é a decisão no meio — o agente precisa escolher entre continuar pesquisando ou ir para a escrita.

Executar o Agente (Versão Linear)

Antes de adicionar a lógica condicional, vamos compilar e testar o fluxo básico para garantir que tudo funciona. Temporariamente, conecte analisar_resultados direto ao relatório:

# Versão simplificada para teste
workflow.add_edge("analisar_resultados", "escrever_relatorio")

# Compilar
agente = workflow.compile()

# Executar
resultado = agente.invoke({
    "topico": "Como empresas estão usando agentes de IA em produção em 2026",
    "messages": [],
    "consultas": [],
    "fontes": [],
    "analise": "",
    "relatorio_final": "",
    "iteracao": 0,
    "max_iteracoes": 3,
})

print(resultado["relatorio_final"])

Se o relatório aparecer, seu grafo básico está funcionando. Agora vamos adicionar inteligência.

Adicionar Lógica Condicional

A aresta condicional é o coração de qualquer agente. É aqui que o grafo deixa de ser um pipeline linear e vira algo que raciocina sobre o próprio progresso.

A Função de Roteamento

# --- Lógica de Roteamento ---

def deve_continuar_pesquisa(state: EstadoPesquisa) -> str:
    """Decide se continua pesquisando ou escreve o relatório."""
    iteracao = state.get("iteracao", 0)
    max_iteracoes = state.get("max_iteracoes", 3)
    analise = state.get("analise", "")

    # Hard stop: previne loops infinitos
    if iteracao >= max_iteracoes:
        return "escrever_relatorio"

    # Se a análise menciona confiança baixa ou lacunas, continua
    analise_lower = analise.lower()
    if "baixo" in analise_lower and "confiança" in analise_lower:
        return "gerar_consultas"
    if "lacunas significativas" in analise_lower or "precisamos" in analise_lower:
        return "gerar_consultas"

    # Caso contrário, temos informação suficiente
    return "escrever_relatorio"

A função retorna uma string — o nome do próximo nó. É assim que o agente decide se continua buscando ou parte para a escrita. Repare no max_iteracoes como trava de segurança: nunca permita que um agente faça loop sem limite.

Montando o Grafo Completo

Agora substituímos a aresta fixa entre analisar_resultados e escrever_relatorio pela aresta condicional:

# --- Grafo Completo ---

workflow = StateGraph(EstadoPesquisa)

# Nós
workflow.add_node("gerar_consultas", gerar_consultas)
workflow.add_node("buscar_web", buscar_web)
workflow.add_node("analisar_resultados", analisar_resultados)
workflow.add_node("escrever_relatorio", escrever_relatorio)

# Arestas
workflow.add_edge(START, "gerar_consultas")
workflow.add_edge("gerar_consultas", "buscar_web")
workflow.add_edge("buscar_web", "analisar_resultados")

# Aresta condicional: o agente decide se faz loop ou finaliza
workflow.add_conditional_edges(
    "analisar_resultados",
    deve_continuar_pesquisa,
    {
        "gerar_consultas": "gerar_consultas",
        "escrever_relatorio": "escrever_relatorio",
    },
)

workflow.add_edge("escrever_relatorio", END)

# Memória para persistência de estado
memory = MemorySaver()
agente = workflow.compile(checkpointer=memory)

O fluxo agora funciona assim:

START → gerar_consultas — cria consultas de busca a partir do tópico
gerar_consultas → buscar_web — executa as consultas
buscar_web → analisar_resultados — avalia o que encontrou
analisar_resultados → ??? — a aresta condicional entra em ação. Se a análise diz que precisamos mais informação, voltamos a gerar consultas. Se temos o suficiente, seguimos para a escrita.
escrever_relatorio → END — saída do relatório final

Esse loop — buscar, avaliar, decidir — é o padrão fundamental de agentes. Se quiser entender a diferença entre esse modelo e agent frameworks versus coding agents, vale a leitura para contextualizar.

Resultado Final

Aqui está o código completo e funcional, pronto para copiar e executar:

"""Agente de pesquisa com LangGraph — código completo."""

import os
from typing import TypedDict, Annotated
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.checkpoint.memory import MemorySaver
from tavily import TavilyClient

load_dotenv()

# ============================================================
# ESTADO
# ============================================================

class EstadoPesquisa(TypedDict):
    """Memória de trabalho do agente."""
    messages: Annotated[list, add_messages]
    topico: str
    consultas: list[str]
    fontes: list[dict]
    analise: str
    relatorio_final: str
    iteracao: int
    max_iteracoes: int

# ============================================================
# SETUP
# ============================================================

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.1)
tavily = TavilyClient(api_key=os.getenv("TAVILY_API_KEY"))

# ============================================================
# NÓS
# ============================================================

def gerar_consultas(state: EstadoPesquisa) -> dict:
    """Transforma o tópico em consultas de busca específicas."""
    topico = state["topico"]
    contexto_existente = ""
    if state.get("analise"):
        contexto_existente = (
            f"\n\nJá sabemos:\n{state['analise']}\n\n"
            "Gere consultas para preencher lacunas."
        )
    response = llm.invoke([
        SystemMessage(content=(
            "Você é um assistente de pesquisa. Gere 3 consultas de busca "
            "específicas e diversas para o tópico dado. Retorne apenas as "
            "consultas, uma por linha. Sem numeração."
            f"{contexto_existente}"
        )),
        HumanMessage(content=f"Tópico: {topico}"),
    ])
    novas_consultas = [
        q.strip() for q in response.content.strip().split("\n") if q.strip()
    ]
    return {
        "consultas": state.get("consultas", []) + novas_consultas,
        "messages": [response],
    }


def buscar_web(state: EstadoPesquisa) -> dict:
    """Executa consultas de busca e coleta resultados."""
    consultas_recentes = state.get("consultas", [])[-3:]
    todos_resultados = state.get("fontes", [])

    for consulta in consultas_recentes:
        try:
            response = tavily.search(
                query=consulta,
                max_results=3,
                include_raw_content=False,
            )
            for resultado in response.get("results", []):
                if not any(f["url"] == resultado["url"] for f in todos_resultados):
                    todos_resultados.append({
                        "titulo": resultado.get("title", ""),
                        "url": resultado.get("url", ""),
                        "conteudo": resultado.get("content", ""),
                        "consulta": consulta,
                    })
        except Exception as e:
            print(f"Busca falhou para '{consulta}': {e}")

    return {"fontes": todos_resultados}


def analisar_resultados(state: EstadoPesquisa) -> dict:
    """Analisa resultados e avalia se temos informação suficiente."""
    fontes = state.get("fontes", [])
    if not fontes:
        return {
            "analise": "Nenhum resultado. Precisamos tentar consultas diferentes.",
            "iteracao": state.get("iteracao", 0) + 1,
        }

    texto_fontes = ""
    for i, fonte in enumerate(fontes, 1):
        texto_fontes += f"\n[{i}] {fonte['titulo']}\nURL: {fonte['url']}\n{fonte['conteudo']}\n"

    response = llm.invoke([
        SystemMessage(content=(
            "Você é um analista de pesquisa. Analise os resultados sobre o "
            "tópico dado. Forneça:\n"
            "1. Principais descobertas\n"
            "2. Lacunas no conhecimento\n"
            "3. Nível de confiança (baixo/médio/alto)\n\n"
            "Cite números das fontes."
        )),
        HumanMessage(content=f"Tópico: {state['topico']}\n\nFontes:{texto_fontes}"),
    ])

    return {
        "analise": response.content,
        "iteracao": state.get("iteracao", 0) + 1,
        "messages": [response],
    }


def escrever_relatorio(state: EstadoPesquisa) -> dict:
    """Escreve o relatório final estruturado."""
    fontes = state.get("fontes", [])
    analise = state.get("analise", "")

    texto_fontes = ""
    for i, fonte in enumerate(fontes, 1):
        texto_fontes += f"\n[{i}] {fonte['titulo']}\nURL: {fonte['url']}\n{fonte['conteudo']}\n"

    response = llm.invoke([
        SystemMessage(content=(
            "Você é um redator técnico. Escreva um relatório de pesquisa "
            "claro e estruturado. Inclua:\n"
            "- Resumo executivo (2-3 frases)\n"
            "- Principais descobertas com citações [1], [2]\n"
            "- Conclusões\n"
            "- Lista de fontes\n\n"
            "Público: técnico. Tom: factual e direto."
        )),
        HumanMessage(content=(
            f"Tópico: {state['topico']}\n\n"
            f"Análise:\n{analise}\n\nFontes:{texto_fontes}"
        )),
    ])

    return {
        "relatorio_final": response.content,
        "messages": [response],
    }

# ============================================================
# ROTEAMENTO
# ============================================================

def deve_continuar_pesquisa(state: EstadoPesquisa) -> str:
    """Decide: continuar pesquisando ou escrever o relatório."""
    iteracao = state.get("iteracao", 0)
    max_iteracoes = state.get("max_iteracoes", 3)
    analise = state.get("analise", "")

    if iteracao >= max_iteracoes:
        return "escrever_relatorio"

    analise_lower = analise.lower()
    if "baixo" in analise_lower and "confiança" in analise_lower:
        return "gerar_consultas"
    if "lacunas significativas" in analise_lower or "precisamos" in analise_lower:
        return "gerar_consultas"

    return "escrever_relatorio"

# ============================================================
# GRAFO
# ============================================================

workflow = StateGraph(EstadoPesquisa)

workflow.add_node("gerar_consultas", gerar_consultas)
workflow.add_node("buscar_web", buscar_web)
workflow.add_node("analisar_resultados", analisar_resultados)
workflow.add_node("escrever_relatorio", escrever_relatorio)

workflow.add_edge(START, "gerar_consultas")
workflow.add_edge("gerar_consultas", "buscar_web")
workflow.add_edge("buscar_web", "analisar_resultados")
workflow.add_conditional_edges(
    "analisar_resultados",
    deve_continuar_pesquisa,
    {
        "gerar_consultas": "gerar_consultas",
        "escrever_relatorio": "escrever_relatorio",
    },
)
workflow.add_edge("escrever_relatorio", END)

memory = MemorySaver()
agente = workflow.compile(checkpointer=memory)

# ============================================================
# EXECUÇÃO
# ============================================================

if __name__ == "__main__":
    print("=" * 60)
    print("  Agente de Pesquisa — LangGraph")
    print("=" * 60)

    topico = input("\nDigite o tópico de pesquisa: ").strip()
    if not topico:
        topico = "Como empresas estão usando agentes de IA em produção em 2026"

    print(f"\nPesquisando: {topico}")
    print("-" * 60)

    estado_inicial = {
        "topico": topico,
        "messages": [],
        "consultas": [],
        "fontes": [],
        "analise": "",
        "relatorio_final": "",
        "iteracao": 0,
        "max_iteracoes": 3,
    }

    config = {"configurable": {"thread_id": "sessao-001"}}

    for evento in agente.stream(estado_inicial, config=config):
        for nome_no, saida in evento.items():
            print(f"\n>> Nó: {nome_no}")
            if nome_no == "gerar_consultas" and "consultas" in saida:
                print(f"   Consultas: {saida['consultas'][-3:]}")
            elif nome_no == "buscar_web" and "fontes" in saida:
                print(f"   {len(saida['fontes'])} fontes encontradas")
            elif nome_no == "analisar_resultados" and "analise" in saida:
                print(f"   Iteração: {saida.get('iteracao', '?')}")
                print(f"   Análise: {saida['analise'][:200]}...")
            elif nome_no == "escrever_relatorio" and "relatorio_final" in saida:
                print(f"\n{'=' * 60}")
                print("  RELATÓRIO DE PESQUISA")
                print("=" * 60)
                print(saida["relatorio_final"])

    print(f"\n{'=' * 60}")
    print("Pesquisa concluída.")

Execute com:

python agente.py

Você verá o agente trabalhando em tempo real — gerando consultas, buscando, avaliando, potencialmente voltando para buscar mais, e finalmente escrevendo o relatório.

Próximos Passos

Você acabou de construir um agente funcional com LangGraph. Os conceitos que aprendeu — StateGraph, add_node, add_edge, add_conditional_edges, compile — são os mesmos que rodam em produção nas empresas que mencionamos.

A partir daqui, os caminhos se abrem:

Adicionar Human-in-the-Loop. LangGraph permite inserir pontos de aprovação humana em qualquer lugar do grafo. O agente pausa, espera a aprovação e continua. Essencial para agentes que tomam ações no mundo real.

Persistência em banco de dados. O MemorySaver que usamos guarda estado em memória. Para produção, troque por SqliteSaver ou PostgresSaver e seu agente sobrevive a reinícios.

Sistemas multi-agente. No LangGraph, um nó pode ser outro grafo compilado. Você pode ter um agente supervisor delegando para agentes especialistas — pesquisador, redator, revisor — cada um com seu próprio grafo.

Streaming de eventos. Ao invés de .stream() com eventos de nó, use .astream_events() para receber cada token conforme o LLM gera. Dá uma experiência de tempo real para o usuário.

Expandir ferramentas. Adicione leitura/escrita de arquivos, execução de código, chamadas a APIs, navegação web. Cada capacidade é um novo nó no grafo.

O padrão fundamental — estado, nós, arestas, decisão — se mantém independente da complexidade. Você define a estrutura, o LangGraph cuida do resto. Se quer entender como frameworks como esse se comparam a coding agents como Claude Code e Cursor, o artigo sobre agent frameworks vs coding agents faz essa distinção com clareza.

Bom building.

OpenAI Agents SDK: Guia Definitivo para Agentes Leves

Sat, 04 Jul 2026 00:00:00 GMT

TL;DR — O OpenAI Agents SDK é o sucessor de produção do Swarm: quatro primitivos (Agent, Runner, Handoffs, Guardrails), tracing embutido, suporte a MCP, e zero boilerplate para colocar múltiplos agentes conversando entre si. Se você já roda modelos OpenAI e precisa de delegação limpa entre especialistas, esse SDK é a menor distância entre a sua ideia e um sistema multi-agent funcionando. Instalou, definiu agentes, rodou. Sem grafos, sem YAML, sem cerimônia.

Overview

De Swarm a produção: a história de um experimento que vingou

Em outubro de 2024 a OpenAI soltou o Swarm — um repositório educacional, quase um brinquedo, que mostrava como orquestrar múltiplos agentes LLM em menos de 100 linhas de Python. A premissa era audaciosa na simplicidade: agentes são funções stateless que se passam o bastão. Sem grafos, sem DAGs, sem banco de estado. Só handoffs.

O problema? O Swarm carregava um disclaimer gigante: "experimental, educational, not production-ready". E não mentia. Faltava tratamento de erro, tracing, guardrails, persistência de sessão — tudo que você precisa quando sai do Jupyter notebook e vai pra produção.

Em março de 2025, a OpenAI arquivou o repositório do Swarm e redirecionou todo mundo pro OpenAI Agents SDK. Mesma filosofia minimalista, mesma API enxuta — mas agora com a robustez que faltava. O README do Swarm é explícito: "Swarm is now replaced by the OpenAI Agents SDK, which is a production-ready evolution of Swarm."

E em abril de 2026 veio a evolução seguinte: sandbox agents, manifests para workspaces, integração com provedores de sandbox (E2B, Modal, Cloudflare, Vercel), memory configurável e skills nativas. O SDK deixou de ser "só um loop de agente" e virou um harness completo para agentes que mexem em arquivos, rodam comandos e trabalham em tarefas longas.

Filosofia: minimalismo com opinião

O Agents SDK ocupa um ponto muito específico no stack. Não é uma API de modelo (isso é o Responses API). Não é uma plataforma managed (isso era o Agent Builder, que foi descontinuado). É um runtime de agente — uma biblioteca que gerencia o loop do agente, despacha tools, executa handoffs, roda guardrails e coleta traces.

A filosofia de design pode ser resumida em três princípios:

Poucos primitivos, bem compostos — Agent, Runner, Handoffs, Guardrails. Você aprende em uma tarde.
O LLM decide — o modelo escolhe quando usar tools e quando fazer handoff. O SDK não impõe fluxo.
Convenção sobre configuração — tracing é automático, schemas são inferidos via Pydantic, tools se registram com um decorator.

Isso é radicalmente diferente do approach do LangGraph, que modela workflows como grafos dirigidos com nós e arestas explícitas. Aqui não existe grafo. Existe um agente que pode delegar pra outro. Ponto.

A pergunta que fica: quando essa simplicidade é suficiente — e quando vira limitação? Vamos descobrir.

Tutorial

Instalação

Python 3.9+ e um pip install:

pip install openai-agents

Pronto. Sem extra dependencies pesadas, sem compilação de extensões C. O pacote é leve de propósito — a OpenAI quer que você importe, use e não pense na infraestrutura.

Configure sua API key:

export OPENAI_API_KEY="sk-..."

Primeiro agente: o clássico "Hello World"

from agents import Agent, Runner

agente = Agent(
    name="Assistente Geral",
    instructions="Você é um assistente técnico. Responda de forma concisa e direta.",
    model="gpt-4o-mini",
)

resultado = Runner.run_sync(agente, "O que é o Model Context Protocol?")
print(resultado.final_output)

Três linhas de setup, uma de execução. O Runner.run_sync() faz todo o trabalho pesado: monta o prompt com as instructions, chama o modelo, verifica se há tool calls, executa tools se necessário, e repete até ter uma resposta final.

A versão assíncrona é await Runner.run() — mesma interface, mas sem bloquear a event loop.

Adicionando uma tool

Tools são funções Python decoradas:

from agents import Agent, Runner, function_tool

@function_tool
def buscar_clima(cidade: str) -> str:
    """Retorna a previsão do tempo para uma cidade."""
    # Em produção, chamaria uma API de clima
    return f"Em {cidade}: 22°C, parcialmente nublado."

agente = Agent(
    name="Agente Clima",
    instructions="Você ajuda usuários com informações de clima. Use a tool buscar_clima.",
    tools=[buscar_clima],
    model="gpt-4o-mini",
)

resultado = Runner.run_sync(agente, "Qual o clima em São Paulo?")
print(resultado.final_output)

O SDK usa inspect do Python pra extrair a assinatura da função e pydantic pra gerar o schema JSON automaticamente. Você não precisa declarar schemas manualmente — é a type hint que define tudo.

Handoff entre dois agentes

Aqui é onde a coisa fica interessante. Vamos criar um sistema de triagem que delega para um especialista:

from agents import Agent, Runner

# Agente especialista em billing
agente_billing = Agent(
    name="Especialista Financeiro",
    instructions="""Você é especialista em questões financeiras.
    Ajuda com cobranças, faturas, reembolsos e métodos de pagamento.
    Seja direto e resolva o problema.""",
    model="gpt-4o-mini",
)

# Agente especialista em suporte técnico
agente_suporte = Agent(
    name="Suporte Técnico",
    instructions="""Você é especialista em suporte técnico.
    Ajuda com bugs, configurações, integrações e problemas de performance.""",
    model="gpt-4o-mini",
)

# Agente de triagem — decide pra quem delegar
agente_triagem = Agent(
    name="Triagem",
    instructions="""Você é o agente de triagem. Analise a mensagem do usuário e:
    - Se for sobre cobrança, fatura ou pagamento → delegue para Especialista Financeiro
    - Se for sobre bug, erro ou configuração → delegue para Suporte Técnico
    - Se for genérico, responda você mesmo.""",
    handoffs=[agente_billing, agente_suporte],
    model="gpt-4o-mini",
)

# O usuário fala com triagem, que delega automaticamente
resultado = Runner.run_sync(
    agente_triagem,
    "Fui cobrado duas vezes na minha assinatura esse mês."
)
print(resultado.final_output)

O que acontece por baixo dos panos: o modelo do agente_triagem recebe a mensagem, identifica que é um problema financeiro, e emite um sinal de handoff para o agente_billing. O Runner intercepta esse sinal, transfere o controle, e o agente_billing recebe o contexto da conversa e responde. Tudo dentro de uma única chamada Runner.run_sync().

Não precisou definir grafos, arestas, condições de roteamento explícitas. O LLM decidiu. Essa é a filosofia do SDK: confia no modelo pra rotear, e valida com guardrails.

Deep Dive

Agent — o descritor leve

Um Agent no SDK não é um processo rodando, não é um container, não é um servidor. É um descritor: um objeto Python que diz "esse agente tem essas instructions, essas tools, esse modelo, esses handoffs disponíveis". Quem dá vida ao agente é o Runner.

Os parâmetros principais:

Parâmetro	O que faz
`name`	Identificador legível (aparece no tracing)
`instructions`	System prompt — a personalidade e regras do agente
`model`	Override de modelo por agente (cada agente pode usar um modelo diferente)
`tools`	Lista de function tools, hosted tools ou MCP servers
`handoffs`	Lista de outros Agents para os quais este pode delegar
`input_guardrails`	Validações que rodam na entrada do usuário
`output_guardrails`	Validações que rodam na saída do agente
`output_type`	Modelo Pydantic para structured output

Detalhe que eu acho elegante: como cada agente pode ter seu próprio model, você consegue montar arquiteturas onde o triagem usa um modelo barato e rápido (gpt-4o-mini) e o especialista usa um modelo pesado (gpt-4o ou gpt-5.4) só quando necessário. Economia de tokens na veia.

Runner — o motor de execução

O Runner é o loop. Ele:

Chama o LLM com as instructions do agente + histórico da conversa
Se o LLM retorna tool calls → executa as tools
Alimenta os resultados de volta ao LLM
Se o LLM retorna um handoff → transfere controle pro agente-alvo
Repete até ter output final ou atingir max_turns

from agents import Runner

# Síncrono
resultado = Runner.run_sync(agente, "mensagem do usuário")

# Assíncrono
resultado = await Runner.run(agente, "mensagem do usuário")

# Com configuração
from agents.run import RunConfig
resultado = await Runner.run(
    agente,
    "mensagem",
    run_config=RunConfig(max_turns=25)
)

Gotcha importante: o default de max_turns é 10. Em workflows com múltiplos handoffs e tools, 10 turns acabam rápido. Cada handoff consome um turn, cada tool call + resposta consome dois. Três agentes com duas tools cada pode estourar fácil. Aumente o max_turns ou passe None pra desabilitar o limite.

Handoffs — delegação entre agentes

Handoffs são o mecanismo multi-agent do SDK. Conceitualmente: um agente termina seu turno passando o bastão para outro agente. Na prática, funciona assim:

O agente-fonte tem o agente-alvo na sua lista de handoffs
O LLM do agente-fonte decide (via function calling) fazer o handoff
O Runner detecta o sinal, reescreve o contexto da conversa, e passa o controle

O ponto-chave é a reescrita de histórico. Quando o agente B recebe o handoff do agente A, ele não vê necessariamente toda a conversa anterior. O SDK fornece filtros em agents.extensions.handoff_filters pra customizar o que o agente-alvo recebe.

Existem dois padrões de orquestração com handoffs:

Padrão 1: Router (mais comum)

Usuário → Triagem → [Billing | Suporte | Vendas]

Padrão 2: Agent as Tool

from agents import Agent, Runner, function_tool

agente_pesquisa = Agent(
    name="Pesquisador",
    instructions="Pesquise informações sobre o tema solicitado.",
)

@function_tool
def pesquisar(query: str) -> str:
    """Delega pesquisa para o agente especialista."""
    resultado = Runner.run_sync(agente_pesquisa, query)
    return resultado.final_output

coordenador = Agent(
    name="Coordenador",
    tools=[pesquisar],
    instructions="Coordene tarefas. Use a tool pesquisar quando precisar de dados.",
)

Nesse segundo padrão, o agente-filho roda como tool e retorna o resultado para o pai. É handoff implícito — o controle volta pro coordenador depois.

Guardrails — segurança em camadas

O sistema de guardrails do SDK é uma das funcionalidades que mais brilham. São três escopos:

Input Guardrails — rodam na entrada do primeiro agente da cadeia:

from agents import input_guardrail, GuardrailFunctionOutput, Agent, Runner
from pydantic import BaseModel

class AnaliseSeguranca(BaseModel):
    is_malicioso: bool
    razao: str

agente_guardrail = Agent(
    name="Analisador de Segurança",
    instructions="Verifique se a mensagem é maliciosa, spam ou off-topic.",
    output_type=AnaliseSeguranca,
    model="gpt-4o-mini",  # modelo barato pro guardrail
)

@input_guardrail
async def guardrail_seguranca(ctx, agent, input):
    resultado = await Runner.run(agente_guardrail, input, context=ctx.context)
    return GuardrailFunctionOutput(
        output_info=resultado.final_output,
        tripwire_triggered=resultado.final_output.is_malicioso,
    )

agente_principal = Agent(
    name="Assistente",
    instructions="Ajude o usuário com suas dúvidas.",
    input_guardrails=[guardrail_seguranca],
    model="gpt-4o",  # modelo caro, protegido pelo guardrail
)

A sacada aqui é econômica: o guardrail roda num modelo barato e bloqueia requests maliciosos antes de atingir o modelo caro. Tripwire disparou? A execução para imediatamente com uma exceção InputGuardrailTripwireTriggered.

Output Guardrails — rodam na saída do último agente:

from agents import output_guardrail, GuardrailFunctionOutput

@output_guardrail
async def guardrail_pii(ctx, agent, output):
    # Verifica se a resposta contém dados sensíveis
    texto = str(output)
    tem_pii = any(p in texto.lower() for p in ["cpf", "cartão de crédito", "senha"])
    return GuardrailFunctionOutput(tripwire_triggered=tem_pii)

Tool Guardrails — rodam antes/depois de cada chamada de function tool:

from agents import function_tool, tool_input_guardrail, ToolGuardrailFunctionOutput

@tool_input_guardrail
def bloquear_segredos(data):
    args = data.context.tool_arguments or "{}"
    if "sk-" in args:
        return ToolGuardrailFunctionOutput.reject_content(
            "Remova segredos antes de chamar esta tool."
        )
    return ToolGuardrailFunctionOutput.allow()

@function_tool(tool_input_guardrails=[bloquear_segredos])
def processar_texto(texto: str) -> str:
    """Processa texto para classificação."""
    return f"Classificado: {len(texto)} caracteres"

Existe também a opção de rodar guardrails em modo bloqueante (run_in_parallel=False) — onde o guardrail termina antes do agente começar, garantindo zero tokens gastos em requests inválidos. Por default rodam em paralelo (melhor latência, mas o agente pode já ter começado quando o guardrail dispara).

Tracing — observabilidade de graça

Todo Runner.run() é automaticamente rastreado. Sem configuração, sem setup adicional. O SDK coleta:

Gerações LLM (prompt, completion, token counts)
Tool calls (nome, input, output, duração)
Handoffs (fonte, alvo, razão)
Guardrail checks (qual guardrail, resultado, duração)

Os traces vão pro dashboard de Traces da OpenAI por padrão. Quer mandar pro Grafana, Datadog ou outro backend? Implemente um TraceProcessor custom:

from agents import trace

with trace(workflow_name="Suporte ao Cliente"):
    resultado = Runner.run_sync(agente_triagem, "Preciso de ajuda")

Essa é uma funcionalidade que frameworks concorrentes ou não têm, ou cobram à parte (oi, LangSmith). Aqui é grátis desde o primeiro run(). Quando você está debugando por que um agente fez um handoff estranho ou por que uma tool falhou, os traces são ouro.

Context — estado compartilhado

O RunContextWrapper permite injetar contexto customizado que todas as tools e guardrails acessam:

from dataclasses import dataclass
from agents import Agent, Runner, function_tool, RunContextWrapper

@dataclass
class ContextoApp:
    user_id: str
    plano: str
    saldo: float

@function_tool
def verificar_saldo(ctx: RunContextWrapper[ContextoApp]) -> str:
    """Verifica o saldo do usuário."""
    return f"Saldo atual: R$ {ctx.context.saldo:.2f}"

contexto = ContextoApp(user_id="usr_123", plano="pro", saldo=150.00)
resultado = await Runner.run(agente, "Qual meu saldo?", context=contexto)

O context é type-safe via generics. Se você tentar acessar um campo que não existe, o linter pega.

Sessions — memória persistente

Pra manter conversa entre turns (o agente lembrar o que o usuário disse antes), o SDK oferece sessions plugáveis:

from agents import Agent, Runner
from agents.extensions.memory import SQLAlchemySession

session = await SQLAlchemySession.create(
    connection_string="sqlite:///agente.db"
)

agente = Agent(name="Memória", instructions="Lembre preferências do usuário.")

await Runner.run(agente, "Meu nome é João.", session=session)
resultado = await Runner.run(agente, "Qual meu nome?", session=session)
# → "Seu nome é João."

Backends disponíveis: SQLite (dev), Redis (multi-processo), PostgreSQL via SQLAlchemy (produção), MongoDB, e até DaprSession pra ambientes cloud-native.

MCP — ferramentas externas

O SDK tem suporte nativo ao Model Context Protocol, permitindo conectar qualquer MCP server como tool do agente:

from agents import Agent
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Filesystem",
    params={"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]}
) as server:
    agente = Agent(
        name="File Manager",
        instructions="Gerencie arquivos para o usuário.",
        mcp_servers=[server],
    )

Isso abre um universo: databases, APIs, browsers, sistemas de arquivo — qualquer coisa que tenha um MCP server vira tool acessível pros seus agentes.

Spider Chart

Avaliação em 8 eixos (0–100):

                    Facilidade de Uso
                         95
                          │
        Documentação      │      Ecosystem/Comunidade
              80 ─────────┼───────── 65
                         ╱│╲
          Tracing/      ╱ │ ╲      Flexibilidade
          Observ. 90 ──╱──│──╲── 55
                      ╱   │   ╲
        Guardrails   ╱    │    ╲   Multi-Provider
              85 ───╱─────│─────╲─── 60
                   ╱      │      ╲
                  ╱       │       ╲
         Multi-Agent      │     Maturidade
              75 ─────────┼───────── 80

Eixo	Nota	Justificativa
Facilidade de Uso	95	Quatro primitivos, zero boilerplate. Curva de aprendizado mais suave que qualquer concorrente.
Documentação	80	Docs oficiais completas, com exemplos. Falta conteúdo em português e tutoriais avançados.
Tracing/Observabilidade	90	Automático, gratuito, integrado. Difícil bater isso.
Guardrails	85	Três escopos (input, output, tool), tripwire pattern elegante. Falta approval flows sofisticados.
Multi-Agent	75	Handoffs funcionam bem pra padrão router/supervisor. Falta execução paralela nativa.
Multi-Provider	60	Funciona com 100+ modelos via LiteLLM, mas features premium (tracing dashboard, hosted tools) são OpenAI-only.
Flexibilidade	55	Opinado por design. Se seu workflow não é tree-shaped, vai lutar contra o framework.
Ecosystem/Comunidade	65	Crescendo rápido, mas ainda atrás de LangChain/LangGraph em tamanho de comunidade e plugins.
Maturidade	80	Em produção desde 2025. Empresas como Oscar Health já usam em produção. API estabilizando.

Prós e Contras

O que brilha

Zero cerimônia — Você vai de pip install a multi-agent funcionando em 20 minutos. Sério. Sem YAML, sem grafos, sem configuração de infraestrutura.
Tracing gratuito e automático — Não precisa configurar nada. Todo Runner.run() gera traces. Compare com LangSmith que cobra planos a partir de $39/mês pra funcionalidades similares.
Guardrails como cidadão de primeira classe — Não é um afterthought ou plugin. O sistema de tripwires é simples, testável e cobre input, output e tools.
Economia por design — Modelo barato no guardrail, modelo barato na triagem, modelo caro só no especialista. O SDK incentiva esse padrão naturalmente.
MCP nativo — Qualquer MCP server é tool. Sem adapters, sem wrappers, sem gambiarras.
Sandbox Agents — A evolução de abril/2026 permite rodar agentes em ambientes isolados com filesystem, shell e persistência. É basicamente o Codex como library.

Onde dói

Sem execução paralela nativa — Se você precisa de fan-out/fan-in (rodar 3 agentes em paralelo e sintetizar), vai ter que orquestrar com asyncio.gather() na mão. LangGraph faz isso out of the box.
Human-in-the-loop limitado — Guardrails conseguem parar a execução, mas não pausar e retomar. Fluxos de aprovação tipo "agente propõe → humano aprova → agente continua" exigem gambiarra.
Vendor lock-in prático — Sim, suporta outros modelos via LiteLLM. Mas tracing dashboard, hosted tools (WebSearch, FileSearch, CodeInterpreter), e sandbox agents são exclusivos OpenAI. Rodar com Anthropic ou local perde metade das features.
Sem TypeScript (ainda) — O SDK oficial é Python-only. Existe um port comunitário em TS, mas sem garantia de paridade. Se seu stack é Node, vai ter que esperar ou usar alternativas.
Handoffs são sequenciais — Um agente delega pra outro que delega pra outro. É sempre linear. Workflows onde dois agentes precisam dialogar entre si (A → B → A → B) ficam desajeitados.
Custos invisíveis — O SDK abstrai contagem de tokens. Você só descobre quanto gastou depois, nos traces. Não existe budget governor ou custo máximo por run.

Quando usar

O OpenAI Agents SDK é a escolha certa quando:

✅ Seu stack já é OpenAI — Se você usa GPT-4o/gpt-5.x e a Responses API, o SDK adiciona orquestração multi-agent sem nova superfície de abstração.

✅ Seu padrão é router → especialistas — Triagem que delega pra N especialistas é exatamente o que handoffs fazem bem. Suporte ao cliente com departamentos, pipelines de processamento com etapas especializadas.

✅ Guardrails e compliance são requisitos — Se precisa de validação de input/output como requisito regulatório ou de segurança, o SDK entrega isso pronto.

✅ Prototipagem rápida com caminho pra produção — Ao contrário do CrewAI (ótimo pra prototipar mas questionável em prod), o Agents SDK é production-ready desde o dia um. Tracing, sessions, error handling — tudo incluído.

✅ Migração do Assistants API — O Assistants API será sunset em agosto de 2026. Se você usa, essa é a migração recomendada oficialmente pela OpenAI.

✅ Agentes que operam em arquivos e código — Com sandbox agents, seu agente pode inspecionar arquivos, rodar comandos e editar código em ambientes isolados. Pense num harness de agente de codificação encapsulado numa lib.

Quando NÃO usar

❌ Workflows com paralelismo complexo — Se você precisa de fan-out/fan-in, dependency graphs entre tasks, ou múltiplos agentes rodando simultâneamente com estado compartilhado, LangGraph é melhor equipado.

❌ Diálogos multi-turn entre agentes — Se seu valor está em agentes que se criticam mutuamente (um escreve, outro revisa, o primeiro corrige), AutoGen modela isso naturalmente com group chat. Handoffs são unidirecionais.

❌ Stack 100% TypeScript/JavaScript — Sem SDK oficial em TS, você vai lutar com bindings incompletas. Espere o suporte oficial ou use o Vercel AI SDK como alternativa.

❌ Orçamento apertado de tokens com controle granular — O SDK não tem cost governor. Se cada token conta e você precisa de budget caps por agent run, vai ter que instrumentar manualmente.

❌ Multi-provider como requisito core — Se amanhã você quer trocar OpenAI por Anthropic sem perder funcionalidade, vai perder tracing dashboard, hosted tools e sandbox. A promessa "provider-agnostic" é parcial.

❌ Fluxos de aprovação humana sofisticados — Pra workflows onde um agente propõe uma ação, pausa, um humano revisa no Slack, aprova, e o agente continua — o SDK não tem mecanismo nativo. Precisa de infra custom em volta.

Comparativo rápido com concorrentes

	Agents SDK	LangGraph	CrewAI	AutoGen/MAF
Curva de aprendizado	Baixa	Alta	Baixa	Média
Multi-agent	Handoffs	Grafos	Roles+Tasks	Group Chat
Parallelismo	Manual	Nativo	Sequencial	Via chat
Guardrails	Nativo (3 scopes)	Via callbacks	—	Limitado
Tracing	Grátis/automático	LangSmith (pago)	Limitado	Third-party
MCP	Nativo	Community	Via plugins	Community
Maturidade	Alta	Mais alta	Crescendo	Em transição (MAF)

Próximos passos

Se você quer começar agora

pip install openai-agents — instale e rode o quickstart da documentação oficial
Monte um triagem + 2 especialistas — use o padrão router do tutorial acima como base
Adicione guardrails — comece com um input guardrail simples que bloqueia off-topic
Habilite tracing — já vem ligado, mas explore o dashboard em platform.openai.com/traces
Conecte um MCP server — filesystem ou database, pra experimentar tools externas

Se quer ir além

Explore Sandbox Agents pra agentes que operam em código — o post da OpenAI de abril/2026 detalha o modelo de isolamento
Combine com sessions em Redis/PostgreSQL pra agentes stateful em produção
Implemente um TraceProcessor custom pra mandar traces pro Grafana ou seu stack de observabilidade
Avalie se handoffs atendem ou se você precisa de algo mais sofisticado — se sim, olhe LangGraph

Leituras complementares aqui no blog

Veredicto

O OpenAI Agents SDK é a resposta certa pra pergunta "qual o menor framework que me dá multi-agent funcional em produção?". Quatro primitivos. Tracing grátis. Guardrails embutidos. MCP nativo. Sessions plugáveis.

Não é a resposta certa pra tudo — se você precisa de grafos complexos, paralelismo nativo, ou independência total de provider, existem ferramentas melhores. Mas pra 80% dos casos de uso "tenho um sistema que precisa rotear requests entre agentes especializados", o SDK entrega mais com menos código e menos dependências que qualquer alternativa.

A OpenAI está apostando que minimalismo com opinião ganha de generalismo com complexidade. No ecossistema de agentes de codificação onde todos reclamam de excesso de abstração, talvez eles tenham razão.

Precisa de ajuda implementando agentes em produção? Consultoria personalizada em ft.ia.br.