Loop Agent

Configure agentes que executam sub-agentes em loop iterativo para refinamento e melhoria contínua

Visão Geral

O Loop Agent é um tipo de agente de workflow que executa sub-agentes em um ciclo iterativo até que uma condição de parada seja atendida. Este padrão é ideal para processos que precisam de refinamento contínuo, melhoria iterativa ou tentativas múltiplas até atingir um resultado satisfatório.

Diferentemente dos agentes Sequential e Parallel, o Loop Agent repete a execução dos sub-agentes múltiplas vezes, permitindo que cada iteração melhore o resultado baseado no feedback da iteração anterior.

Baseado no Google ADK: Implementação seguindo os padrões do Google Agent Development Kit para agentes iterativos.

Características Principais

Execução Iterativa

Repete execução dos sub-agentes até condição de parada

Melhoria Contínua

Cada iteração pode melhorar o resultado baseado no anterior

Tool exit_loop

Controle de parada via tool automática nas instruções

Flexibilidade Total

Critérios de parada personalizáveis via instruções

Tool exit_loop - Controle de Parada

Importante: O Loop Agent permite que você selecione quais sub-agentes podem usar a tool exit_loop. Durante a configuração dos sub-agentes, você define quais têm o poder de parar o loop.

Como funciona:

• Na configuração de cada sub-agente, você pode habilitar o uso da tool exit_loop
• Apenas os sub-agentes selecionados podem decidir parar o loop
• A tool aceita parâmetros para documentar o motivo da parada
• Permite controle granular sobre quem pode finalizar o processo iterativo

Configuração na interface:

• ✅ Sub-agentes com exit_loop: Podem usar a tool para parar o loop
• ❌ Sub-agentes sem exit_loop: Executam normalmente sem poder de parada

Como usar exit_loop:

exit_loop()

A função exit_loop não aceita argumentos. Ela simplesmente sinaliza que o loop deve parar.

Output Keys - Compartilhamento de Estado

Resposta Final: O sub-agente que tiver o Output Key definido como loop_output será usado para gerar a resposta final apresentada ao usuário no fim do loop.

Tipos de agente com Output Key:

• LLM Agent: Salva resposta do modelo de linguagem
• Task Agent: Salva resultado da execução da tarefa
• Workflow Agent: Salva resultado do workflow executado
• A2A Agent: Salva resposta do protocolo Agent-to-Agent

Output Key Especial - loop_output:

• ⭐ loop_output - Sub-agente que gera resposta final apresentada ao usuário
• Este agente é executado após todas as iterações para consolidar resultado
• A resposta deste agente é apresentada ao usuário como resultado final
• Apenas um sub-agente pode ter loop_output como output_key

Como funciona:

1. Configure o Output Key de cada sub-agente
2. O resultado é salvo automaticamente no estado do loop
3. Use placeholders {{output_key_name}} nas instruções para acessar os dados
4. O estado persiste entre todas as iterações do loop
5. Ao final, o agente com loop_output consolida a resposta final

Exemplo de fluxo:

Iteração 1:
- Gerador (output_key: "conteudo") → salva em state.conteudo
- Analisador lê {{user_input}} e {{conteudo}} → analisa e salva em state.analise

Iteração 2:  
- Gerador lê {{user_input}}, {{conteudo}} e {{analise}} → refina e atualiza state.conteudo
- Analisador lê {{conteudo}} atualizado → nova análise

Fim do Loop:
- Finalizador (output_key: "loop_output") → gera resposta final baseado em todo o estado

Quando Usar Loop Agent

Cenários Ideais

✅ Use Loop Agent quando:

• Refinamento iterativo: Melhorar resultado a cada tentativa
• Otimização: Buscar a melhor solução através de iterações
• Validação com retry: Tentar até conseguir resultado válido
• Aprendizado incremental: Melhorar baseado em feedback
• Convergência: Iterar até atingir critério de qualidade

Exemplos práticos:

• Refinamento de conteúdo até atingir qualidade desejada
• Otimização de parâmetros através de tentativas
• Geração de código com correções iterativas
• Negociação com múltiplas rodadas
• Análise com refinamento baseado em feedback

Quando NÃO usar

❌ Evite Loop Agent quando:

