Principle:OpenHands OpenHands Progress Notification

Knowledge Sources	OpenHands
Domains	Platform_Integration, Webhook_Processing
Last Updated	2026-02-11 21:00 GMT

Overview

Progress notification is the feedback loop pattern of posting agent progress updates back to the originating platform during asynchronous execution, keeping users informed about the status of long-running automated tasks.

Description

When an AI agent is working on a task triggered by a webhook event, the execution may take minutes or even longer. During this time, the user who triggered the event -- and any collaborators watching the issue or pull request -- have no visibility into what the agent is doing unless the system actively pushes status updates back to the originating platform. Progress notification closes this visibility gap.

The pattern involves three core concerns:

1. Message formatting -- Translating internal agent state (tool calls, intermediate results, error messages) into human-readable messages appropriate for the target platform. GitHub comments support markdown; Slack messages support blocks; each platform has its own formatting conventions.
2. Target resolution -- Determining where to post the update. The notification must go to the correct issue, pull request, or review thread, and in the correct form (top-level comment vs. inline review reply).
3. Platform-specific posting -- Authenticating to the platform API and creating the comment or message. This requires the correct scoped token, the correct API endpoint, and proper error handling for rate limits, permissions, and network failures.

Usage

Apply this pattern when:

• The agent's execution takes more than a few seconds and users expect visibility
• The agent produces intermediate results (partial fixes, clarifying questions) that benefit from early disclosure
• Multiple stakeholders are watching the same resource and need to stay informed
• The system needs to request human input mid-execution (e.g., asking for clarification on ambiguous requirements)

Theoretical Basis

1. Observer Pattern

Progress notification implements the Observer pattern from the GoF design patterns. The originating platform resource (issue, PR) acts as the subject, and users watching it are observers. The agent acts as a state-change producer that notifies observers through the platform's notification system:

notify_observers(resource, message):
    post_comment(resource, format_message(message))
    # Platform automatically notifies all watchers/subscribers

This leverages the platform's built-in notification infrastructure (email, web push, mobile alerts) rather than building a separate notification system.

2. Feedback Loop Theory

In control theory, a feedback loop is a mechanism by which a system's output is fed back as input to regulate its behavior. In the context of agent execution, progress notifications create a feedback loop between the agent and the user:

Agent produces output -> Notification posted -> User reads notification
                                                       |
                                                       v
                                              User provides feedback
                                                       |
                                                       v
                                              New webhook event -> Agent adjusts

This loop enables collaborative automation, where the user and agent work together iteratively rather than the agent operating in isolation.

3. Message Routing

The notification must be routed to the correct target. The routing function maps from the view type to a platform-specific API call:

route_message(view, message):
    match view:
        case Issue:
            post_issue_comment(view.repo, view.issue_number, message)
        case PRComment:
            post_pr_comment(view.repo, view.pr_number, message)
        case InlinePRComment:
            reply_to_review_thread(view.repo, view.pr_number,
                                   view.thread_id, message)

The routing logic is determined by the view type, which was established during the payload parsing phase.

4. Rate Limiting and Batching

Platform APIs impose rate limits on comment creation. The notification layer must respect these limits to avoid being throttled or blocked:

post_with_rate_limit(resource, message):
    if rate_limit_remaining() > THRESHOLD:
        post_immediately(resource, message)
    else:
        buffer_and_batch(resource, message)

In practice, notifications are often batched (multiple intermediate updates consolidated into a single comment) or throttled (posted at most once per N seconds) to stay within rate limits.

Related Pages

Implemented By

• Implementation:OpenHands_OpenHands_GithubManager_Send_Message