Sequential Agent

Configure agentes que executam sub-agentes em sequência ordenada para processos estruturados

Visão Geral

O Sequential Agent é um tipo de agente de workflow que executa sub-agentes em uma sequência predefinida e ordenada. Cada sub-agente é executado apenas após o anterior ter completado sua tarefa com sucesso, criando um pipeline de processamento estruturado.

Este tipo de agente é ideal para processos que precisam seguir etapas específicas, onde cada etapa depende do resultado da anterior, como pipelines de aprovação, processamento de dados em etapas ou workflows de validação.

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

Características Principais

Execução Ordenada

Sub-agentes executam em ordem específica, um após o outro

Dependência Sequencial

Cada etapa depende do sucesso da etapa anterior

Contexto Compartilhado

Dados passam de um sub-agente para o próximo automaticamente

Controle de Falhas

Pipeline para se uma etapa falhar, evitando processamento desnecessário

Quando Usar Sequential Agent

Cenários Ideais

✅ Use Sequential Agent quando:

• Processos com etapas dependentes: Cada etapa precisa do resultado da anterior
• Pipelines de aprovação: Validações em cascata
• Processamento de dados: Transformações sequenciais
• Workflows de validação: Verificações em ordem específica
• Processos de onboarding: Etapas que devem ser completadas em ordem

Exemplos práticos:

• Pipeline de processamento de pedidos
• Workflow de aprovação de documentos
• Processo de análise de leads
• Sistema de verificação de qualidade
• Fluxo de integração de novos usuários

Quando NÃO usar

❌ Evite Sequential Agent quando:

• Tarefas independentes: Sub-agentes não dependem uns dos outros
• Processamento paralelo: Velocidade é mais importante que ordem
• Workflows flexíveis: Ordem pode variar baseada em condições
• Tarefas simples: Um único agente LLM seria suficiente

Criando um Sequential 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 “Sequential Agent”
3. Você verá campos específicos para configuração sequencial

2. Configurar informações básicas

Name: Nome descritivo do pipeline

Exemplo: pipeline_processamento_pedidos

Description: Resumo do processo sequencial

Exemplo: Pipeline completo para processar pedidos desde 
validação até confirmação de entrega

Goal: Objetivo do pipeline sequencial

Exemplo: Processar pedidos de forma estruturada e confiável, 
garantindo todas as validações necessárias

3. Configurar sub-agentes em ordem

Sub-Agents: Adicione os agentes na ordem de execução

⚠️ Importante: A ordem dos sub-agentes define a sequência de execução

Exemplo de pipeline de pedidos:

1. Validador de Dados - Verifica informações do pedido
2. Verificador de Estoque - Confirma disponibilidade
3. Calculador de Preços - Calcula valores e descontos
4. Processador de Pagamento - Processa transação
5. Agendador de Entrega - Define logística

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

Instructions: Como o agente deve coordenar a sequência

# Pipeline de Processamento de Pedidos

Execute os sub-agentes na ordem definida para processar pedidos:

## Sequência de execução:
1. **Validador**: Valide dados do pedido
2. **Estoque**: Verifique disponibilidade dos produtos
3. **Preços**: Calcule valores finais com descontos
4. **Pagamento**: Processe a transação financeira
5. **Entrega**: Agende logística de entrega

## Regras importantes:
- Pare a execução se qualquer etapa falhar
- Passe contexto completo entre etapas
- Registre progresso de cada etapa
- Notifique sobre falhas imediatamente

## Em caso de falha:
- Identifique a etapa que falhou
- Forneça detalhes específicos do erro
- Sugira ações corretivas quando possível

5. Configurações avançadas

Timeout por Etapa: Tempo limite para cada sub-agente

Recomendado: 300 segundos (5 minutos)

Retry Policy: Política de tentativas em caso de falha

Opções: No Retry / Retry Once / Retry Twice

Error Handling: Como tratar erros

- Stop on First Error (recomendado)
- Continue on Non-Critical Errors
- Log and Continue

Output Aggregation: Como combinar resultados

- Combine All Outputs
- Last Agent Output Only
- Custom Aggregation

Exemplos Práticos

1. Pipeline de Processamento de Pedidos

Estrutura do Pipeline

Objetivo: Processar pedidos de e-commerce de forma estruturada

Sub-Agentes em sequência:

1. Validador de Pedidos

• Name: order_validator
• Description: Valida dados do pedido e informações do cliente
• Instructions:

