Feature Request

Feature Enhancement Request: Nested Progress Notifications for Agent-to-Agent Transparency

Status: Demonstration created
Category: User Experience, Multi-Agent Systems
Implementation Branch: feature/mcp-sdk-main-branch-migration
Compare with Main: View all changes

Executive Summary

This document proposes a feature enhancement to Langflow that enables nested progress notifications in multi-agent workflows. This feature provides complete transparency into child agent operations by displaying their progress updates hierarchically within the parent agent's tool invocation, rather than as separate top-level messages.

Business Value:

• Improved user experience in complex multi-agent workflows
• Clear visual hierarchy showing parent-child agent relationships
• Better debugging and monitoring capabilities for agent orchestration
• Organizations can combine simple MCP tools with complex Langflow flow tools, guaranteeing operations happen in a particular way rather than relying entirely on agentic skills
• Enhanced compliance and auditing capabilities for enterprise users

Problem Statement

Current Behavior: Lack of Agent-to-Agent Transparency

When a parent agent invokes a child agent as a tool in Langflow, users cannot see what the child agent is doing. The current implementation has several critical limitations:

1. Invisible Child Agent Operations

• Parent agent shows "Called tool: CHILD_FLOW" with execution time
• Child agent's internal steps are completely hidden from the user
• No visibility into which tools the child agent invokes
• No insight into the child agent's reasoning process

2. Flat Message Structure

All messages appear at the same level in the chat interface:

User: "What is the metadata for product ABC?"
├─ Parent Agent: Called tool GET_DATA_PRODUCTS (7.5s)
├─ 📊 Tool Progress: "What is the metadata..."  ← Child notification (orphaned)
├─ 🔄 Agent Steps: "Processing request..."      ← Child notification (orphaned)
├─ 🔨 Tool: get_metadata                        ← Child notification (orphaned)
├─ ✅ AI: "Here's the metadata..."              ← Child notification (orphaned)
└─ Parent Agent: "Here's the metadata..."

Problems:

• Child notifications appear as separate top-level messages
• No visual connection between parent tool call and child operations
• Difficult to understand which messages belong to which agent
• Cluttered interface with orphaned progress messages

3. Poor User Experience in Complex Workflows

• Users cannot trace execution flow in multi-agent systems
• Debugging agent orchestration is difficult
• No way to understand why a tool call took a long time
• Enterprise users need transparency for compliance and auditing

Proposed Solution: Nested Progress Notifications

Visual Representation

Transform the flat message structure into a hierarchical, expandable view:

User: "What is the metadata for product ABC?"
└─ Parent Agent
   └─ Called tool: GET_DATA_PRODUCTS [Expandable ▼] (7.5s)
      ├─ 📊 Tool Progress [Expandable ▼]
      │  └─ "What is the metadata of data product ABC?"
      │
      ├─ 🔄 Agent Steps [Expandable ▼]
      │  └─ "Processing request to retrieve metadata..."
      │
      ├─ 🔨 Tool Invocation [Expandable ▼]
      │  ├─ Tool: get_metadata
      │  └─ Input: {'data_product_id': 'ABC'}
      │
      └─ ✅ Final Answer [Expandable ▼]
         └─ "Here's the metadata for data product ABC: ..."

Benefits:

• ✅ Clear parent-child relationship visualization
• ✅ Expandable/collapsible sections for progressive disclosure
• ✅ All child operations nested under parent tool call
• ✅ Clean, organized interface
• ✅ Easy to trace execution flow

NOTE: This section describles how this demonstration implementation works but it is not meant to be pushed as the actual final solution - only to act as an inspiration for an official solution

Implementation Overview

A complete working implementation has been developed and is available in the feature/mcp-sdk-main-branch-migration branch.

Setup Requirements

⚠️ Important: This demonstration implementation has dependencies on unreleased or modified versions of external packages. Users attempting to run this demonstration must be aware of these requirements.

1. MCP-Proxy Modifications Required

Issue: The standard mcp-proxy package does not support the progress notification streaming required for this feature.

