docs: agent blocks

docs/docs/Components/agent-blocks-agent-loop.mdx

@@ -0,0 +1,34 @@
+---
+title: AgentLoop
+slug: /agent-blocks-agent-loop
+---
+
+import Icon from "@site/src/components/icon";
+import PartialParams from '@site/docs/_partial-hidden-params.mdx';
+
+The **Agent Loop** component is a pre-composed component that encapsulates the complete agent loop. It combines the [**While Loop** component](/agent-blocks-while-loop), [**Agent Step** component](/agent-blocks-agent-step), and [**Execute Tool** component](/agent-blocks-execute-tool) into a single, ready-to-use component.
+
+**Agent Loop** provides a simplified way to create agent workflows without manually assembling individual agent blocks, including built-in loop control, LLM reasoning with tool calling, automatic tool execution, and session memory management.
+
+For more information, see the [Agent blocks quickstart](/agent-blocks-quickstart).
+
+## AgentLoop parameters
+
+<PartialParams />
+
+| Name | Display Name | Type | Description |
+|------|--------------|------|-------------|
+| llm | Language Model | LanguageModel | Input parameter. The language model for reasoning. |
+| tools | Tools | Tool[] | Input parameter. List of tools available to the agent. |
+| system_prompt | System Prompt | String | Input parameter. System prompt to guide agent behavior. |
+| input_value | Input | Message | Input parameter. Input message from the [**Chat Input** component](/chat-input-and-output). |
+| max_iterations | Max Iterations | Integer | Input parameter. Maximum number of iterations. Default: `15`. |
+| response | Response | Message | Output parameter. Final response from the agent. |
+
+## See also
+
+* [Agent Blocks](/agent-blocks-quickstart)
+* [Agent Step](/agent-blocks-agent-step)
+* [Execute Tool](/agent-blocks-execute-tool)
+* [While Loop](/agent-blocks-while-loop)
+* [Agent component](/components-agents)

docs/docs/Components/agent-blocks-agent-step.mdx

@@ -0,0 +1,41 @@
+---
+title: AgentStep
+slug: /agent-blocks-agent-step
+---
+
+import Icon from "@site/src/components/icon";
+import PartialParams from '@site/docs/_partial-hidden-params.mdx';
+
+The **Agent Step** component is the reasoning core of an agent workflow. It sends messages to an LLM and routes the response based on whether the LLM requests tool execution or provides a final answer.
+
+**Agent Step** performs the core reasoning step in the agent loop:
+
+1. The **Agent Step** component receives input messages from the [**Chat Input** component](/chat-input-and-output) or [**While Loop** component](/agent-blocks-while-loop).
+2. The **Agent Step** component sends messages to the LLM with available tools.
+3. Examines the LLM response for `tool_calls`, and then routes to either:
+   * `tool_calls` output: When the LLM requests tool execution, the message routes to the [**Execute Tool** component](/agent-blocks-execute-tool).
+   * `ai_message` output: When the LLM provides a final answer, the message routes to the [**Chat Output** component](/chat-input-and-output).
+
+For more information, see the [Agent blocks quickstart](/agent-blocks-quickstart).
+
+## AgentStep parameters
+
+<PartialParams />
+
+| Name | Display Name | Type | Description |
+|------|--------------|------|-------------|
+| llm | Language Model | LanguageModel | Input parameter. The language model that performs reasoning. |
+| tools | Tools | Tool[] | Input parameter. List of tools available to the agent. |
+| system_prompt | System Prompt | String | Input parameter. System prompt to guide the agent's behavior. |
+| chat_history | Chat Memory | Data[] | Input parameter. Chat history for context-aware responses. |
+| input_value | Input | Message | Input parameter. The input message to process. |
+| tool_calls | Tool Calls | ToolCall[] | Output parameter. Tool calls requested by the LLM (routes to [**Execute Tool** component](/agent-blocks-execute-tool)). |
+| ai_message | AI Message | Message | Output parameter. Final answer from the LLM (routes to [**Chat Output** component](/chat-input-and-output)). |
+
+## See also
+
+* [Agent Blocks](/agent-blocks-quickstart)
+* [Execute Tool](/agent-blocks-execute-tool)
+* [While Loop](/agent-blocks-while-loop)
+* [Agent Loop](/agent-blocks-agent-loop)
+* [Agent component](/components-agents)

docs/docs/Components/agent-blocks-execute-tool.mdx

