> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evo-ai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  **Baseado no Google ADK**: Implementação seguindo os padrões do [Google Agent Development Kit](https://google.github.io/adk-docs/agents/multi-agents/) para agentes iterativos.
</Note>

## Características Principais

<CardGroup cols={2}>
  <Card title="Execução Iterativa" icon="recycle">
    Repete execução dos sub-agentes até condição de parada
  </Card>

  <Card title="Melhoria Contínua" icon="chart-line">
    Cada iteração pode melhorar o resultado baseado no anterior
  </Card>

  <Card title="Tool exit_loop" icon="stop">
    Controle de parada via tool automática nas instruções
  </Card>

  <Card title="Flexibilidade Total" icon="sliders">
    Critérios de parada personalizáveis via instruções
  </Card>
</CardGroup>

## Tool exit\_loop - Controle de Parada

<Note>
  **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.
</Note>

**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:**

```markdown theme={null}
exit_loop()
```

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

## Output Keys - Compartilhamento de Estado

<Note>
  **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.
</Note>

**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:**

```markdown theme={null}
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

<AccordionGroup>
  <Accordion icon="check" title="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
  </Accordion>

  <Accordion icon="x" title="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
  </Accordion>
</AccordionGroup>

## Criando um Loop Agent

### Passo a Passo na Plataforma

<AccordionGroup>
  <Accordion icon="robot" title="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

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/evoai/images/prints/loop_agent_creation.png" alt="Criando Loop Agent" />
  </Accordion>

  <Accordion icon="gear" title="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
    ```
  </Accordion>

  <Accordion icon="recycle" title="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"**)

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/evoai/images/prints/loop_sub_agents.png" alt="Configurando Sub-Agentes do Loop" />
  </Accordion>

  <Accordion icon="file" title="4. Definir instruções de coordenação">
    **Instructions:** Como o agente deve coordenar as iterações

    ```markdown theme={null}
    # 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
    ```
  </Accordion>

  <Accordion icon="database" title="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:**

    ```markdown theme={null}
    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:**

    ```markdown theme={null}
    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}}"
    ```

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/evoai/images/prints/output_keys_config.png" alt="Configurando Output Keys" />
  </Accordion>

  <Accordion icon="gear" title="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:**

    ```markdown theme={null}
    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:**

    ```markdown theme={null}
    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:**

    ```markdown theme={null}
    ## 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()
    ```

    <img src="https://mintlify.s3.us-west-1.amazonaws.com/evoai/images/prints/loop_agent_config.png" alt="Configurações do Loop Agent" />
  </Accordion>
</AccordionGroup>

## Exemplos Práticos

### 1. Refinamento de Conteúdo de Marketing

<AccordionGroup>
  <Accordion icon="pencil" title="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:**

    ```markdown theme={null}
    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:**

    ```markdown theme={null}
    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:**

    ```markdown theme={null}
    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:**

    ```markdown theme={null}
    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:**

    ```markdown theme={null}
    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` ⭐
  </Accordion>
</AccordionGroup>

### 2. Otimização com Diferentes Tipos de Agente

<AccordionGroup>
  <Accordion icon="sliders" title="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` ⭐
  </Accordion>
</AccordionGroup>

### 3. Desenvolvimento com Workflow Agents

<AccordionGroup>
  <Accordion icon="code" title="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` ⭐
  </Accordion>
</AccordionGroup>

## Configurações Avançadas do Loop

### Output Keys - Estado Compartilhado

<AccordionGroup>
  <Accordion icon="database" title="Configuração de Output Keys">
    **Output Key está disponível para todos os tipos de agente:**

    **LLM Agent:**

    ```json theme={null}
    {
      "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:**

    ```json theme={null}
    {
      "type": "task", 
      "task_definition": "Processar dados conforme {{user_input}} em {{dados_entrada}}",
      "config": {
        "output_key": "dados_processados"
      }
    }
    ```

    **Workflow Agent:**

    ```json theme={null}
    {
      "type": "workflow",
      "workflow_type": "sequential",
      "sub_agents": ["agent1", "agent2"],
      "config": {
        "output_key": "resultado_workflow"
      }
    }
    ```

    **A2A Agent:**

    ```json theme={null}
    {
      "type": "a2a",
      "endpoint": "https://api.externa.com/analyze",
      "payload": {"data": "{{dados_entrada}}"},
      "config": {
        "output_key": "resposta_externa"
      }
    }
    ```
  </Accordion>

  <Accordion icon="arrow-right-arrow-left" title="Fluxo de Dados entre Agentes">
    **Como os dados fluem no loop:**

    ```markdown theme={null}
    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
  </Accordion>

  <Accordion icon="shield-check" title="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
  </Accordion>