• Resultado único: Processo precisa executar apenas uma vez
• Sem melhoria possível: Iterações não agregam valor
• Recursos limitados: Múltiplas execuções são muito custosas
• Tempo crítico: Não há tempo para múltiplas tentativas
• Determinístico: Resultado sempre será o mesmo

Criando um Loop Agent

Passo a Passo na Plataforma

1. Iniciar criação

1. Na tela principal do Evo AI, clique em “New Agent”
2. No campo “Type”, selecione “Loop Agent”
3. Você verá campos específicos para configuração de loop

2. Configurar informações básicas

Name: Nome descritivo do agente de loop

Exemplo: refinador_conteudo_iterativo

Description: Resumo do processo iterativo

Exemplo: Refina conteúdo de marketing através de múltiplas 
iterações até atingir qualidade e efetividade desejadas

Goal: Objetivo do processo iterativo

Exemplo: Produzir conteúdo de alta qualidade através de 
refinamento contínuo baseado em análise e feedback

3. Configurar sub-agentes do loop

Sub-Agents: Adicione os agentes que executarão em cada iteração

💡 Importante: Ordem dos sub-agentes define sequência dentro de cada iteração

🛑 Controle de Parada: Para cada sub-agente, você pode habilitar o uso da tool exit_loop

🎯 Resposta Final: Um sub-agente deve ter output_key: "loop_output" para gerar resposta final

Exemplo de refinamento de conteúdo:

1. Gerador de Conteúdo - Cria ou refina o conteúdo
2. Analisador de Qualidade - Avalia qualidade do conteúdo
3. Coletor de Feedback - Identifica pontos de melhoria
4. Verificador de Critérios - Decide se deve continuar (🛑 pode usar exit_loop)
5. Finalizador - Gera resposta final (🎯 output_key: “loop_output”)

4. Definir instruções de coordenação

Instructions: Como o agente deve coordenar as iterações

# Refinador de Conteúdo Iterativo

Execute iterações de refinamento até atingir qualidade desejada:

## Processo por iteração:
1. **Gerador**: Crie ou refine conteúdo baseado em feedback anterior
2. **Analisador**: Avalie qualidade em múltiplas dimensões
3. **Feedback**: Identifique pontos específicos de melhoria
4. **Verificador**: Determine se qualidade é satisfatória

## Critérios de parada - USE exit_loop quando:
- Score de qualidade >= 8.0 E todas as dimensões >= 7.0
- Melhoria < 0.1 entre iterações consecutivas
- Máximo de 5 iterações atingido

## Como usar exit_loop:

exit_loop()

## Entre iterações:
- Mantenha contexto do conteúdo atual
- Acumule feedback de todas as iterações
- Registre progresso e melhorias
- Evite regressões de qualidade

5. Configurar Output Keys dos sub-agentes

Output Key: Campo disponível para todos os tipos de agente

Tipos de agente que suportam output_key:

• ✅ LLM Agent - Salva resposta do modelo no estado
• ✅ Task Agent - Salva resultado da tarefa no estado
• ✅ Workflow Agent - Salva resultado do workflow no estado
• ✅ A2A Agent - Salva resposta do protocolo A2A no estado

Output Key Especial:

• ⭐ loop_output - Sub-agente que gera resposta final apresentada ao usuário

Como configurar:

Para cada sub-agente, defina onde salvar o resultado:

Gerador de Conteúdo:
- Output Key: "conteudo_atual"

Analisador de Qualidade:  
- Output Key: "analise_qualidade"

Coletor de Feedback:
- Output Key: "feedback_melhoria"

Verificador de Critérios:
- Output Key: "decisao_parada"
- ✅ Pode usar exit_loop: Habilitado

Finalizador Final:
- Output Key: "loop_output"  ⭐
- Função: Gerar resposta final para o usuário

Uso nas instruções:

Use placeholders {{output_key_name}} para acessar dados:

"Analise o pedido: {{user_input}} e este conteúdo: {{conteudo_atual}}"
"Baseado na análise: {{analise_qualidade}}"
"Implemente o feedback: {{feedback_melhoria}}"

Para o Finalizador (loop_output):
"Consolide todo o processo: {{conteudo_atual}}, {{analise_qualidade}}, {{feedback_melhoria}} e gere resposta final para o usuário sobre {{user_input}}"

