Agent V2: expose configured human contacts in Composer for ask_human
- 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
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