@@ -0,0 +1,30 @@
+---
+title: ExecuteTool
+slug: /agent-blocks-execute-tool
+---
+
+import Icon from "@site/src/components/icon";
+import PartialParams from '@site/docs/_partial-hidden-params.mdx';
+
+The **Execute Tool** component executes tool calls from the [**Agent Step** component](/agent-blocks-agent-step) with support for parallel execution and proper error handling.
+
+For more information, see the [Agent blocks quickstart](/agent-blocks-quickstart).
+
+## ExecuteTool parameters
+
+<PartialParams />
+
+| Name | Display Name | Type | Description |
+|------|--------------|------|-------------|
+| tool_calls | Tool Calls | ToolCall[] | Input parameter. Tool calls to execute from the [**Agent Step** component](/agent-blocks-agent-step). |
+| parallel_execution | Parallel Execution | Boolean | Input parameter. Enable parallel execution of multiple tools. Default: `true`. |
+| error_handling | Error Handling | Dropdown | Input parameter. Error handling strategy: `raise`, `return_error`, or `skip`. Default: `return_error`. |
+| results | Tool Results | Message[] | Output parameter. Results from tool execution, formatted for the agent loop. |
+
+## See also
+
+* [Agent Blocks](/agent-blocks-quickstart)
+* [Agent Step](/agent-blocks-agent-step)
+* [While Loop](/agent-blocks-while-loop)
+* [Agent Loop](/agent-blocks-agent-loop)
+* [Agent component](/components-agents)

docs/docs/Components/agent-blocks-quickstart.mdx

