langgenius / langgenius/dify

Agent V2: expose configured human contacts in Composer for ask_human

Open
#42,216 0 comments 1 reaction 0 assignees View on GitHub
Dominant language
TypeScript
Stars
156k
Forks
24.6k
Avg merge
22h 9m
Merged PRs (30d)
610

Description

## Problem

Agent V2 already has a complete backend/runtime path for human involvement, but the current Web Composer does not expose a way to configure the `AgentSoul.human.contacts` that activate it.

The gap is between shipped capability and usable product surface:

- `AgentSoulHumanConfig` persists `human.contacts`.
- Agent Composer responses already carry the currently configured `human_contacts` shape.
- prompt mentions already support human references.
- Agent runtime treats `human` as a supported feature and injects `dify.ask_human` only when human contacts are configured.
- the merged `ask_human` HITL path already pauses/resumes both Workflow Agent V2 and standalone Agent V2 chat.

However, the current Web Agent Composer form state has no human-contact field or configuration action.

One important detail: the existing Composer `human_contacts` candidate field is currently a reflection of contacts already present in the Agent Soul, not an available Human roster. `human_roster_available` also defaults to `false` in current main. So the missing Web layer is not just rendering an existing picker response; it also needs to reuse the correct existing workspace-member / Human Input recipient source rather than inventing a new roster API.

This means a backend capability that is already implemented is not discoverable/configurable through the normal Agent V2 Studio flow.

## Current behavior

A user can configure prompt, model, tools, knowledge, skills/files, environment variables, and app features in Agent V2 Composer, but cannot select the human contacts required to enable `dify.ask_human`.

Existing human-contact data is preserved through Composer saves because `formStateToAgentSoulConfig()` spreads the existing base config; this is therefore **not** a data-loss report. The product gap is configuration/discoverability.

## Proposed bounded scope

Treat Human as a native Prompt reference in Agent V2 Composer, backed by existing workspace identity and `agent_soul.human.contacts` persistence:

1. model `humanContacts` in Composer form state and round-trip them through Agent Soul;
2. reuse the existing workspace-member / Human Input recipient source rather than add a new roster API;
3. expose configured/available Humans through the Prompt reference interaction so selecting a person both inserts the human mention at the editing position and ensures the matching `human.contacts` entry exists;
4. keep Human mention/contact state consistent when a reference is removed;
5. render/validate missing Human references consistently with the other Composer reference types;
6. add focused conversion/store/editor/UI coverage.

This follows the existing backend contract: configured human involvement must be referenced from the corresponding Prompt surface, and the shipped `ask_human` implementation already relies on the existing mention-expansion path.

## Out of scope

- new Human roster CRUD or a new identity system;
- changes to `dify.ask_human` runtime semantics;
- new HITL delivery infrastructure;
- Slack support;
- legacy Agent behavior;
- redesigning Human Input forms;
- broadening this first slice to arbitrary external-email contacts.

The intent is to connect the final Web configuration layer to capability that is already present upstream, not to introduce a new HITL architecture.

I am implementing this in PR #42217. If this direction is acceptable, please assign this issue to me so I can carry the implementation through review without duplicate work.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing PR #42217 and the Agent V2 Composer entry points named in the issue, especially formStateToAgentSoulConfig() and AgentSoul.human.contacts. Trace how Prompt references and existing workspace-member or Human Input recipients are represented. Done means Composer can round-trip contacts, insert and remove Human references consistently, validate them, and has focused conversion, store, editor, and UI coverage.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
frontend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.