Feat add custom event

[fishl3j]

Add Custom Event Support to AguiEvent

Summary

This issue implements support for Custom events in the AG-UI protocol, providing an extension mechanism for implementing features not covered by the standard event types.

Motivation

The AG-UI protocol currently supports various standard event types (RUN_STARTED, TEXT_MESSAGE_START, TOOL_CALL_START, etc.) and a RAW event type for unstructured custom data. However, there is a need for a structured Custom event type that allows passing custom data with a name identifier, following the AG-UI protocol specification.

Implementation Details

Changes Made

1. Added CUSTOM Event Type

   • Added CUSTOM enum value to AguiEventType
   • Updated event type count from 12 to 13

2. Implemented Custom Event Record

   • Created AguiEvent.Custom record implementing AguiEvent interface
   • Fields:
     • threadId (String, required): Thread ID associated with the event
     • runId (String, required): Run ID associated with the event
     • name (String, required): Name of the custom event
     • value (Object, optional): Value associated with the event
   • Added proper null validation for required fields
   • Implemented JSON serialization/deserialization support via @JsonCreator and @JsonProperty annotations

3. Updated Sealed Interface

   • Added AguiEvent.Custom to the permits clause of the sealed AguiEvent interface
   • Added @JsonSubTypes annotation entry for Custom event type mapping

4. Test Coverage

   • Added comprehensive test suite in CustomTest nested class:
     • Event creation tests
     • Null value handling
     • Complex value handling
     • JSON serialization/deserialization
     • Null parameter validation
     • toString() method verification
   • Updated testEventTypeCount to expect 13 event types
   • Added CUSTOM to testAllEventTypesExist test

Protocol Compliance

The implementation follows the AG-UI protocol specification:

• Custom events include a name field for event identification
• Custom events include a value field for event data
• All standard event properties (threadId, runId) are maintained

Example Usage

import io.agentscope.core.agui.event.AguiEvent;
import io.agentscope.core.agui.event.AguiEventType;
import io.agentscope.core.util.JsonUtils;
import java.util.Map;

// Create a custom event with a name and value
AguiEvent.Custom customEvent = new AguiEvent.Custom(
        "thread-1",
        "run-1",
        "test-event",
        Map.of("key", "value", "number", 42));

// Verify event properties
assertEquals(AguiEventType.CUSTOM, customEvent.getType());
assertEquals("thread-1", customEvent.getThreadId());
assertEquals("run-1", customEvent.getRunId());
assertEquals("test-event", customEvent.name());
assertNotNull(customEvent.value());

// Serialize to JSON
String json = JsonUtils.getJsonCodec().toJson(customEvent);
// JSON contains: "type":"CUSTOM", "name":"test-event", "value":{...}

// Deserialize from JSON
AguiEvent deserialized = JsonUtils.getJsonCodec().fromJson(json, AguiEvent.class);
assertTrue(deserialized instanceof AguiEvent.Custom);
AguiEvent.Custom deserializedCustom = (AguiEvent.Custom) deserialized;
assertEquals("test-event", deserializedCustom.name());

[gemini-code-assist]

Summary of Changes

Hello @xingmengxian, 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 significantly enhances the AG-UI protocol by integrating a new Custom event type. This addition provides a flexible and structured mechanism for developers to define and transmit application-specific events with named identifiers and associated data, moving beyond the limitations of generic raw events. The change ensures protocol compliance and is backed by thorough testing.

Highlights

• New Custom Event Type: Introduced AguiEvent.Custom record to support structured custom events within the AG-UI protocol, allowing for a named identifier and associated data.
• Protocol Extension: Expanded the AguiEvent sealed interface and AguiEventType enum to officially include and handle the new CUSTOM event type, ensuring proper integration into the existing event system.
• Robust Implementation: Ensured proper JSON serialization/deserialization, implemented strict null validation for required fields (threadId, runId, name), and added comprehensive test coverage for the new event type.

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 effectively adds support for CUSTOM events to the AG-UI protocol, which is a valuable extension mechanism. The implementation is clean, follows the existing structure of AguiEvent, and includes a comprehensive set of unit tests for the new functionality. I have a few minor suggestions to improve code formatting consistency and to make the new tests even more robust. Overall, this is a solid contribution.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[AlbumenJ]

Please resolve conflicts

[AlbumenJ]

How to publish this event?

[fishl3j]

Currently, we have certain scenarios where, in addition to the AguiEvent output by AguiAgentAdapter, we need to send an extra card render event to the client for rendering card-based information. This event cannot be effectively carried using a RawEvent.

Moreover, since CustomEvent is already a defined type within the AG-UI protocol, it is theoretically necessary to extend or formalize this capability.

[AlbumenJ]

Currently, this POJO definition is not directly used within AgentScope. Therefore, my question is: how should users utilize it? Does it require directly modifying the implementation of AG-UI in AgentScope?

[fishl3j]

Yes, currently there is no place in AgentScope that actually uses the CustomEvent POJO.

I’m not fully leveraging all the AG-UI features provided by AgentScope—for example, the AguiRestController. Although it exposes a complete RunAgentInputPOJO, some parameters (such as RunAgentInput.context) are not actually used or passed through, which prevents the agent from accessing the context content.

Therefore, I only use the AguiRequestProcessor to directly handle the AG-UI event stream and inject my own custom events.

This is the motivation and rationale behind adding the CustomEvent POJO, which is currently unused by AgentScope.