diff --git a/docs/source/build-workflows/about-building-workflows.md b/docs/source/build-workflows/about-building-workflows.md index ea314e3e32..5985567428 100644 --- a/docs/source/build-workflows/about-building-workflows.md +++ b/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. |