feat(examples): add HITL interactive UI example with fitness coach

[LearningGp]

AgentScope-Java Version

1.0.10

Description

Added an example to demonstrate the HITL (Human-in-the-Loop) implementations discussed earlier.
FYI, #743

Checklist

Please check the following items before code is ready to be reviewed.

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[gemini-code-assist]

Summary of Changes

Hello @LearningGp, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new advanced example demonstrating Human-in-the-Loop (HITL) capabilities within the AgentScope framework. It showcases how an AI fitness coach agent can engage in dynamic, structured interactions with a user through a web-based UI. The example highlights the use of custom tools to request specific user input (e.g., fitness goals, body info) and to seek explicit confirmation for sensitive actions like adding calendar events, thereby enhancing user control and transparency in agent-driven workflows.

Highlights

• New Human-in-the-Loop (HITL) Example: Introduced a new interactive UI example demonstrating Human-in-the-Loop capabilities for an AI fitness coach, showcasing dynamic user interaction and tool confirmation.
• Dynamic User Interaction Tool: Developed a UserInteractionTool that allows the agent to dynamically request structured input from the user via various UI components (text, select, form, date, number), pausing agent execution until a response is received.
• Tool Confirmation Mechanism: Implemented a ToolConfirmationHook to enable explicit user approval for 'dangerous' agent actions, such as adding calendar events, enhancing user control and transparency.
• Mock Calendar Event Tool: Created a mock AddCalendarEventTool to simulate calendar integration, specifically designed to trigger the user confirmation flow.
• Interactive Frontend: Provided a comprehensive web frontend (HTML, CSS, JavaScript) to render the interactive UI, handle real-time communication via Server-Sent Events (SSE), and manage dynamic form rendering.
• Agent Observation Hook: Added an ObservationHook for detailed logging of agent conversation, reasoning steps, and tool input/output, aiding in debugging and understanding agent behavior.

Changelog

• agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/hitl/AddCalendarEventTool.java
  • Added a mock tool for adding calendar events, designed to require user approval before execution.
• agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/hitl/HitlInteractionExample.java
  • Added the main Spring Boot application for the HITL interactive UI example, integrating the fitness coach agent, user interaction tools, and SSE for real-time communication.
• agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/hitl/ObservationHook.java
  • Added a hook to log detailed agent conversation and tool input/output for debugging and monitoring.
• agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/hitl/ToolConfirmationHook.java
  • Added a hook to intercept and pause agent execution when tools requiring user confirmation are called.
• agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/hitl/UserInteractionTool.java
  • Added a tool that suspends agent execution to prompt the user for structured input via various UI types.
• agentscope-examples/advanced/src/main/resources/static/hitl-interaction/app.js
  • Added JavaScript code to handle frontend logic, SSE event processing, dynamic UI rendering for user interactions, and tool confirmation.
• agentscope-examples/advanced/src/main/resources/static/hitl-interaction/index.html
  • Added the HTML structure for the interactive chat interface, including welcome messages, example queries, and language switching.
• agentscope-examples/advanced/src/main/resources/static/hitl-interaction/style.css
  • Added CSS styling for the interactive UI, ensuring a clean and responsive user experience.

Activity

• Pull request created by LearningGp.
• Initial commit includes a new Human-in-the-Loop (HITL) interactive UI example for an AI fitness coach.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive Human-in-the-Loop (HITL) interactive UI example. It adds several new Java classes: AddCalendarEventTool for simulating calendar event additions, UserInteractionTool for dynamic user input, ToolConfirmationHook to intercept tools requiring user approval, and ObservationHook for detailed console logging of agent events. The HitlInteractionExample class orchestrates these components, setting up a ReActAgent and exposing REST endpoints for chat, user responses, session management, and tool confirmation via Server-Sent Events (SSE). The frontend, implemented with app.js, index.html, and style.css, provides a dynamic chat interface that renders various UI components (text, select, form, date, number inputs) based on agent requests and handles user interactions and tool confirmations. Review comments suggest refining error handling in HitlInteractionExample.java by using more specific exception types for ObjectMapper operations, improving code readability in ObservationHook.java by using Java's switch statement with pattern matching, and enhancing type safety in UserInteractionTool.java by explicitly typing defaultValue as String.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Adds a new advanced example demonstrating HITL (Human-in-the-Loop) interactions via a dynamic, form-driven web UI, including tool-suspension for user input and pre-execution confirmation for “dangerous” tools.

Changes:

• Added a standalone static web UI (HTML/CSS/JS) that streams agent events over SSE and renders dynamic interaction components.
• Added a Spring Boot example backend that streams agent events, suspends on ask_user, and resumes via /respond and /confirm endpoints.
• Added supporting HITL tools and hooks (ask_user, confirmation hook, observation logging hook).

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
agentscope-examples/advanced/src/main/resources/static/hitl-interaction/style.css	Styling for the HITL interactive chat UI, tool events, and dynamic interaction cards.
agentscope-examples/advanced/src/main/resources/static/hitl-interaction/index.html	Static page shell for the example UI, language toggle, and basic chat controls.
agentscope-examples/advanced/src/main/resources/static/hitl-interaction/app.js	Client-side SSE streaming + rendering for messages, tool events, tool confirmation, and dynamic interaction components.
agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/hitl/UserInteractionTool.java	Defines the ask_user tool that always suspends agent execution to request structured user input.
agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/hitl/ToolConfirmationHook.java	Stops the agent when configured tools are pending, enabling approve/reject UX.
agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/hitl/ObservationHook.java	Logs agent conversation and tool I/O for visibility while running the example.
agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/hitl/HitlInteractionExample.java	Spring Boot app exposing /api/chat, /respond, /confirm, /interrupt, and /session endpoints and mapping agent events to SSE payloads.
agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/hitl/AddCalendarEventTool.java	Mock “dangerous” tool used to demonstrate confirmation-gated execution.