> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding agentic workflows

**Agentic workflow is a type of tool** with built-in agentic capabilities and automations that support arbitrarily complex orchestration of multiple agents, tools, and people.

Each node can represent an agent, a tool, or built-in capabilities such as user interactions, prompts, or decision logic.

With agentic workflows, you design workflows using control structures such as conditional branching with if-then-else or switch-case, iteration over lists with foreach, and loops that repeat actions until specific conditions are met.

An agentic workflow is composed of nodes and edges. You define nodes of different types and connect them using edges. Because agentic workflows can take several seconds to execute depending on their complexity, they run asynchronously.

Agentic workflows apply to various scenarios, such as:

* **Repeatable, predictable** sequencing of agents, tools, and human tasks is required.
* **Long-running processes** are involved. Agentic workflow supports extended task chains that can take minutes, hours, or even days to complete.
* **Human-in-the-loop interaction** is needed for approvals or decision-making.
* **Scheduling** is necessary to trigger tasks at specific times or intervals.

<Note>
  - When an **agentic workflow tool** is invoked, the system returns an instance ID and waits for the response.
  - To check the progress, use the **Get agentic workflow status** tool in a new chat session. Provide the instance ID to retrieve the current status of the agentic workflow.
  - Tools built using Agentic workflows do not require connection support as connections within Agentic workflows are configured via their downstream component tools.
</Note>

## Agentic workflow and ADK

Unlike the UI experience, the pro-code approach uses the ADK CLI and Python library. You build agentic workflows with the Python library included in ADK, then manage them with the ADK CLI in your active environment. This environment can be local or remote. For details, see [Environments](../../environment/initiate_environment).

