> ## 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. # 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](https://google.github.io/adk-docs/agents/multi-agents/) para agentes sequenciais. ## Características Principais Sub-agentes executam em ordem específica, um após o outro Cada etapa depende do sucesso da etapa anterior Dados passam de um sub-agente para o próximo automaticamente Pipeline para se uma etapa falhar, evitando processamento desnecessário ## Quando Usar Sequential Agent **✅ 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 **❌ 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. 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 Criando Sequential Agent **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 ``` **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 Configurando Sub-Agentes Sequenciais **Instructions:** Como o agente deve coordenar a sequência ```markdown theme={null} # 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 ``` **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 **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:** ```markdown theme={null} 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:** ```markdown theme={null} 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:** ```markdown theme={null} 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:** ```markdown theme={null} 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:** ```markdown theme={null} 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 **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 **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 **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 **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 **Etapas condicionais baseadas em resultados:** ```markdown theme={null} # 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. ``` **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 **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 **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:** ```markdown theme={null} 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:** ```markdown theme={null} # 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:** ```markdown theme={null} # 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 **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" **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 **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 **Pipeline de Pedidos:** * Validação → Estoque → Preço → Pagamento → Entrega * Garantia de ordem e dependências **Workflow de Aprovação:** * Análise → Revisão → Aprovação → Notificação * Controle de qualidade estruturado **Integração de Usuários:** * Registro → Verificação → Setup → Treinamento * Experiência guiada passo a passo **Pipeline de ETL:** * Extract → Transform → Validate → Load * Processamento estruturado de dados ## Próximos Passos Aprenda sobre execução paralela de sub-agentes Explore agentes que executam em loop iterativo Volte aos fundamentos dos agentes inteligentes 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.