docs: restructure About Building Workflows to the about-procedural-task template

docs/source/build-workflows/about-building-workflows.md

@@ -19,7 +19,9 @@ limitations under the License.
 
 In NeMo Agent Toolkit, a workflow defines which [functions](./functions-and-function-groups/functions.md) and [models](./llms/index.md) are used to perform a given task or series of tasks. A workflow definition is specified in a [YAML configuration file](#understanding-the-workflow-configuration-file). The `workflow` section of the configuration file defines the workflow itself, and specifies a function, typically an [agent](../components/agents/index.md), which will orchestrate which functions and models are called to complete the given task.
 
-## Understanding the Workflow Configuration File
+## Workflow Overview
+
+### Understanding the Workflow Configuration File
 
 The workflow configuration file is a YAML file that specifies the [tools](./functions-and-function-groups/functions.md#agents-and-tools) and models to use in a workflow, along with general configuration settings. This section examines the configuration of the `examples/getting_started/simple_web_query` workflow to show how they are organized.
 
@@ -57,28 +59,61 @@ workflow:
 
 This workflow configuration is divided into four sections: `functions`, `llms`, `embedders`, and `workflow`. The `functions` section contains the tools used in the workflow, while `llms` and `embedders` define the models used in the workflow, and lastly the `workflow` section ties the other sections together and defines the workflow itself.
 
-The workflow itself is typically an agent, however any NeMo Agent Toolkit function can be used as a workflow. Refer to the [Agents](../components/agents/index.md) documentation for more details on the agents that are included in NeMo Agent Toolkit.
+#### The `functions` section
 
 In this workflow, the `webpage_query` tool queries the LangSmith User Guide, and the `current_datetime` tool gets the current date and time. The `description` entry instructs the LLM when and how to use the tool. In this case, the workflow explicitly defines `description` for the `webpage_query` tool.
 
+#### The `llms` and `embedders` sections
+
 The `webpage_query` tool uses the `nv-embedqa-e5-v5` embedder, which is defined in the `embedders` section.
 
+#### The `workflow` section
+
+The workflow itself is typically an agent, however any NeMo Agent Toolkit function can be used as a workflow. Refer to the [Agents](../components/agents/index.md) documentation for more details on the agents that are included in NeMo Agent Toolkit.
+
 For details on workflow configuration, including sections not utilized in the above example, refer to the [Workflow Configuration](./workflow-configuration.md) document.
 
-## Using Agents With Workflows
+## Key Concepts
+
+Understanding these concepts will help you build workflows effectively.
+
+### Workflow
+
+A workflow defines which functions and models are used to perform a given task or series of tasks. The `workflow` section of the configuration file defines the workflow itself, and specifies a function, typically an agent, which will orchestrate which functions and models are called to complete the given task.
+
+### Configuration File
+
+A workflow definition is specified in a YAML configuration file. The file specifies the tools and models to use in a workflow, along with general configuration settings, organized into the `functions`, `llms`, `embedders`, and `workflow` sections.
+
+### Functions (Tools)
+
+The `functions` section contains the tools used in the workflow. The `description` entry instructs the LLM when and how to use the tool.
+
+### Agents
+
+The workflow itself is typically an agent, however any NeMo Agent Toolkit function can be used as a workflow. Refer to the [Agents](../components/agents/index.md) documentation for more details on the agents that are included in NeMo Agent Toolkit.
+
+### Control Flow Components
+
+Control flow components are offered by NeMo Agent Toolkit to direct how a workflow runs, including the [Router Agent](../components/agents/router-agent/index.md) and the [Sequential Executor](../components/agents/sequential-executor/index.md).
+
+## Common Approaches
 
-The following are [agents](../components/agents/index.md) offered by NeMo Agent Toolkit:
+The following are [agents](../components/agents/index.md) offered by NeMo Agent Toolkit. Choose the approach that best fits your needs.
 
-- [Automatic Memory Wrapper Agent](../components/agents/auto-memory-wrapper/index.md)
-- [ReAct Agent](../components/agents/react-agent/index.md)
-- [Reasoning Agent](../components/agents/reasoning-agent/index.md)
-- [ReWOO Agent](../components/agents/rewoo-agent/index.md)
-- [Responses API and Agent](../components/agents/responses-api-and-agent/index.md)
-- [Tool Calling Agent](../components/agents/tool-calling-agent/index.md)
+- [Automatic Memory Wrapper Agent](../components/agents/auto-memory-wrapper/index.md) — **Best for**: wrapping any agent to provide automatic memory capture and retrieval without requiring the LLM to invoke memory tools explicitly.
+- [ReAct Agent](../components/agents/react-agent/index.md) — **Best for**: performing ReAct (Reasoning and Acting) reasoning between tool calls.
+- [Reasoning Agent](../components/agents/reasoning-agent/index.md) — **Best for**: reasoning ahead of time through planning rather than between steps (requires an LLM that supports reasoning).
+- [ReWOO Agent](../components/agents/rewoo-agent/index.md) — **Best for**: decoupling reasoning from observations to improve tool usage and token efficiency for reasoning tasks.
+- [Responses API and Agent](../components/agents/responses-api-and-agent/index.md) — **Best for**: tool use with OpenAI's Responses API, including built-in tools, MCP remote tools, and NeMo Agent Toolkit tools.
+- [Tool Calling Agent](../components/agents/tool-calling-agent/index.md) — **Best for**: directly invoking external tools based on structured function definitions (requires an LLM with tool-calling support).
 
-## Using Control Flow Components With Workflows
+## Decision Factors
 
-The following are control flow components offered by NeMo Agent Toolkit:
+The following are control flow components offered by NeMo Agent Toolkit. Use the following comparison to select the right component.
 
-- [Router Agent](../components/agents/router-agent/index.md)
-- [Sequential Executor](../components/agents/sequential-executor/index.md)
+| Factor | [Router Agent](../components/agents/router-agent/index.md) | [Sequential Executor](../components/agents/sequential-executor/index.md) |
+|--------|------------------|-------------------|
+| **What it does** | Analyzes incoming requests and directs them to the most appropriate branch based on the request configuration. | Chains multiple functions together, where each function's output becomes the input for the next function. |
+| **How it runs** | Pairs a single-pass architecture with intelligent request routing to analyze prompts and select one branch that best handles the request. | Creates a linear tool execution pipeline that executes functions in a predetermined sequence without requiring LLMs or agents for orchestration. |
+| **Best For** | Scenarios where different types of requests need specialized handling. | Linear pipelines where each function feeds the next; supports better error handling and optional compatibility validation. |