O que é um Fluxo de Trabalho Agêntico? Como Construir um que Planeja, Age e Avalia

Um fluxo de trabalho agêntico é um sistema de múltiplas etapas onde um modelo de linguagem faz mais do que responder uma vez: ele planeja, escolhe ferramentas, executa ações, verifica o resultado e decide o que fazer a seguir até que a tarefa seja concluída. Na prática, isso significa combinar uma camada de raciocínio do LLM com chamadas de ferramentas, um ambiente de execução real e um loop de avaliação. Se você está construindo agentes de codificação, agentes de pesquisa ou automação interna que precisa se adaptar durante a tarefa, esta é geralmente a arquitetura que você está realmente construindo.

O que é um fluxo de trabalho agêntico?

Um fluxo de trabalho agêntico é o padrão por trás de sistemas de IA que podem avançar em uma tarefa em vez de parar na geração de texto. Em vez de pedir ao modelo uma única resposta e retorná-la ao usuário, você permite que o modelo opere dentro de um loop controlado:

1. Ler o objetivo e o estado atual.
2. Planejar o próximo passo.
3. Chamar uma ferramenta ou executar código.
4. Observar o resultado.
5. Avaliar se a tarefa está completa.
6. Repetir se necessário.

Isso é diferente de um fluxo de trabalho fixo, onde cada etapa é pré-escrita em código. Em um fluxo de trabalho fixo, você decide o caminho com antecedência. Em um fluxo de trabalho agêntico, o modelo decide qual ação tomar a seguir dentro dos limites que você fornece.

Essa distinção é importante porque muitas tarefas reais de desenvolvimento não são lineares. Um agente de codificação pode precisar inspecionar arquivos antes de saber qual teste executar. Um agente de pesquisa pode precisar pesquisar duas vezes porque a primeira fonte estava incompleta. Um agente de navegador pode precisar se recuperar de uma falha de login ou de um layout de página alterado. Esses são problemas de fluxo de trabalho, mas exigem adaptação.

Como um fluxo de trabalho agêntico é diferente de um agente de IA?

As pessoas costumam usar os dois termos de forma intercambiável, mas é mais útil separá-los:

• Um fluxo de trabalho agêntico é o padrão de execução.
• Um agente de IA é o produto ou sistema construído sobre esse padrão.

Você pode ter um fluxo de trabalho agêntico de escopo restrito que apenas tria tickets de suporte, ou um agente de IA mais amplo que coordena planejamento, uso de ferramentas, memória e pontos de verificação de aprovação em muitas tarefas.

Se você quiser uma regra prática, use fluxo de trabalho quando estiver falando sobre arquitetura e fluxo de controle, e use agente quando estiver falando sobre o sistema voltado para o usuário.

Quais são as partes principais de um fluxo de trabalho agêntico?

A maioria dos sistemas de produção acaba tendo as mesmas cinco partes.

1. Planejador

O planejador transforma uma instrução ampla na próxima ação concreta. Às vezes, isso é uma etapa de planejamento explícita que gera uma lista de tarefas. Às vezes, é implícito e acontece dentro de cada turno de chamada de ferramenta. De qualquer forma, o modelo precisa de contexto suficiente para decidir se deve ler, escrever, pesquisar, executar ou parar.

Um bom planejamento não significa gerar um esboço longo para cada solicitação. Significa manter o próximo movimento legível. Para tarefas curtas, o planejamento de uma etapa é suficiente. Para tarefas mais longas, como refatorações de repositório, automação de navegador ou revisão de documentos, um plano explícito reduz a oscilação.

2. Camada de ferramentas

As ferramentas são a interface do fluxo de trabalho com o mundo. Uma camada de ferramentas forte é geralmente estreita e previsível. Por exemplo:

• read_file(caminho)
• write_file(caminho, conteudo)
• search_files(consulta)
• run_command(comando)
• fetch_url(url)

Ferramentas pequenas são mais fáceis para o modelo chamar corretamente, mais fáceis de registrar e mais fáceis de proteger. Ferramentas grandes que “fazem tudo” parecem convenientes no início, mas se tornam difíceis de depurar porque você não consegue dizer se as falhas vieram da decisão do modelo, da implementação da ferramenta ou do sistema externo por trás dela.