6. Configurar controle de parada do loop

Controle via Tool exit_loop:

Durante a configuração dos sub-agentes, você seleciona quais podem usar a tool exit_loop. Apenas os sub-agentes habilitados têm o poder de parar o loop.

Configuração na interface:

Para cada sub-agente, você verá uma opção:
✅ "Pode usar exit_loop" - Habilitar/Desabilitar

Exemplo:
- Gerador de Conteúdo: ❌ Não pode parar
- Analisador de Qualidade: ❌ Não pode parar  
- Verificador de Critérios: ✅ Pode parar o loop
- Finalizador: ❌ Não precisa parar (executa no final)

Como funciona:

Apenas sub-agentes com permissão podem usar exit_loop.
O agente deve usar a tool quando a condição de parada for atendida.

Nas instruções do sub-agente habilitado:
"Se critérios de qualidade forem atingidos, use exit_loop()"

Exemplo de instrução para parada:

## Para o Verificador de Critérios
Baseado na análise {{analise_qualidade}}, verifique critérios:

USE exit_loop quando:
- Score de qualidade >= 8.0 E
- Todas as dimensões >= 7.0 E
- Melhoria < 0.1 entre iterações

Exemplo de uso:
exit_loop()

Exemplos Práticos

1. Refinamento de Conteúdo de Marketing

Estrutura do Loop

Objetivo: Refinar conteúdo até atingir alta qualidade e efetividade

Sub-Agentes em cada iteração:

1. Gerador de Conteúdo

• Name: content_generator
• Description: Gera ou refina conteúdo baseado em feedback
• Instructions:

Se primeira iteração:
- Gere conteúdo inicial baseado no pedido {{user_input}}

Se iteração subsequente:
- Refine conteúdo atual baseado no feedback {{feedback_anterior}}
- Mantenha pontos fortes identificados
- Melhore pontos fracos específicos

Foque em: clareza, persuasão, adequação ao público-alvo

• Output Key: conteudo_atual

2. Analisador de Qualidade

• Name: quality_analyzer
• Description: Avalia qualidade do conteúdo em múltiplas dimensões
• Instructions:

Analise o conteúdo gerado em {{conteudo_atual}}:

Dimensões de avaliação (score 1-10):
1. **Clareza**: Mensagem é clara e compreensível?
2. **Persuasão**: Conteúdo é convincente e engajante?
3. **Público-alvo**: Adequado para audiência definida?
4. **Gramática**: Linguagem correta e fluida?
5. **Call-to-action**: CTA é claro e efetivo?

Calcule score médio e identifique pontos fortes/fracos.

• Output Key: analise_qualidade

3. Coletor de Feedback

• Name: feedback_collector
• Description: Identifica melhorias específicas baseado na análise
• Instructions:

Baseado na análise de qualidade {{analise_qualidade}}:

Para cada dimensão com score < 8:
- Identifique problemas específicos
- Sugira melhorias concretas
- Priorize por impacto

Gere feedback acionável para próxima iteração.

• Output Key: feedback_melhoria

4. Verificador de Critérios

• Name: criteria_checker
• Description: Decide se deve continuar iterando ou usar exit_loop
• ✅ Pode usar exit_loop: Habilitado
• Instructions:

Verifique critérios de parada baseado na análise {{analise_qualidade}}:

USE exit_loop se:
- Score médio >= 8.0 E todas as dimensões >= 7.0
- Melhoria desde última iteração < 0.1
- Atingiu máximo de iterações

Exemplo de uso:
exit_loop()

Continue iterando se ainda há potencial de melhoria significativa.

• Output Key: decisao_parada

5. Finalizador

• Name: final_consolidator
• Description: Gera resposta final consolidada para o usuário
• ✅ Pode usar exit_loop: Desabilitado (executa após loop)
• Instructions:

Consolide todo o processo de refinamento para responder ao usuário sobre {{user_input}}:

Baseado em:
- Conteúdo final: {{conteudo_atual}}
- Análise de qualidade: {{analise_qualidade}}
- Feedback aplicado: {{feedback_melhoria}}
- Decisão final: {{decisao_parada}}

Apresente o resultado final de forma clara e completa.

• Output Key: loop_output ⭐