Temporary Solution: The implementation branch uses a locally modified version of mcp-proxy with necessary changes.

Affected Files:

• src/backend/base/langflow/api/utils/mcp/config_utils.py
• src/backend/base/langflow/api/v1/mcp_projects.py
• src/backend/base/langflow/api/v1/projects.py

These files contain commands to run mcp-proxy, but the commands have been temporarily modified to point to a local version.

Official Fix: A pull request has been submitted to the official mcp-proxy repository:

• PR: fix: forward meta parameter in call_tool handler sparfenyuk/mcp-proxy#189
• Status: Pending merge

Action Required for Users:
Until PR #189 is merged into the official mcp-proxy repository, users must:

1. Clone the mcp-proxy repository locally
2. Apply the changes from PR Number of requested results 4 cannot be greater than number of elements in index 3  #189 to their local copy
3. Update the commands in the affected Langflow files to point to their modified local mcp-proxy installation

Example:

# Instead of using the standard mcp-proxy command:
# mcp-proxy --config config.json

# Users must point to their locally modified version:
# /path/to/local/mcp-proxy/mcp-proxy --config config.json

2. MCP SDK Main Branch Dependency

Issue: This implementation requires features from the unreleased MCP SDK version 2.0, which is currently only available on the main branch.

Current Configuration:
The pyproject.toml file has been modified to use the MCP SDK main branch:

"mcp @ git+https://github.com/modelcontextprotocol/python-sdk.git@main"

Risks:

• The main branch may change at any time
• Breaking changes could occur without notice
• No version pinning or stability guarantees

Action Required for Users:
Users should be aware that:

1. This dependency points to an unstable, unreleased version
2. The main branch may have changed since this demonstration was created
3. Future updates to the main branch could break this implementation

Long-Term Solution:
This dependency is only needed until MCP SDK version 2.0 is officially released. Once released, the dependency should be updated to:

"mcp>=2.0.0,<3.0.0"

3. Recommended Setup Process

For users who want to test this demonstration:

1. Clone the feature branch:

   git clone https://github.com/stevehaertel/langflow.git
   cd langflow
   git checkout feature/mcp-sdk-main-branch-migration

2. Set up modified mcp-proxy:

   # Clone mcp-proxy repository
   git clone https://github.com/sparfenyuk/mcp-proxy.git
   cd mcp-proxy
   
   # Apply changes from PR #189
   # (Follow instructions in the PR)
   
   # Note the path to your modified mcp-proxy

3. Update Langflow configuration:

   • Edit config_utils.py, mcp_projects.py, and projects.py
   • Update mcp-proxy command paths to point to your local installation

4. Install Langflow dependencies:

   cd /path/to/langflow
   pip install -e src/backend/base

5. Enable the feature:

   export LANGFLOW_MCP_SERVER_STREAM_MESSAGES_IN_PROGRESS=true

6. Run database migration:

   langflow migration upgrade head

4. Production Considerations

This demonstration is NOT production-ready due to:

• Dependency on unreleased MCP SDK main branch
• Requirement for modified mcp-proxy package
• Potential instability from upstream changes

For production deployment, the Langflow team should:

1. Wait for official MCP SDK 2.0 release
2. Coordinate with mcp-proxy maintainers to merge PR Number of requested results 4 cannot be greater than number of elements in index 3  #189
3. Update dependencies to use stable, released versions
4. Add version pinning for all dependencies
5. Conduct thorough testing with stable dependency versions

Backend Implementation

The backend implementation spans multiple functional areas to enable nested progress notifications:

1. Database Schema Extensions

Purpose: Support parent-child message relationships and nested content blocks

Changes:

• Added database migration for new fields on Message model
• Extended Message model with parent_message_id and tool_call_id fields to track parent-child relationships
• Extended ContentBlock schema with nested_blocks field for recursive nesting
• Added nesting_depth and block_type fields for UI rendering and classification
• All fields are optional for backward compatibility

Impact: Messages can now form hierarchical structures, and content blocks can contain nested child blocks