3. Runtime de execução

Depois que o modelo decide agir, algo precisa executar a ação. Para qualquer fluxo de trabalho que escreve arquivos, instala pacotes, executa código ou abre sessões de navegador, esse runtime precisa de isolamento.

É aí que entra um sandbox. O Novita Agent Sandbox é projetado para esta camada de execução: um ambiente separado onde as ações do agente podem ser executadas sem tocar diretamente no sistema host. Esta é a diferença entre “o modelo sugeriu um comando” e “o fluxo de trabalho executou esse comando com segurança.”

4. Estado e memória

Um fluxo de trabalho agêntico precisa de memória de trabalho entre as etapas. Isso geralmente inclui:

• estado da conversa
• saídas das ferramentas
• arquivos intermediários
• logs de execução
• um rascunho ou plano curto

Sem estado, cada etapa se torna uma engenharia de prompt sem estado, e o sistema desmorona assim que a tarefa abrange mais de uma ação.

5. Loop de avaliação

Esta é a parte que muitas equipes adicionam tarde demais. O fluxo de trabalho precisa de uma maneira de julgar se uma etapa foi bem-sucedida e se a tarefa está concluída. Em um fluxo de trabalho de codificação, isso pode significar que os testes passam. Em um fluxo de trabalho de pesquisa, pode significar que a resposta cita fontes confiáveis suficientes. Em um fluxo de trabalho de navegador, pode significar que o estado esperado da interface do usuário está visível.

Sem avaliação, “agêntico” muitas vezes se transforma em “continua chamando ferramentas até o tempo limite.”

Por que o planejamento é importante na construção de fluxos de trabalho agênticos

O maior erro na construção de fluxos de trabalho agênticos é assumir que o modelo deve improvisar tudo do zero a cada turno.

Isso geralmente cria três problemas:

• o modelo revisita os mesmos arquivos ou URLs repetidamente
• o uso de ferramentas se torna ruidoso e caro
• o fluxo de trabalho perde uma condição de parada clara

Um padrão melhor é o planejamento leve combinado com execução fundamentada. Deixe o modelo decidir a próxima ação, mas faça-o contra uma tarefa explícita, um estado atual visível e um pequeno conjunto de ferramentas permitidas. Isso mantém a flexibilidade onde ela ajuda e a remove onde não ajuda.

Em fluxos de trabalho de codificação, o planejamento geralmente se parece com isto:

1. Identificar os arquivos envolvidos.
2. Ler a implementação atual.
3. Decidir a mudança mínima.
4. Fazer a edição.
5. Executar a verificação.
6. Parar ou reparar.

Isso ainda é agêntico, porque o modelo pode ramificar quando o repositório o surpreende. Mas não está vagando.

Como o uso de ferramentas deve funcionar em um fluxo de trabalho agêntico?

O uso de ferramentas deve ser explícito, tipado e observável.

Se o seu modelo suporta chamada de função, use-a. A API LLM da Novita expõe um endpoint compatível com OpenAI e documenta a chamada de função diretamente, que é a maneira mais limpa de permitir que o modelo escolha entre as ferramentas sem depender de análise de string frágil.

Algumas regras tornam o uso de ferramentas muito mais confiável:

• Mantenha os nomes das ferramentas concretos.
• Use esquemas com campos obrigatórios.
• Retorne resultados completos, incluindo erros.
• Registre cada chamada, argumento e saída.
• Torne as ações destrutivas raras e fáceis de controlar.

A camada de ferramentas também deve refletir limites reais. Por exemplo, não dê a um agente de codificação uma mega-ferramenta chamada edit_repo_and_run_tests. Divida as etapas de leitura, escrita e execução para que o modelo possa se recuperar quando algo falhar.

Por que a execução de código precisa de um sandbox?

Um fluxo de trabalho agêntico que nunca executa nada pode muitas vezes ficar dentro de um servidor de aplicativo comum. No momento em que começa a executar comandos de shell, instalar dependências, lidar com arquivos baixados ou navegar na web aberta, você precisa de isolamento.

O sandbox resolve dois problemas diferentes:

• Segurança: código gerado e saídas de ferramentas podem estar errados, hostis ou simplesmente imprevisíveis.
• Estado: tarefas de várias etapas precisam de um espaço de trabalho persistente onde arquivos, pacotes e histórico de execução sobrevivam entre os turnos.