2. Otimização com Diferentes Tipos de Agente

Estrutura do Loop

Objetivo: Otimizar parâmetros usando diferentes tipos de agente

Sub-Agentes em cada iteração:

1. Ajustador de Parâmetros (LLM Agent)

• Type: LLM Agent
• Description: Ajusta parâmetros baseado em performance anterior
• Instructions: Analise o pedido {{user_input}} e performance anterior: {{performance_anterior}}. Ajuste parâmetros para melhorar resultados.
• Output Key: parametros_atuais

2. Simulador de Performance (Task Agent)

• Type: Task Agent
• Description: Executa simulação com novos parâmetros
• Task: Simulação de campanha com parâmetros em {{parametros_atuais}}
• Output Key: performance_simulada

3. Analisador de Dados (A2A Agent)

• Type: A2A Agent
• Description: Analisa dados via protocolo externo
• Endpoint: Sistema de análise que recebe {{performance_simulada}}
• Output Key: analise_detalhada

4. Decisor de Convergência (LLM Agent)

• Type: LLM Agent
• Description: Decide se atingiu otimização satisfatória
• ✅ Pode usar exit_loop: Habilitado
• Instructions: Baseado na análise {{analise_detalhada}}, se melhoria < 5% use exit_loop.
• Output Key: decisao_otimizacao

5. Consolidador Final (LLM Agent)

• Type: LLM Agent
• Description: Gera resposta final com parâmetros otimizados
• ✅ Pode usar exit_loop: Desabilitado
• Instructions: Baseado na otimização completa {{parametros_atuais}} e {{analise_detalhada}}, apresente resultado final para {{user_input}}.
• Output Key: loop_output ⭐

3. Desenvolvimento com Workflow Agents

Estrutura do Loop

Objetivo: Desenvolver código usando workflows complexos

Sub-Agentes em cada iteração:

1. Gerador de Código (LLM Agent)

• Type: LLM Agent
• Description: Gera ou corrige código baseado em requisitos
• Instructions: Baseado no pedido {{user_input}}, gere código para: {{requisitos}}. Se há erros em {{resultados_teste}}, corrija-os.
• Output Key: codigo_atual

2. Pipeline de Testes (Workflow Agent)

• Type: Workflow Agent (Sequential)
• Description: Executa pipeline completo de testes
• Sub-agents: [validador_sintaxe, executor_testes, analisador_cobertura]
• Output Key: resultados_teste

3. Analisador de Qualidade (A2A Agent)

• Type: A2A Agent
• Description: Analisa qualidade via sistema externo
• Endpoint: Sistema de análise de código que recebe {{codigo_atual}}
• Output Key: analise_qualidade

4. Verificador Final (LLM Agent)

• Type: LLM Agent
• Description: Decide se código está pronto
• ✅ Pode usar exit_loop: Habilitado
• Instructions: Analise os resultados {{resultados_teste}} e qualidade {{analise_qualidade}}. Se todos testes passaram e qualidade >= 8, use exit_loop.
• Output Key: verificacao_final

5. Entregador Final (LLM Agent)

• Type: LLM Agent
• Description: Entrega código final ao usuário
• ✅ Pode usar exit_loop: Desabilitado
• Instructions: Apresente o código final {{codigo_atual}} com documentação baseada em {{resultados_teste}} e {{analise_qualidade}} para {{user_input}}.
• Output Key: loop_output ⭐

Configurações Avançadas do Loop

Output Keys - Estado Compartilhado

Configuração de Output Keys

Output Key está disponível para todos os tipos de agente:

LLM Agent:

{
  "type": "llm",
  "model": "gemini-2.0-flash",
  "instructions": "Analise o pedido {{user_input}} e dados {{dados_entrada}}, forneça feedback",
  "config": {
    "output_key": "feedback_analise"
  }
}

Task Agent:

{
  "type": "task", 
  "task_definition": "Processar dados conforme {{user_input}} em {{dados_entrada}}",
  "config": {
    "output_key": "dados_processados"
  }
}

Workflow Agent:

{
  "type": "workflow",
  "workflow_type": "sequential",
  "sub_agents": ["agent1", "agent2"],
  "config": {
    "output_key": "resultado_workflow"
  }
}

A2A Agent:

{
  "type": "a2a",
  "endpoint": "https://api.externa.com/analyze",
  "payload": {"data": "{{dados_entrada}}"},
  "config": {
    "output_key": "resposta_externa"
  }
}

Fluxo de Dados entre Agentes

Como os dados fluem no loop:

Estado inicial:
{
  "requisitos": "Criar função de ordenação",
  "linguagem": "Python"
}

Após Agente 1 (output_key: "codigo"):
{
  "requisitos": "Criar função de ordenação",
  "linguagem": "Python", 
  "codigo": "def ordenar(lista): return sorted(lista)"
}

Após Agente 2 (output_key: "testes"):
{
  "requisitos": "Criar função de ordenação",
  "linguagem": "Python",
  "codigo": "def ordenar(lista): return sorted(lista)",
  "testes": "Todos os testes passaram"
}

Placeholders automáticos:

• Use {{codigo}} para acessar resultado do agente anterior
• Use {{testes}} para acessar resultado dos testes
• Use {{requisitos}} para acessar dados iniciais
• Todos os dados persistem entre iterações

Boas Práticas para Output Keys

Nomenclatura:

• Use snake_case: resultado_analise, dados_processados
• Seja descritivo: feedback_qualidade em vez de feedback
• Evite conflitos: não use nomes já existentes no estado

Estrutura de dados:

• Mantenha dados estruturados quando possível
• Use JSON para dados complexos
• Documente formato esperado nas instruções

Performance:

• Evite salvar dados muito grandes desnecessariamente
• Limpe dados temporários quando não precisar mais
• Use output_key apenas quando dados serão reutilizados

Controle de Parada com exit_loop

Como usar a tool exit_loop

A tool exit_loop é automaticamente disponibilizada para o agente e deve ser usada nas instruções para controlar quando parar o loop.

1. Score-based Stop:

# Nas instruções do agente:
Use exit_loop quando score atingir threshold:

if quality_score >= 8.0:
    exit_loop()

2. Improvement-based Stop:

# Nas instruções do agente:
Use exit_loop quando melhoria for mínima:

if improvement < 0.1:
    exit_loop()

3. Criteria-based Stop:

# Nas instruções do agente:
Use exit_loop quando todos os critérios forem atendidos:

if all_criteria_met:
    exit_loop()

4. Custom Condition:

# Nas instruções do agente:
Use exit_loop para condições personalizadas:

if custom_business_rule_satisfied:
    exit_loop()

Controle de Tempo

Timeouts por nível:

Iteration Timeout: Tempo limite por iteração

- Padrão: 300s (5 minutos)
- Complexo: 600s (10 minutos)
- Simples: 120s (2 minutos)

Total Loop Timeout: Tempo limite total do loop

- Padrão: 1800s (30 minutos)
- Longo: 3600s (1 hora)
- Rápido: 900s (15 minutos)

Sub-Agent Timeout: Tempo limite por sub-agente

- Baseado na complexidade de cada sub-agente
- Permite configuração individual
- Failover para próximo sub-agente

Monitoramento de Convergência

Métricas de convergência:

Progress Tracking:

Iteration 1: Score 5.2 → Improvement: N/A
Iteration 2: Score 6.8 → Improvement: +1.6 (30.8%)
Iteration 3: Score 7.4 → Improvement: +0.6 (8.8%)
Iteration 4: Score 7.6 → Improvement: +0.2 (2.7%)

Convergence detected: Improvement < 5%

Trend Analysis:

• Detecta tendências de melhoria
• Identifica platôs de performance
• Prevê número de iterações necessárias
• Sugere ajustes de parâmetros

Estratégias de Otimização

Performance do Loop

Otimizações de velocidade:

Cache Inteligente:

- Cache resultados de sub-agentes determinísticos
- Evite reprocessar dados idênticos
- Invalide cache quando necessário

Early Termination:

- Pare assim que critério for atingido
- Não execute sub-agentes desnecessários
- Monitore progresso em tempo real

Adaptive Timeouts:

- Ajuste timeouts baseado em performance histórica
- Reduza timeouts para iterações rápidas
- Aumente para iterações complexas

Gestão de Memória

Controle de estado entre iterações:

State Management:

- Mantenha apenas dados essenciais
- Limpe dados temporários entre iterações
- Comprima histórico de iterações antigas