Files Modified:

• Database migration script
• Message model definitions (backend and lfx)
• ContentBlock schema definitions (backend and lfx)

2. MCP Protocol Integration

Purpose: Enable progress notification streaming from child flows to parent flows via MCP protocol

Changes:

• Upgraded to MCP SDK main branch with breaking API changes
• Refactored from decorator-based to constructor-based handler registration
• Added progress_callback parameter to MCP client implementations (stdio and HTTP/SSE)
• Implemented progress handlers that extract messages from MCP notifications
• Clients now pass progressToken via meta parameter to MCP SDK
• Updated handler signatures to accept (ctx, params) with ServerRequestContext

Impact: Child flows running as MCP tools can now stream progress messages back to parent flows in real-time

Files Modified:

• MCP client implementations (stdio and HTTP)
• MCP server handlers and utilities
• MCP component integration
• Configuration utilities

3. Agent Message Routing System

Purpose: Intelligently route child agent notifications to parent message's nested structure

Changes:

• Implemented in-memory tool call tracking registry mapping tool invocations to parent messages
• Added message type detection to classify progress notifications (tool_progress, agent_steps, tool_invocation, final_answer)
• Created message formatting system with emoji indicators (🔄, ✅, 🔨, 📊)
• Implemented progress callback injection mechanism for tools invoked by agents
• Added nested block routing logic to add child notifications to parent's nested_blocks array
• Implemented deduplication logic to update existing blocks instead of creating duplicates
• Added message ID tracking for smart updates (replace mode vs append mode)

Impact: Child agent progress appears nested under parent's tool call in real-time, with proper classification and no duplicates

Files Modified:

• Agent base class (core logic)
• Agent events handling
• Component tool wrapper

4. Message Persistence & Caching

Purpose: Efficiently persist nested blocks and prevent data loss during concurrent updates

Changes:

• Enhanced message update logic to preserve nested_blocks during database operations
• Implemented smart merge strategy to avoid losing nested blocks during streaming updates
• Added in-memory message caching for efficient nested block updates
• Implemented replace mode logic for updating existing messages instead of creating duplicates
• Added nested block serialization to JSONB format
• Fixed message merge issues that were overwriting nested_blocks from database

Impact: Nested blocks are reliably persisted to database and survive concurrent updates from streaming events

Files Modified:

• Memory/persistence layer
• Component base class (caching and replace mode)
• Event handling (merge logic)

5. Component Integration

Purpose: Connect all pieces together for seamless nested notification flow

Changes:

• Updated MCP component to use agent callback when present
• Added callback storage on component for tool access
• Implemented callback extraction from tool metadata
• Enhanced component to pass progress_callback through to MCP client
• Added chat output component support for nested notifications

Impact: Complete end-to-end flow from child agent → MCP protocol → parent agent → nested UI display

Files Modified:

• MCP component
• Component tool wrapper
• Chat output component
• Agent component

6. Feature Flag Control

Purpose: Enable safe rollout with ability to disable feature if issues arise

Changes:

• Added environment variable LANGFLOW_MCP_SERVER_STREAM_MESSAGES_IN_PROGRESS
• When enabled (true): Child notifications nested under parent tool call
• When disabled (false): Original behavior with flat message structure
• Default: Disabled for backward compatibility

Impact: Feature can be gradually rolled out and easily disabled if needed

Files Modified:

• Settings configuration

Key Backend Features

Message Type Detection

Automatically classifies progress notifications based on content patterns:

• Tool Progress (📊): Initial progress messages
• Agent Steps (🔄): Agent reasoning and planning
• Tool Invocation (🔨): Specific tool calls with parameters
• Final Answer (✅): Completed responses

Smart Message Updates

• Tracks messages by type using unique IDs
• Updates existing messages instead of creating duplicates
• Shared tracking IDs for related message types (e.g., tool_progress → agent_steps)
• Replace mode prevents duplicate agent steps, final answers, and tool invocations

Nested Block Hierarchy