</AccordionGroup>

### Controle de Parada com exit\_loop

<AccordionGroup>
  <Accordion icon="stop" title="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:**

    ```markdown theme={null}
    # Nas instruções do agente:
    Use exit_loop quando score atingir threshold:

    if quality_score >= 8.0:
        exit_loop()
    ```

    **2. Improvement-based Stop:**

    ```markdown theme={null}
    # Nas instruções do agente:
    Use exit_loop quando melhoria for mínima:

    if improvement < 0.1:
        exit_loop()
    ```

    **3. Criteria-based Stop:**

    ```markdown theme={null}
    # Nas instruções do agente:
    Use exit_loop quando todos os critérios forem atendidos:

    if all_criteria_met:
        exit_loop()
    ```

    **4. Custom Condition:**

    ```markdown theme={null}
    # Nas instruções do agente:
    Use exit_loop para condições personalizadas:

    if custom_business_rule_satisfied:
        exit_loop()
    ```
  </Accordion>

  <Accordion icon="clock" title="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
    ```
  </Accordion>

  <Accordion icon="chart-line" title="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
  </Accordion>
</AccordionGroup>

### Estratégias de Otimização

<AccordionGroup>
  <Accordion icon="rocket" title="Performance do Loop">
    **Otimizações de velocidade:**

    **Cache Inteligente:**

    ```markdown theme={null}
    - Cache resultados de sub-agentes determinísticos
    - Evite reprocessar dados idênticos
    - Invalide cache quando necessário
    ```

    **Early Termination:**

    ```markdown theme={null}
    - Pare assim que critério for atingido
    - Não execute sub-agentes desnecessários
    - Monitore progresso em tempo real
    ```

    **Adaptive Timeouts:**

    ```markdown theme={null}
    - Ajuste timeouts baseado em performance histórica
    - Reduza timeouts para iterações rápidas
    - Aumente para iterações complexas
    ```
  </Accordion>

  <Accordion icon="memory" title="Gestão de Memória">
    **Controle de estado entre iterações:**

    **State Management:**

    ```markdown theme={null}
    - Mantenha apenas dados essenciais
    - Limpe dados temporários entre iterações
    - Comprima histórico de iterações antigas
    ```

    **Memory Limits:**

    ```markdown theme={null}
    - Limite memória por iteração
    - Garbage collection entre iterações
    - Alertas para uso excessivo de memória
    ```

    **Data Persistence:**

    ```markdown theme={null}
    - Salve checkpoints a cada iteração
    - Permita restart do ponto de falha
    - Mantenha audit trail completo
    ```
  </Accordion>
</AccordionGroup>

## Monitoramento e Debugging

### Acompanhando Iterações

<AccordionGroup>
  <Accordion icon="chart-line" title="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
    ```
  </Accordion>

  <Accordion icon="bug" title="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
    ```
  </Accordion>
</AccordionGroup>

## Melhores Práticas

<AccordionGroup>
  <Accordion icon="lightbulb" title="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
  </Accordion>

  <Accordion icon="bullseye" title="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
  </Accordion>

  <Accordion icon="shield-check" title="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
  </Accordion>
</AccordionGroup>

## Casos de Uso Comuns

<CardGroup cols={2}>
  <Card title="Criação de Conteúdo" icon="pencil">
    **Refinamento Iterativo:**

    * Melhoria de textos até qualidade desejada
    * Otimização de copy para conversão
    * Refinamento de propostas comerciais
  </Card>

  <Card title="Otimização" icon="sliders">
    **Busca de Parâmetros Ótimos:**

    * Tuning de campanhas de marketing
    * Otimização de preços
    * Ajuste de configurações de sistema
  </Card>

  <Card title="Desenvolvimento" icon="code">
    **Geração e Correção:**

    * Geração de código com testes iterativos
    * Refinamento de algoritmos
    * Correção automática de bugs
  </Card>

  <Card title="Negociação" icon="handshake">
    **Processos Iterativos:**

    * Negociação automática de contratos
    * Refinamento de propostas
    * Otimização de termos comerciais
  </Card>
</CardGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Sequential Agent" icon="arrow-right" href="/agents/sequential">
    Aprenda sobre execução sequencial ordenada
  </Card>

  <Card title="Parallel Agent" icon="arrow-right-arrow-left" href="/agents/parallel">
    Explore execução paralela de sub-agentes
  </Card>

  <Card title="Agente LLM" icon="brain" href="/agents/llm">
    Volte aos fundamentos dos agentes inteligentes
  </Card>

  <Card title="Configurações" icon="gear" href="/configurations/index">
    Explore configurações avançadas de agentes
  </Card>
</CardGroup>

***

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.