Memory Limits:

- Limite memória por iteração
- Garbage collection entre iterações
- Alertas para uso excessivo de memória

Data Persistence:

- Salve checkpoints a cada iteração
- Permita restart do ponto de falha
- Mantenha audit trail completo

Monitoramento e Debugging

Acompanhando Iterações

Dashboard de Loop

Visualização em tempo real:

Loop Agent: refinador_conteudo_iterativo

Current Iteration: 3/5
Elapsed Time: 8m 32s

Progress by Iteration:
├── Iteration 1: Score 5.2 [COMPLETED] 2m 15s
├── Iteration 2: Score 6.8 [COMPLETED] 2m 45s
├── Iteration 3: Score 7.4 [RUNNING]   3m 32s
│   ├── content_generator    [COMPLETED] ✓
│   ├── quality_analyzer     [COMPLETED] ✓
│   ├── feedback_collector   [RUNNING]   
│   └── criteria_checker     [PENDING]   

Convergence Trend: ↗️ Improving
Estimated Completion: 2 more iterations

Debugging de Loops

Problemas comuns:

1. Loop Infinito

Sintoma: Nunca atinge critério de parada
Causa: Critério muito rigoroso ou inalcançável
Solução: Ajustar thresholds ou adicionar max iterations

2. Convergência Lenta

Sintoma: Muitas iterações com pouca melhoria
Causa: Feedback insuficiente ou sub-agentes ineficazes
Solução: Melhorar qualidade do feedback ou ajustar sub-agentes

3. Regressão de Qualidade

Sintoma: Score diminui em iterações posteriores
Causa: Feedback contraditório ou overfitting
Solução: Implementar validação de regressão

4. Timeout Frequente

Sintoma: Iterações frequentemente excedem tempo limite
Causa: Sub-agentes muito lentos ou timeouts muito baixos
Solução: Otimizar sub-agentes ou ajustar timeouts

Melhores Práticas

Design de Loops Eficazes

Princípios fundamentais:

• Feedback de qualidade: Cada iteração deve fornecer feedback específico e acionável
• Critérios claros com exit_loop: Defina nas instruções quando usar exit_loop
• Múltiplas condições de parada: Implemente várias condições com exit_loop
• Monitoramento de progresso: Acompanhe métricas de melhoria
• Validação de regressão: Evite que iterações piorem o resultado
• Documentação da parada: Use o parâmetro reason para explicar por que parou

Otimização de Convergência

Estratégias para convergência rápida:

• Feedback incremental: Foque em uma melhoria por vez
• Priorização: Aborde problemas mais impactantes primeiro
• Adaptive learning: Ajuste estratégia baseado em progresso
• Early stopping: Pare quando melhoria marginal for baixa
• Quality gates: Valide qualidade mínima a cada iteração

Robustez e Confiabilidade

Garantindo execução estável:

• Error handling: Trate falhas de sub-agentes graciosamente
• State persistence: Salve estado entre iterações
• Recovery mechanisms: Permita restart de pontos de falha
• Resource management: Monitore uso de CPU, memória e tempo
• Circuit breakers: Evite cascata de falhas

Casos de Uso Comuns

Criação de Conteúdo

Refinamento Iterativo:

• Melhoria de textos até qualidade desejada
• Otimização de copy para conversão
• Refinamento de propostas comerciais

Otimização

Busca de Parâmetros Ótimos:

• Tuning de campanhas de marketing
• Otimização de preços
• Ajuste de configurações de sistema

Desenvolvimento

Geração e Correção:

• Geração de código com testes iterativos
• Refinamento de algoritmos
• Correção automática de bugs

Negociação

Processos Iterativos:

• Negociação automática de contratos
• Refinamento de propostas
• Otimização de termos comerciais

Próximos Passos

Sequential Agent

Aprenda sobre execução sequencial ordenada

Parallel Agent

Explore execução paralela de sub-agentes

Agente LLM

Volte aos fundamentos dos agentes inteligentes

Configurações

Explore configurações avançadas de agentes

---

O Loop Agent é perfeito para processos que precisam de refinamento contínuo e melhoria iterativa. Use-o quando quiser atingir alta qualidade através de múltiplas tentativas e feedback constante.