• Recursive ContentBlock structure supports unlimited nesting depth
• Practical limit of 3 levels for performance and UX
• Each nested block tracks its depth for proper UI rendering
• Blocks classified by type for appropriate formatting

Real-Time Streaming

• Progress callbacks injected into tool invocations
• Immediate database persistence after each nested block addition
• Streaming events sent to frontend for real-time UI updates
• Incremental updates minimize network traffic

Deduplication Logic

• Checks for existing blocks by block_type before creating new ones
• Updates existing block content instead of appending duplicates
• Handles rapid progress notifications without creating clutter
• In-memory caching enables efficient lookups

Testing & Validation

Test Scenario: Parent-Child Agent Flow

Setup:

1. Parent agent with tool: "GET_DATA_PRODUCTS" (child agent)
2. Child agent performs metadata lookup
3. Child sends 4 progress notifications

Expected Result:

Parent Agent Message
└─ Called tool: GET_DATA_PRODUCTS [Expandable ▼]
   ├─ 📊 Tool Progress [Expandable ▼]
   ├─ 🔄 Agent Steps [Expandable ▼]
   ├─ 🔨 Tool Invocation [Expandable ▼]
   └─ ✅ Final Answer [Expandable ▼]

Actual Result: ✅ All nested blocks render correctly with proper hierarchy

Implementation Details

For complete implementation details, please refer to the feature branch which contains:

• All source code changes
• Comprehensive commit history
• Database migration script
• Bug fixes and improvements

Compare with Main: View all changes

Conclusion

The nested progress notifications feature transforms Langflow's multi-agent experience by providing complete transparency into child agent operations. This enhancement addresses a critical gap in agent-to-agent visibility, making complex workflows easier to understand, debug, and trust.

Links

• Implementation Branch: feature/mcp-sdk-main-branch-migration
• Compare with Main: View all changes

Motivation

Executive Summary

This document proposes a feature enhancement to Langflow that enables nested progress notifications in multi-agent workflows. This feature provides complete transparency into child agent operations by displaying their progress updates hierarchically within the parent agent's tool invocation, rather than as separate top-level messages.

Business Value:

• Improved user experience in complex multi-agent workflows
• Clear visual hierarchy showing parent-child agent relationships
• Better debugging and monitoring capabilities for agent orchestration
• Organizations can combine simple MCP tools with complex Langflow flow tools, guaranteeing operations happen in a particular way rather than relying entirely on agentic skills
• Enhanced compliance and auditing capabilities for enterprise users

Problem Statement

Current Behavior: Lack of Agent-to-Agent Transparency

When a parent agent invokes a child agent as a tool in Langflow, users cannot see what the child agent is doing. The current implementation has several critical limitations:

1. Invisible Child Agent Operations

• Parent agent shows "Called tool: CHILD_FLOW" with execution time
• Child agent's internal steps are completely hidden from the user
• No visibility into which tools the child agent invokes
• No insight into the child agent's reasoning process

2. Flat Message Structure

All messages appear at the same level in the chat interface:

User: "What is the metadata for product ABC?"
├─ Parent Agent: Called tool GET_DATA_PRODUCTS (7.5s)
├─ 📊 Tool Progress: "What is the metadata..."  ← Child notification (orphaned)
├─ 🔄 Agent Steps: "Processing request..."      ← Child notification (orphaned)
├─ 🔨 Tool: get_metadata                        ← Child notification (orphaned)
├─ ✅ AI: "Here's the metadata..."              ← Child notification (orphaned)
└─ Parent Agent: "Here's the metadata..."

Problems:

• Child notifications appear as separate top-level messages
• No visual connection between parent tool call and child operations
• Difficult to understand which messages belong to which agent
• Cluttered interface with orphaned progress messages

3. Poor User Experience in Complex Workflows

• Users cannot trace execution flow in multi-agent systems
• Debugging agent orchestration is difficult
• No way to understand why a tool call took a long time
• Enterprise users need transparency for compliance and auditing

Your Contribution

No response