@@ -0,0 +1,107 @@
+---
+title: Agent blocks quickstart
+slug: /agent-blocks-quickstart
+---
+
+import Icon from "@site/src/components/icon";
+
+An agent is fundamentally a while loop.
+The while loop accepts input and iterates over the agent's reasoning.
+The agent's reasoning sends messages to an LLM and examines the LLM's response to determine where to route the request.
+If the LLM's response includes `tool_calls`, the agent sends output to a tool-calling function, and the results are sent back to the while loop to be iterated over again.
+If the LLM's response does not include `tool_calls` and the agent determines the task is complete, the agent sends a "finished" message to output.
+
+```
+ChatInput → WhileLoop → AgentStep → [Tool Calls] → ExecuteTool → WhileLoop
+                              ↓ [AI Message - done]
+                         ChatOutput
+```
+
+Langflow's [**Agent** component](/components-agents) is composed of this same architecture, and is suitable for most tasks that require a reasoning loop that can choose from a list of registered functions.
+
+But what if you want to modify the agent's behavior? For example, how do you include a validation step in your tool outputs before execution?
+
+Use **Agent Blocks** to construct an agent in Langflow's visual builder.
+Agent Blocks are composable primitives that provide the building blocks for constructing each step of custom agent workflows.
+Assemble the blocks to create agents tailored to your exact requirements.
+For example, to add a validation step to your agent, insert an [**If-Else** component](/if-else) between the [**Agent Step** component](/agent-blocks-agent-step)'s `tool_calls` output and the [**Execute Tool** component](/agent-blocks-execute-tool) to validate tool names against an allowed list.
+
+This page includes a quickstart for building an agent with Agent Blocks.
+For the individual Agent Blocks components, see the Components reference pages.
+
+## Agent Blocks quickstart
+
+This quickstart demonstrates building an agent using Agent Blocks components.
+The core agent loop pattern iterates over reasoning and tool execution until completion.
+
+### Prerequisites
+
+- [Install and start Langflow](/get-started-installation)
+- Create an [OpenAI API key](https://platform.openai.com/api-keys) or credentials for your preferred LLM provider
+
+### Build the agent loop
+
+The agent loop consists of four main components:
+
+* [**While Loop** component](/agent-blocks-while-loop): Controls iteration until the agent completes its task.
+* [**Agent Step** component](/agent-blocks-agent-step): The reasoning core that sends messages to the LLM.
+* [**Execute Tool** component](/agent-blocks-execute-tool): Executes tool calls when the agent needs to use tools.
+* [**Chat Output** component](/chat-input-and-output): Displays the final response.
+
+![Agent Loop flow diagram showing WhileLoop, AgentStep, ExecuteTool, and ChatOutput components connected in a loop pattern](/img/component-agent-blocks.png)
+
+To create an agent with agent blocks, do the following:
+
+1. In Langflow, click **New Flow** to create a blank flow.
+2. Add a [**While Loop** component](/agent-blocks-while-loop) from the component library.
+The **While Loop** component manages conversation state and continues iterating until the agent signals completion.
+3. In the **While Loop** component, configure the following fields:
+   * **Initial State**: Leave this empty, or optionally provide initial conversation history as a DataFrame.
+   * **Input Value**: Connect this to the [**Chat Input** component](/chat-input-and-output) in a later step.
+   * **Max Iterations**: Set a limit to prevent infinite loops. For this example, enter `10`.
+4. Add an **Agent Step** component to your flow.
+5. In the **Agent Step** component, configure the following fields:
+   * **Language Model**: Select your model provider, such as OpenAI.
+   * **API Key**: Enter your model provider's API key or a [global variable](/configuration-global-variables).
+   * **System Message**: Optionally define the agent's behavior with a prompt.
+
+   The **Agent Step** component has two outputs:
+   * **Response** (`ai_message`): This output sends when the model is done, and no tool calls remain.
+   * **Tool Calls** (`tool_calls`): This output sends when the model wants to execute tools.
+
+6. Connect the **While Loop** component's **Loop** output to the **Agent Step** component's **Messages** input.
+7. Add an [**Execute Tool** component](/agent-blocks-execute-tool) to your flow.
+8. Configure the **Execute Tool** component:
+   - **Parallel Execution**: Enable to execute multiple tool calls concurrently
+   - **Timeout**: Set a timeout for individual tool calls (optional)
+9. Connect the **Agent Step** component's **Tool Calls** output to the **Execute Tool** component's **Tool Calls** input.
+10. Connect the same tools you connected to the **Agent Step** component to the **Execute Tool** component's **tools** input.
+
+    The **Execute Tool** component executes the tool calls and returns the results as a [Message](/data-types#message).
+
+    The next steps complete the agent loop by connecting the tool execution results back to the loop, and then routing the final responses to the output.
+
+11. Connect the **Execute Tool** component's **messages** output back to the **While Loop** component's **loop** input.
+   This creates the iterative loop which sends tool result back into the conversation.
+
+12. Connect the **Agent Step** component's **Response** output to a **Chat Output** component.
+   The Chat output will display the final response when the agent completes its task and no tool calls remain.
+
+### Test the flow
+
+To test the flow in the Playground, do the following:
+
+1. Add a **Chat Input** component.
+2. Connect the **Chat Input** component to the **While Loop** component's **Input** input.
+3. Click <Icon name="Play" aria-hidden="true" /> **Playground** to test your agent.
+4. Enter a message that requires tool usage, such as `What is 15 * 7?`, if you've connected a **Calculator** tool.
+5. The Playground outputs each step of the agent loop as it receives your message, executes tools if required, and then returns a final response.
+
+## Agent Blocks components
+
+- [**Agent Step** component](/agent-blocks-agent-step): The reasoning core that sends messages to the LLM and routes based on tool calls.
+- [**Execute Tool** component](/agent-blocks-execute-tool): Executes tool calls from the **Agent Step** component, with parallel execution support.
+- [**While Loop** component](/agent-blocks-while-loop): Loop control for iterative agent execution.
+- [**Agent Loop** component](/agent-blocks-agent-loop): A pre-composed component that encapsulates the complete agent loop.
+- [**Shared Context** component](/agent-blocks-shared-context): Share state management across agent iterations.
+- [**Think Tool** component](/agent-blocks-think-tool): Think tool support for step-by-step reasoning.

docs/docs/Components/agent-blocks-shared-context.mdx

@@ -0,0 +1,35 @@
+---
+title: SharedContext
+slug: /agent-blocks-shared-context
+---
+
+import Icon from "@site/src/components/icon";
+import PartialParams from '@site/docs/_partial-hidden-params.mdx';
+
+The **Shared Context** component provides shared state management across agent iterations. It allows you to maintain and update state that persists throughout the agent loop, enabling complex workflows that require accumulating information or tracking progress.
+
+**Shared Context** is used when you need to maintain state across agent iterations:
+
+```
+ChatInput → WhileLoop → SharedContext → AgentStep → ExecuteTool → SharedContext → WhileLoop
+```
+
+For more information, see the [Agent blocks quickstart](/agent-blocks-quickstart).
+
+## SharedContext parameters
+
+<PartialParams />
+
+| Name | Display Name | Type | Description |
+|------|--------------|------|-------------|
+| initial_context | Initial Context | Dictionary | Input parameter. Initial state values. Default: `{}`. |
+| context_updates | Context Updates | Dictionary | Input parameter. Updates to apply to the context. |
+| context | Context | Dictionary | Output parameter. Current shared context state. |
+| updated_context | Updated Context | Dictionary | Output parameter. Context after applying updates. |
+
+## See also
+
+* [Agent Blocks](/agent-blocks-quickstart)
+* [Agent Step](/agent-blocks-agent-step)
+* [While Loop](/agent-blocks-while-loop)
+* [Agent Loop](/agent-blocks-agent-loop)

docs/docs/Components/agent-blocks-think-tool.mdx

@@ -0,0 +1,35 @@
+---
+title: ThinkTool
+slug: /agent-blocks-think-tool
+---
+
+import Icon from "@site/src/components/icon";
+import PartialParams from '@site/docs/_partial-hidden-params.mdx';
+
+The **Think Tool** component provides think tool support for step-by-step reasoning. It enables agents to perform explicit reasoning steps before taking action, improving the quality of tool selection and parameter generation.
+
+**Think Tool** is typically used as a tool that the [**Agent Step** component](/agent-blocks-agent-step) can call during reasoning:
+
+```
+AgentStep → [Think Tool Call] → ThinkTool → [Reasoning Output] → AgentStep
+```
+
+For more information, see the [Agent blocks quickstart](/agent-blocks-quickstart).
+
+## ThinkTool parameters
+
+<PartialParams />
+
+| Name | Display Name | Type | Description |
+|------|--------------|------|-------------|
+| reasoning_prompt | Reasoning Prompt | String | Input parameter. The prompt for the reasoning step. |
+| reasoning_model | Reasoning Model | LanguageModel | Input parameter. Optional LLM for reasoning (uses the [**Agent Step** component](/agent-blocks-agent-step)'s LLM if not provided). |
+| reasoning_output | Reasoning Output | String | Output parameter. The structured reasoning output. |
+| toolset | Toolset | Tool | Output parameter. Tool interface for the [**Agent Step** component](/agent-blocks-agent-step) (when Tool Mode is enabled). |
+
+## See also
+
+* [Agent Blocks](/agent-blocks-quickstart)
+* [Agent Step](/agent-blocks-agent-step)
+* [Execute Tool](/agent-blocks-execute-tool)
+* [Configure tools for agents](/agents-tools)

docs/docs/Components/agent-blocks-while-loop.mdx

@@ -0,0 +1,45 @@
+---
+title: WhileLoop
+slug: /agent-blocks-while-loop
+---
+
+import Icon from "@site/src/components/icon";
+import PartialParams from '@site/docs/_partial-hidden-params.mdx';
+
+The **While Loop** component provides loop control for iterative agent execution. It manages the agent's reasoning loop, continuing iteration until the agent determines the task is complete.
+
+**While Loop** is the control structure that wraps the agent's reasoning loop:
+
+```
+ChatInput → WhileLoop → AgentStep → [Tool Calls] → ExecuteTool → WhileLoop
+                              ↓ [AI Message - done]
+                         ChatOutput
+```
+
+**While Loop** stops iterating when:
+
+* The [**Agent Step** component](/agent-blocks-agent-step) outputs an `ai_message` (final answer) instead of `tool_calls`
+* Maximum iterations are reached
+* An explicit stop condition is met
+
+For more information, see the [Agent blocks quickstart](/agent-blocks-quickstart).
+
+## WhileLoop parameters
+
+<PartialParams />
+
+| Name | Display Name | Type | Description |
+|------|--------------|------|-------------|
+| input_value | Input | Message | Input parameter. Initial input or input from previous iteration. |
+| max_iterations | Max Iterations | Integer | Input parameter. Maximum number of iterations allowed. Default: `15`. |
+| iteration | Iteration | Integer | Output parameter. Current iteration count. |
+| output | Output | Message | Output parameter. Output from the current iteration (routes to the [**Agent Step** component](/agent-blocks-agent-step)). |
+| done | Done | Message | Output parameter. Final result when loop completes. |
+
+## See also
+
+* [Agent Blocks](/agent-blocks-quickstart)
+* [Agent Step](/agent-blocks-agent-step)
+* [Execute Tool](/agent-blocks-execute-tool)
+* [Agent Loop](/agent-blocks-agent-loop)
+* [Loop component](/loop)

docs/docs/Support/release-notes.mdx

@@ -82,6 +82,11 @@ For all changes, see the [Changelog](https://github.com/langflow-ai/langflow/rel
 
 ### New features and enhancements
 
+- Agent blocks
+
+    Use **Agent Blocks** to build custom agents with control over iteration, tool calls, and persistent memory.
+    For more information, see the [Agent Blocks quickstart](/agent-blocks-quickstart).
+
 - Mustache templating support for Prompt Template component
 
     The **Prompt Template** component now supports Mustache templating syntax.

docs/sidebars.js

@@ -358,6 +358,19 @@ module.exports = {
           label: "Bundles",
           items: [
             "Components/components-bundles",
+            {
+              type: "category",
+              label: "Agent Blocks",
+              items: [
+                "Components/agent-blocks-quickstart",
+                "Components/agent-blocks-agent-loop",
+                "Components/agent-blocks-agent-step",
+                "Components/agent-blocks-execute-tool",
+                "Components/agent-blocks-shared-context",
+                "Components/agent-blocks-think-tool",
+                "Components/agent-blocks-while-loop",
+              ]
+            },
             "Components/bundles-aiml",
             "Components/bundles-altk",
             "Components/bundles-amazon",