Valide o pedido recebido:
- Dados do cliente completos e válidos
- Produtos existem no catálogo
- Quantidades são válidas
- Endereço de entrega está correto

Se tudo estiver válido, passe para próxima etapa.
Se houver erro, pare o pipeline e informe detalhes.

2. Verificador de Estoque

• Name: inventory_checker
• Description: Verifica disponibilidade dos produtos em estoque
• Instructions:

Verifique estoque para o pedido validado:
- Confirme disponibilidade de cada produto
- Verifique quantidades solicitadas
- Reserve produtos se disponível
- Sugira alternativas se indisponível

3. Calculador de Preços

• Name: price_calculator
• Description: Calcula preços finais com descontos e impostos
• Instructions:

Calcule valores do pedido:
- Preço base dos produtos
- Descontos aplicáveis
- Impostos e taxas
- Frete baseado no endereço
- Valor total final

4. Processador de Pagamento

• Name: payment_processor
• Description: Processa pagamento do pedido
• Instructions:

Processe o pagamento:
- Valide método de pagamento
- Execute transação
- Confirme aprovação
- Gere comprovante

5. Agendador de Entrega

• Name: delivery_scheduler
• Description: Agenda entrega do pedido
• Instructions:

Agende a entrega:
- Calcule prazo de entrega
- Defina transportadora
- Gere código de rastreamento
- Envie confirmação ao cliente

2. Pipeline de Análise de Leads

Estrutura do Pipeline

Objetivo: Analisar e qualificar leads de vendas

Sub-Agentes em sequência:

1. Enriquecedor de Dados

• Name: data_enricher
• Description: Enriquece dados do lead com informações públicas
• Output Key: enriched_data

2. Pontuador de Leads

• Name: lead_scorer
• Description: Calcula score do lead baseado em critérios
• Instructions: Analise o pedido {{user_input}} e use dados de {{enriched_data}} para calcular score
• Output Key: lead_score

3. Classificador

• Name: lead_classifier
• Description: Classifica lead como HOT/WARM/COLD
• Instructions: Classifique baseado no {{lead_score}}
• Output Key: classification

4. Roteador

• Name: lead_router
• Description: Direciona lead para vendedor adequado
• Instructions: Route baseado na {{classification}}
• Output Key: assignment

3. Pipeline de Aprovação de Documentos

Estrutura do Pipeline

Objetivo: Aprovar documentos através de múltiplas validações

Sub-Agentes em sequência:

1. Verificador de Formato

• Valida formato e estrutura do documento

2. Analisador de Conteúdo

• Analisa conteúdo e completude

3. Verificador de Compliance

• Verifica conformidade com regulamentações

4. Aprovador Final

• Toma decisão final de aprovação

5. Notificador

• Envia notificações sobre o resultado

Monitoramento e Debugging

Acompanhando a Execução

Dashboard de Monitoramento

Métricas importantes:

• Progresso atual: Qual etapa está executando
• Tempo por etapa: Duração de cada sub-agente
• Taxa de sucesso: Percentual de pipelines completados
• Pontos de falha: Onde o pipeline falha mais
• Throughput: Quantos pipelines por hora

Visualização em tempo real:

• Status de cada etapa (Pending/Running/Completed/Failed)
• Logs detalhados de cada sub-agente
• Dados passados entre etapas

Debugging de Falhas

Quando um pipeline falha:

1. Identifique a etapa: Qual sub-agente falhou
2. Analise os logs: Mensagens de erro específicas
3. Verifique dados: Input recebido pelo sub-agente
4. Teste isoladamente: Execute o sub-agente separadamente
5. Ajuste configuração: Modifique instruções se necessário

Logs úteis:

[SEQUENTIAL] Starting pipeline: pipeline_processamento_pedidos
[STEP 1/5] Executing: order_validator
[STEP 1/5] Completed successfully
[STEP 2/5] Executing: inventory_checker
[STEP 2/5] ERROR: Product XYZ not found in inventory
[SEQUENTIAL] Pipeline stopped due to error in step 2

Configurações Avançadas

Controle de Fluxo

Conditional Steps

Etapas condicionais baseadas em resultados:

# Pipeline com Condições

Execute etapas baseado em condições:

1. **Analisador**: Sempre execute
2. **Aprovador Simples**: Se valor < R$ 1000
3. **Aprovador Gerencial**: Se valor >= R$ 1000
4. **Notificador**: Sempre execute

Analise o pedido inicial {{user_input}} e use {{valor_pedido}} para decidir o fluxo.