Para muitas equipes, o segundo ponto é tão importante quanto o primeiro. Um fluxo de trabalho que edita código, executa testes, corrige a falha e reexecuta a verificação não é possível se cada etapa começar em uma máquina limpa.

É por isso que a arquitetura prática é geralmente:

• API LLM para planejamento e seleção de ferramentas
• Runtime de sandbox para execução e persistência

A Novita se encaixa naturalmente nessa divisão: a API LLM atua como a camada de planejamento e chamada de ferramentas, enquanto o Agent Sandbox lida com o ambiente de execução real.

Como você avalia um fluxo de trabalho agêntico?

A avaliação precisa acontecer em dois níveis.

Avaliação no nível da etapa

A última ação funcionou?

Exemplos:

• O comando foi encerrado com sucesso?
• A API retornou JSON válido?
• O arquivo esperado foi criado?
• A página do navegador continha o elemento alvo?

Avaliação no nível da tarefa

O fluxo de trabalho resolveu o problema do usuário?

Exemplos:

• Os testes passam após a alteração do código?
• O resumo responde à pergunta de pesquisa com evidências?
• A automação concluiu a transação sem limpeza manual?

Fluxos de trabalho fortes usam ambos. Se você avaliar apenas a saída final, perde sinais de falha óbvios durante a execução. Se você avaliar apenas as etapas, o fluxo de trabalho pode completar uma longa série de ações localmente válidas e ainda falhar na tarefa real.

Uma arquitetura prática para construir fluxos de trabalho agênticos

Aqui está a arquitetura com a qual a maioria das equipes deve começar:

1. Uma solicitação do usuário entra no seu aplicativo.
2. Seu controlador envia o objetivo, estado e ferramentas disponíveis para um LLM.
3. O LLM retorna uma resposta direta ou uma chamada de ferramenta.
4. Seu controlador executa a ferramenta dentro de um sandbox ou outro runtime controlado.
5. O resultado da ferramenta é anexado ao estado da conversa.
6. Um avaliador verifica a conclusão, falha ou portões de aprovação.
7. O loop continua até que o fluxo de trabalho seja concluído ou bloqueado.

Este loop de controlador pode ser simples. Em muitos casos, um único processo orquestrador é suficiente. Você não precisa de um sistema multi-agente no primeiro dia. Comece com um planejador, algumas ferramentas bem definidas, um runtime em sandbox e um avaliador claro.

Exemplo: um controlador de fluxo de trabalho agêntico em Python

O exemplo abaixo mostra a forma do loop de controle. Ele usa a API compatível com OpenAI da Novita para chamada de ferramentas. As funções de execução são suas para implementar contra seu próprio runtime ou sandbox.

import json
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    api_key=os.environ["NOVITA_API_KEY"],
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Read a file from the workspace",
            "parameters": {
                "type": "object",
                "properties": {"path": {"type": "string"}},
                "required": ["path"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "run_command",
            "description": "Run a shell command in the sandbox",
            "parameters": {
                "type": "object",
                "properties": {"cmd": {"type": "string"}},
                "required": ["cmd"],
            },
        },
    },
]


def read_file(path: str) -> str:
    # Implement this against your own workspace or sandbox filesystem.
    raise NotImplementedError


def run_command(cmd: str) -> str:
    # Implement this against your sandbox runtime.
    raise NotImplementedError


dispatch = {
    "read_file": read_file,
    "run_command": run_command,
}


def run_workflow(task: str, model: str) -> str:
    messages = [
        {
            "role": "system",
            "content": (
                "You are a workflow controller. Use tools when needed, "
                "check results after each action, and stop when the task is complete."
            ),
        },
        {"role": "user", "content": task},
    ]

    while True:
        response = client.chat.completions.create(
            model=model,
            messages=messages,
            tools=tools,
            tool_choice="auto",
        )

        message = response.choices[0].message
        messages.append(message)

        if not message.tool_calls:
            return message.content

        for call in message.tool_calls:
            fn = dispatch[call.function.name]
            args = json.loads(call.function.arguments)
            result = fn(**args)
            messages.append(
                {
                    "role": "tool",
                    "tool_call_id": call.id,
                    "content": result,
                }
            )