<Steps>
  <Step title="Create an agentic workflow">
    Use Python and the ADK library to create agentic workflows and their nodes.
    For more information, see:

    * [Building agentic workflows](./building_flow)
    * [Agentic workflow nodes](./agent_node)
    * [Testing agentic workflow](./testing_flow)
  </Step>

  <Step title="Import the workflow into your environment">
    After creating a workflow, import it into your active watsonx Orchestrate environment using the command `orchestrate tools import` with the flag `--kind flow`. For more information, see [Import the agentic workflow](./building_flow#import-the-agentic-workflow).
  </Step>

  <Step title="Manage agentic workflows in your environment">
    After you import an agentic workflow, you can also list it, export it, update it, and remove it from your active environment. Because an agentic workflow is a type of tool, you manage it with the same commands you use for other tools in ADK. For more information, see [Managing tools](../manage_tool).
  </Step>
</Steps>

## Agentic workflow key concepts

The sections below introduce the key concepts and components you'll use when working with agentic workflows:

<AccordionGroup>
  <Accordion title="Edges">
    Edges connect nodes within an agentic workflow. Every agentic workflow must begin with a **Start Node** and end with one or more **End Nodes**. Nodes connected with single exit points are run sequentially, whereas nodes with multiple exit points are run in parallel, except for branch nodes.
  </Accordion>

  <Accordion title="Node types">
    The system supports the following node types right now, and more will be added over time:

    * **Flow Node**: A node that represents an agentic workflow or a nested agentic workflow.
    * **Start Node**: The entry point of an agentic workflow. Each agentic workflow must have exactly one **Start Node**.
    * **End Node**: The exit point of an agentic workflow. An agentic workflow must have at least one **End Node**.
    * **Tool Node**: Call an imported tool and returns its result.
    * **Agent Node**: Call an imported agent to perform a certain task.
    * **Decisions Node**: (Public Preview) Specify a decision table to determine actions based on provided conditions.
    * **Prompt Node**: (Public Preview) Make a LLM call to extract/classify/generate information based on provided input.
    * **Doc Processing Node**: (Public Preview) Extract text from a provided document.
    * **Branch Node**: A conditional branch. A branch node can include two or more exit paths where only the first path is followed that matches the given expression.
    * **Foreach Node**: A nested agentic workflow that iterates over a list of items until completion.
    * **Loop Node**: A nested agentic workflow that iterates over a condition as long as the condition is true.
  </Accordion>

  <Accordion title="Node specification">
    Each node includes a specification that defines its behavior and properties:

    * **kind**: The type of node. For example: `tool`, `user`, `agent`.
    * **name**: The internal name of the node.
    * **display\_name** *(optional)*: A user-friendly name for display purposes.
    * **description** *(optional)*: A brief description of the node's purpose.
    * **input\_schema** *(optional)*: The input schema of the node. By default there are no input schemas.
    * **output\_schema** *(optional)*: The output schema of the node. By default there are no output schemas.
  </Accordion>

  <Accordion title="Data mapping">
    To improve auto-mapping reliability, large data in the flow is automatically summarized. You customize the summarization by providing instructions specific to your use case. If data is not summarized, auto-mapping fails due to token limits, resulting in unpredictable agent behavior.

    ```python Python theme={null}
    class FlowContextWindow(BaseModel):
    """Indicate the context window setting for the LLM model used by the flow"""

    compression_threshold: Optional[int] = Field(
        description="Trigger compression when the context window reaches a specific number of tokens",
        default=None
    )
    compression_instruction: Optional[str] = Field(
        description="Instruction used for summarization or compression",
        default=None
    )
    max_tokens: Optional[int] = Field(
        description="The maximum number of tokens supported by the LLM model",
        default=None
    )
    allow_compress: Optional[bool] = Field(
        description="Indicates whether compression is allowed",
        default=True
    )
    ```
  </Accordion>

  <Accordion title="Scheduling">
    Schedule agentic workflows and agents to run automatically at specific times or intervals. Create schedules through Chat UI using natural language. To enable scheduling, set `schedulable=True` in the agentic workflow decorator or agent configuration. For details, see [Scheduling agentic workflows and agents](/scheduling/overview).
  </Accordion>

  <Accordion title="Flow callbacks">
    Flow callbacks support four tool types: OpenAPI, Python, Flow, and MCP. The Flow runtime executes these callbacks using a fire-and-forget pattern for optimal performance.

    **Recommendation**

    For Flow callbacks, use OpenAPI tools as the preferred callback mechanism. OpenAPI tools provide a clean, stateless callback interface without the complexity of managing user interactions or correlation ID propagation.

    **Limitation: Flow Tools as Callbacks**

    When using a Flow as a callback tool, there is a current limitation:

    * **Restriction**: Flow callback tools must not contain user activity nodes (nodes that require user interaction or input).
    * **Reason**: If a Flow callback contains user activity nodes, the Flow runtime would need to submit user activity events to the user's chat thread. This requires propagating correlation IDs through the Flow callback event chain, which adds significant complexity to the implementation.
    * **Workaround**: To keep the implementation simple and maintainable, Flows used as callback tools should be designed without user interaction requirements.
  </Accordion>

  <Accordion title="Multi-language support">
    Configure agentic workflows to support multiple languages using Python APIs. Define target locales in your agentic workflow code with `aflow.target_locales(['fr', 'es'])`, then export translatable text to CSV, add translations, and import them back. At runtime, the system automatically presents user activities in each user's preferred language. For complete details, see [Multi-language support](./multi_language_overview).
  </Accordion>
</AccordionGroup>

## Agentic workflow examples

The `examples/flow_builder` directory includes sample agentic workflow that demonstrate key agentic workflow features:

* **agent\_scheduler**: Demonstrates agent scheduling.
* **collaborator\_agents**: Shows how to sequence multiple agents.
* **extract\_support\_request**: Uses an LLM to extract information from support requests.
* **foreach\_email**: Applies the `Foreach` control to iterate over a set of items.
* **get\_facts\_numbers**: Uses the `Loop` control to repeat work until a condition is met.
* **get\_insurance\_rate**: Uses a `Decisions` node to determine insurance rates based on credit rating and loan amount.
* **get\_pet\_facts**: Demonstrates branching to route requests.
* **get\_tuition\_reimbursed**: Uses multiple branches to support complex logic routing.
* **hello\_message\_flow**: Sequences two Python tools together.
* **ibm\_knowledge\_to\_emails**: Combines an agent and a tool in a single agentic workflow.
* **schedule\_helpdesk\_alert**: Creates a schedulable agentic workflow to check helpdesk availability.
* **text\_extract**: Uses the `DocProc` node to extract text from a document.
* **user\_flow\_application\_form**: Displays a form to the user in the chat.