Utilizando Sub Agents com o Kiro CLI

Se você já usa o Kiro CLI no dia a dia, sabe que ele resolve bem tarefas diretas: editar arquivos, rodar comandos, analisar código. Mas e quando a tarefa é complexa, com várias etapas independentes? É aí que entram os sub agents.

Neste post vou explorar a fundo como eles funcionam, quando fazem sentido, os padrões de orquestração e os cuidados que você precisa ter pra tirar o máximo dessa feature.

O que são Sub Agents?

Sub agents são agentes especializados que o Kiro CLI pode invocar pra executar subtarefas de forma isolada e paralela. Pense neles como "workers" que o agente principal recruta sob demanda.

Cada sub agent tem:

• Contexto próprio: ele não enxerga a conversa principal nem os outros sub agents
• Toolset especializado: pode ter ferramentas diferentes do agente principal
• Execução independente: roda em paralelo, sem bloquear o fluxo

O agente principal funciona como um orquestrador. Ele decide o que delegar, dispara os sub agents, espera os resultados e consolida tudo numa resposta coerente pra você.

Como funciona por baixo dos panos

O ciclo de vida de uma chamada com sub agents segue esse fluxo:

1. Descoberta de agentes

Antes de delegar, o agente principal executa um ListAgents pra saber quais agentes especializados estão disponíveis e quais ferramentas cada um oferece. Isso é importante porque nem todo sub agent serve pra qualquer tarefa.

2. Invocação paralela

Com os agentes mapeados, o principal usa InvokeSubagents passando um array de até 4 sub agents simultâneos. Cada invocação recebe:

• query: a tarefa que o sub agent precisa executar
• agent_name (opcional): qual agente específico usar
• relevant_context (opcional): contexto adicional pra ajudar o sub agent a entender a tarefa

3. Execução isolada

Cada sub agent roda com seu próprio contexto. Ele não sabe que outros sub agents existem, não tem acesso à conversa principal e não pode se comunicar com os demais. Essa isolação é proposital: evita conflitos, mantém o contexto limpo e permite paralelismo real.

4. Consolidação

Quando todos os sub agents terminam, os resultados voltam pro agente principal. Ele analisa cada resposta, resolve possíveis conflitos e monta a resposta final.

Quando usar Sub Agents

Cenários ideais

Análises independentes em paralelo: você pede pro Kiro analisar segurança de um Dockerfile, revisar permissões IAM e validar um template CloudFormation. São 3 tarefas sem dependência entre si, perfeitas pra rodar em paralelo. Pesquisa em múltiplas fontes: precisa buscar informações em diferentes partes do codebase ao mesmo tempo. Cada sub agent pode explorar um diretório ou módulo diferente. Geração de artefatos independentes: criar um script de deploy, uma policy IAM e um arquivo de configuração ao mesmo tempo. Cada sub agent gera um artefato sem depender dos outros. Ferramentas que o agente principal não tem: às vezes o sub agent tem acesso a tools específicos que o principal não possui. Delegar é a única forma de acessar essas capabilities.

Quando NÃO usar

Tarefas sequenciais com dependência: se a tarefa B precisa do resultado da tarefa A, não adianta disparar as duas juntas. O sub agent B não vai ter o output de A porque eles não se comunicam. Tarefas simples e rápidas: pra coisas triviais, o overhead de criar sub agents não compensa. O agente principal resolve mais rápido sozinho. Quando o contexto compartilhado é essencial: se as subtarefas precisam "conversar" entre si ou compartilhar estado intermediário, sub agents não são a ferramenta certa.

Padrões de orquestração

Fan-out / Fan-in

O padrão mais comum. O agente principal divide a tarefa em N partes, dispara N sub agents em paralelo (fan-out), espera todos terminarem e consolida os resultados (fan-in).

Exemplo: "Revise todos os arquivos de infraestrutura do projeto"

1. O principal lista os arquivos relevantes
2. Dispara um sub agent pra cada arquivo (até 4 por vez)
3. Coleta as revisões e apresenta um resumo consolidado

