AgentWorks documentation

Human Feedback System

Purpose

human_feedback is a short-lived, blocking tool for input that only a human can provide. Typical uses are:

• OTP or 2FA codes
• CAPTCHA completion
• Explicit approval before an irreversible action
• A private value or subjective decision that another agent must not infer

It is not a general agent-to-agent question mechanism and it is not intended for questions that may remain unanswered for hours or days. Long-lived workflow/report questions use the persistent report/Pulse human-input records instead.

The workflow waits, but the AgentWorks/Electron application does not block. The user receives an interactive card and submits the response directly to the backend. The Workflow Builder is not an intermediary and has no answer-submission tool.

Runtime flow

1. The agent calls human_feedback with a unique request ID, a human-facing message, and an appropriate timeout.
2. The backend registers the pending request before publishing any UI event. This prevents a fast UI answer from racing request creation.
3. A blocking_human_feedback event renders an interactive card in AgentWorks.
4. Browser/Electron and configured connector notifications are triggered immediately because these requests are short-lived.
5. The user answers the card, or a supported interactive connector submits the correlated answer.
6. POST /api/human-feedback/submit writes the response to HumanFeedbackStore, which wakes only the waiting workflow call.
7. The tool returns the response to the calling agent, and the store deletes the pending request and answer.
8. If the timeout expires first, the request is deleted and the tool returns an expiry error.

sequenceDiagram
    participant Agent
    participant Tool as human_feedback
    participant Store as HumanFeedbackStore
    participant UI as AgentWorks UI
    participant API as /api/human-feedback/submit
    participant Human

    Agent->>Tool: message, unique_id, timeout_seconds
    Tool->>Store: Register pending request
    Tool->>UI: blocking_human_feedback event
    UI->>Human: Card + immediate notification
    Tool->>Store: Wait for bounded timeout
    Human->>UI: Enter answer
    UI->>API: Submit request ID + answer
    API->>Store: SubmitResponse
    Store-->>Tool: Wake with answer
    Store->>Store: Delete request and answer
    Tool-->>Agent: Tool result

There is deliberately no Builder/chat hop in this sequence. A saved Builder session cannot answer, delay, rewrite, or retain the response.

Tool contract

{
  "tool": "human_feedback",
  "arguments": {
    "message_for_user": "Enter the six-digit code sent to your phone.",
    "unique_id": "login-otp-1712345678",
    "timeout_seconds": 120
  }
}

The agent should use an expiry supplied by the external service when available and otherwise choose the shortest realistic timeout.

Direct submission and UI behavior

The frontend submits through agentApi.submitHumanFeedback() to:

POST /api/human-feedback/submit
{
  "unique_id": "login-otp-1712345678",
  "response": "..."
}

The API requires a currently pending request. A late response after expiry is rejected rather than being applied to another workflow turn.

Potentially private response text is not included in server or browser console logs, OS notification previews, or the frontend's localStorage. The frontend persists only a short-lived boolean marker so a completed historical event does not reopen after a page refresh.

Workflow human_input steps

Configured human_input plan steps use the same direct request store, UI card, endpoint, and connector path. Text, yes/no, and multiple-choice steps no longer forward questions into the Workflow Builder. These configured steps currently retain their existing ten-minute wait; the agent-selected timeout_seconds field applies to explicit human_feedback tool calls.

Notification behavior

• The AgentWorks response card is the primary interaction surface.
• Browser/Electron notifications appear as soon as the card is available when notification permission is granted.
• Notification previews use generic text and do not expose the question or answer.
• The Electron dock badge stays active while the displayed request is pending.
• Configured interactive connectors are notified immediately for these short-lived requests.
• Workflow Slack Incoming Webhooks are not used here. They are one-way notify_user destinations and cannot submit the correlated answer this blocking flow requires.
• The older ScheduleNotification helper still supports a two-minute reminder for legacy/non-urgent callers; direct human-input paths use ScheduleNotificationAfter(..., 0).

An app-wide durable Electron notification inbox is a separate capability. This flow uses the current event renderer, native notification, badge, and connector infrastructure.

Key implementation files

Operational rules

• Generate a fresh unique_id for every request.
• Do not ask an agent-answerable clarification through human_feedback.
• Do not use this tool for asynchronous questions that may be answered days later.
• Do not put OTPs or private values in the question; the sensitive value belongs only in the response.
• Handle timeout errors explicitly. Never assume approval when a request expires.
• Never reintroduce a chat/Builder relay for these answers.