Timeouts e Retries

Configuração de tempo e tentativas:

• Step Timeout: 300s (padrão)
• Total Pipeline Timeout: 1800s (30 min)
• Retry Policy: Retry once on failure
• Retry Delay: 30s between retries

Para etapas críticas:

• Aumente timeout para operações complexas
• Configure retry apenas para falhas temporárias
• Use circuit breaker para falhas persistentes

Persistência de Estado

Salvando progresso:

• Checkpoint após cada etapa: Permite restart do ponto de falha
• Estado compartilhado: Dados disponíveis para todas as etapas
• Rollback capability: Desfazer etapas se necessário
• Audit trail: Histórico completo de execução

Output Key - Resultado do Workflow

Campo Output Key na interface:

O Output Key permite que o Sequential Agent salve o resultado final do workflow sequencial em uma variável específica no estado compartilhado, tornando-o disponível para outros agentes ou processos.

Como funciona:

• Configure o campo Output Key com um nome descritivo
• O resultado final do workflow será salvo automaticamente nessa variável
• Outros agentes podem acessar usando placeholders {{output_key_name}}
• Funciona em workflows aninhados, loops e sistemas multi-agente

Exemplos de configuração:

Output Key: "pedido_processado"
→ Salva resultado final em state.pedido_processado

Output Key: "aprovacao_completa"
→ Salva resultado final em state.aprovacao_completa

Output Key: "pipeline_etl_resultado"
→ Salva resultado final em state.pipeline_etl_resultado

Resultado consolidado:

# O Sequential Agent automaticamente:
- Coleta resultados de todos os sub-agentes
- Consolida em um resultado final estruturado
- Inclui status de cada etapa
- Salva no estado com a chave especificada

Uso em outros agentes:

# Nas instruções de agentes subsequentes:
"Analise o pedido original: {{user_input}} e use o pedido processado: {{pedido_processado}}"
"Baseado na aprovação: {{aprovacao_completa}}"
"Analise os resultados: {{pipeline_etl_resultado}}"

Boas práticas:

• Use snake_case: workflow_resultado, processo_completo
• Seja específico: aprovacao_credito_resultado em vez de resultado
• Documente estrutura do resultado final
• Considere incluir metadados (tempo, status, etapas)
• Use nomes que reflitam o processo completo

Melhores Práticas

Design do Pipeline

Princípios fundamentais:

• Etapas atômicas: Cada sub-agente deve ter uma responsabilidade clara
• Idempotência: Executar a mesma etapa múltiplas vezes deve ser seguro
• Validação precoce: Falhe rápido em dados inválidos
• Logging detalhado: Registre entrada e saída de cada etapa
• Timeouts apropriados: Evite etapas que ficam “presas”

Tratamento de Erros

Estratégias de recuperação:

• Fail fast: Pare imediatamente em erros críticos
• Graceful degradation: Continue com funcionalidade reduzida quando possível
• Retry logic: Tente novamente apenas para falhas temporárias
• Circuit breaker: Evite cascata de falhas
• Dead letter queue: Armazene falhas para análise posterior

Performance

Otimização de velocidade:

• Minimize transferência de dados: Passe apenas dados necessários
• Cache resultados: Evite recalcular dados estáticos
• Paralelização interna: Use parallel processing dentro de etapas quando possível
• Monitoring: Identifique gargalos através de métricas
• Load balancing: Distribua carga entre instâncias

Casos de Uso Comuns

E-commerce

Pipeline de Pedidos:

• Validação → Estoque → Preço → Pagamento → Entrega
• Garantia de ordem e dependências

Aprovações

Workflow de Aprovação:

• Análise → Revisão → Aprovação → Notificação
• Controle de qualidade estruturado

Onboarding

Integração de Usuários:

• Registro → Verificação → Setup → Treinamento
• Experiência guiada passo a passo

Análise de Dados

Pipeline de ETL:

• Extract → Transform → Validate → Load
• Processamento estruturado de dados

Próximos Passos

Parallel Agent

Aprenda sobre execução paralela de sub-agentes

Loop Agent

Explore agentes que executam em loop iterativo

Agente LLM

Volte aos fundamentos dos agentes inteligentes

Configurações

Explore configurações avançadas de agentes

---

O Sequential Agent é fundamental para criar workflows estruturados e confiáveis. Use-o quando precisar garantir que etapas sejam executadas em ordem específica, com cada etapa dependendo do sucesso da anterior.