Pipeline com estágios paralelos

Quando você tem uma sequência de etapas, mas dentro de cada etapa existem tarefas paralelizáveis.

Exemplo: "Analise o projeto e depois gere a documentação"

1. Estágio 1 (paralelo): sub agents analisam diferentes módulos do projeto
2. O principal consolida a análise
3. Estágio 2 (paralelo): sub agents geram docs pra cada módulo com base na análise consolidada

Especialista sob demanda

O principal identifica que precisa de uma capability específica que só um sub agent tem e delega pontualmente.

Exemplo: o agente principal não tem acesso a uma ferramenta de busca semântica, mas um sub agent tem. Ele delega a busca e usa o resultado pra continuar o trabalho.

Exemplo prático: auditoria de segurança AWS

Vamos a um cenário real. Você tem um projeto com infraestrutura AWS e quer uma auditoria completa. O pedido seria algo como:

"Faça uma auditoria de segurança: revise as IAM policies, analise os security groups, verifique as configurações do S3 e valide o CloudFormation."

O Kiro CLI pode resolver isso assim:

Rodada 1 (4 sub agents em paralelo):

• Sub agent 1: analisa as IAM policies buscando permissões excessivas
• Sub agent 2: revisa os security groups procurando portas abertas desnecessariamente
• Sub agent 3: verifica configurações do S3 (encryption, public access, versioning)
• Sub agent 4: valida o CloudFormation contra boas práticas

Consolidação: o agente principal recebe os 4 relatórios, identifica os achados mais críticos, cruza informações (ex: uma policy permissiva + um bucket público = risco alto) e entrega um relatório unificado com priorização.

Sem sub agents, isso seria sequencial e levaria bem mais tempo. Com eles, as 4 análises rodam ao mesmo tempo.

Combinando com o Planner Agent

O Kiro CLI tem outro recurso poderoso: o Planner Agent, ativado com Shift + Tab. Ele é read-only, ou seja, só ajuda a pensar e estruturar, sem fazer alterações.

Um workflow eficiente combina os dois:

1. Planner Agent: você descreve o que quer fazer e ele quebra em um plano estruturado com etapas claras
2. Identificação de paralelismo: olhando o plano, você (ou o agente principal) identifica quais etapas são independentes
3. Sub agents: as etapas independentes são delegadas em paralelo
4. Consolidação: resultados voltam e alimentam as próximas etapas

Essa combinação transforma o Kiro de um assistente reativo em uma ferramenta de planejamento e execução paralela.

Dicas e boas práticas

Forneça contexto relevante: use o campo relevant_context pra dar ao sub agent as informações que ele precisa. Lembre que ele não tem acesso à conversa principal, então seja explícito. Respeite o limite de 4: você pode disparar no máximo 4 sub agents por vez. Se tem mais tarefas, faça em rodadas. Pense em independência: antes de delegar, pergunte "essa tarefa depende do resultado de outra?". Se sim, não coloque no mesmo bloco. Use pra evitar context bloat: tarefas que geram muito output (análise de arquivos grandes, buscas extensas) são ótimas candidatas pra sub agents. O contexto pesado fica isolado e só o resultado relevante volta pro principal. Não force paralelismo: nem toda tarefa precisa de sub agents. Se é algo simples e direto, deixe o agente principal resolver. O overhead de criar sub agents só compensa pra tarefas que realmente se beneficiam de paralelismo.

Conclusão

Sub agents são uma das features mais poderosas do Kiro CLI pra quem lida com tarefas complexas. Eles transformam o assistente de um executor sequencial em um orquestrador paralelo, capaz de dividir trabalho entre agentes especializados e consolidar resultados de forma inteligente.

Pra quem trabalha com infraestrutura AWS, isso é especialmente útil: auditorias, análises de segurança, geração de artefatos e revisões de código podem rodar simultaneamente, economizando tempo sem perder profundidade.

A chave é entender quando paralelizar faz sentido e quando o fluxo sequencial é mais adequado. Com essa clareza, os sub agents viram um multiplicador real de produtividade no seu workflow.