Isso é intencionalmente mínimo. Em produção, você também adicionaria:

• política de repetição para erros transitórios
• timeouts e limites de orçamento
• aprovação humana para ações sensíveis
• logs de etapas estruturados
• um avaliador de nível de tarefa antes da conclusão final

Qual modelo você deve usar como planejador?

Para um fluxo de trabalho agêntico, o modelo planejador não precisa apenas de inteligência bruta. Ele precisa da forma certa:

• chamada de ferramenta confiável
• comportamento estável em contexto longo
• forte seguimento de instruções
• latência previsível em profundidade de múltiplos turnos

Se você quiser um ponto de partida de peso aberto na Novita, o Qwen3 Coder 30B A3B Instruct é uma opção prática para planejamento de fluxo de trabalho e uso de ferramentas orientado a codificação. A página de modelos atual da Novita lista acesso compatível com OpenAI, suporte a chamada de função, suporte a saída estruturada e uma janela de contexto hospedada de 160K. Para muitas tarefas de automação interna e codificação, isso é suficiente para construir uma primeira versão séria antes de migrar para um planejador maior ou mais especializado.

O modelo certo ainda depende do trabalho. Para fluxos de trabalho amplos e pesados em raciocínio, escolha primeiro pela qualidade do planejamento. Para automação de alto volume, latência e custo podem importar tanto quanto a força do benchmark.

Modos comuns de falha em fluxos de trabalho agênticos

A maioria das falhas não é dramática. Elas são repetitivas e caras.

Excesso de ferramentas

Se cada capacidade se tornar sua própria dependência remota, o fluxo de trabalho gasta mais tempo coordenando do que fazendo trabalho útil.

Regras de parada fracas

Se o sistema nunca sabe quando “concluído” é verdadeiro, ele continua gerando mais um passo.

Tratamento de erro ruim

Se as ferramentas retornam mensagens vagas como “falhou” em vez de saída acionável, o modelo não consegue se recuperar.

Sem limite de sandbox

O fluxo de trabalho pode funcionar em desenvolvimento, mas se tornar inseguro no momento em que toca em arquivos reais, credenciais ou sistemas externos.

Sem avaliador

O agente parece ocupado, mas nunca prova que a tarefa foi concluída corretamente.

Quando você não deve usar um fluxo de trabalho agêntico?

Não construa um apenas porque o termo é popular.

Você provavelmente não precisa de um fluxo de trabalho agêntico se:

• a tarefa é geração única
• o caminho é fixo e raramente muda
• um programa tradicional pode decidir cada etapa de forma barata
• não há necessidade de uso de ferramentas ou execução

Por exemplo, se seu aplicativo sempre recebe uma entrada de formulário, chama um prompt e retorna um e-mail formatado, um fluxo de trabalho LLM comum é mais simples e melhor.

Fluxos de trabalho agênticos valem a pena quando o ambiente pode surpreender o sistema e o sistema ainda precisa continuar.

FAQ

Um fluxo de trabalho agêntico é o mesmo que chamada de função?

Não. A chamada de função é um mecanismo dentro do fluxo de trabalho. O fluxo de trabalho completo também precisa de fluxo de controle, estado, execução e avaliação.

Preciso de múltiplos agentes para construir fluxos de trabalho agênticos?

Não. A maioria das equipes deve começar com um único loop de controlador e algumas ferramentas. Designs multi-agente são úteis mais tarde, mas não são o ponto de partida padrão.

Qual é o controle de segurança mais importante?

Para fluxos de trabalho que executam código ou tocam em sistemas externos, o controle mais importante é um ambiente de execução isolado combinado com permissões de ferramenta estreitas.

Qual é a stack mais simples pronta para produção?

Uma boa primeira stack é: uma API LLM compatível com OpenAI, um pequeno registro de ferramentas, um runtime em sandbox e um avaliador que pode decidir quando a tarefa está realmente concluída.

Artigos Recomendados

• O que são Agentes de Codificação? Como Eles Funcionam e Como Construir Um
• O que é um Sandbox de Agente de IA?
• Agente vs Fluxo de Trabalho: Principais Diferenças e Trade-offs Práticos