Merge pull request #19 from seymourtang/feat/convoai

feat: Add new API: HistoryConvoAIAPI, InterruptConvoAIAPI, and SpeakConvoAIAPI to ConvoAIClient

Author: seymourtang

agora-rest-client-core/src/main/java/io/agora/rest/services/convoai/ConvoAIClient.java

@@ -4,10 +4,14 @@
 import io.agora.rest.core.DefaultContext;
 import io.agora.rest.services.convoai.req.JoinConvoAIReq;
 import io.agora.rest.services.convoai.req.ListConvoAIReq;
+import io.agora.rest.services.convoai.req.SpeakConvoAIReq;
 import io.agora.rest.services.convoai.req.UpdateConvoAIReq;
+import io.agora.rest.services.convoai.res.HistoryConvoAIRes;
+import io.agora.rest.services.convoai.res.InterruptConvoAIRes;
 import io.agora.rest.services.convoai.res.JoinConvoAIRes;
 import io.agora.rest.services.convoai.res.ListConvoAIRes;
 import io.agora.rest.services.convoai.res.QueryConvoAIRes;
+import io.agora.rest.services.convoai.res.SpeakConvoAIRes;
 import io.agora.rest.services.convoai.res.UpdateConvoAIRes;
 import reactor.core.publisher.Mono;
 
@@ -18,7 +22,8 @@ public abstract class ConvoAIClient {
     /**
      * @param convoAIConfig Instance of {@link ConvoAIConfig}.
      * @return Returns the Conversational AI engine client instance.
-     * @brief Creates a Conversational AI engine client with the specified configuration.
+     * @brief Creates a Conversational AI engine client with the specified
+     *        configuration.
      * @since v0.3.0
      */
     public static synchronized ConvoAIClient create(ConvoAIConfig convoAIConfig) {
@@ -36,11 +41,13 @@ public static synchronized ConvoAIClient create(ConvoAIConfig convoAIConfig) {
     }
 
     /**
-     * @param request Parameters for the join request to the conversational AI engine, see {@link JoinConvoAIReq}.
+     * @param request Parameters for the join request to the conversational AI
+     *                engine, see {@link JoinConvoAIReq}.
      * @return Returns the join response result, see {@link JoinConvoAIRes}.
      * @brief Creates an agent instance and joins the specified RTC channel.
      * @example Use this to create an agent instance in an RTC channel.
-     * @post After successful execution, the agent will join the specified channel. You can perform subsequent operations using the returned agent ID.
+     * @post After successful execution, the agent will join the specified channel.
+     *       You can perform subsequent operations using the returned agent ID.
      * @since v0.3.0
      */
     public abstract Mono<JoinConvoAIRes> join(JoinConvoAIReq request);
@@ -49,18 +56,23 @@ public static synchronized ConvoAIClient create(ConvoAIConfig convoAIConfig) {
      * @param agentId Agent ID
      * @brief Stops the specified agent instance and leaves the RTC channel.
      * @example Use this to stop an agent instance.
-     * @post After successful execution, the agent will be stopped and leave the RTC channel.
-     * @note Ensure the agent ID has been obtained by calling the join API before using this method.
+     * @post After successful execution, the agent will be stopped and leave the RTC
+     *       channel.
+     * @note Ensure the agent ID has been obtained by calling the join API before
+     *       using this method.
      * @since v0.3.0
      */
     public abstract Mono<Void> leave(String agentId);
 
     /**
-     * @param request Parameters for listing conversational agents, see {@link ListConvoAIReq}.
-     * @return Returns the list response result, see {@link ListConvoAIRes} for details.
+     * @param request Parameters for listing conversational agents, see
+     *                {@link ListConvoAIReq}.
+     * @return Returns the list response result, see {@link ListConvoAIRes} for
+     *         details.
      * @brief Retrieves a list of agents that meet the specified criteria.
      * @example Use this to get a list of agents that meet the specified criteria.
-     * @post After successful execution, a list of agents that meet the specified criteria will be retrieved.
+     * @post After successful execution, a list of agents that meet the specified
+     *       criteria will be retrieved.
      * @since v0.3.0
      */
     public abstract Mono<ListConvoAIRes> list(ListConvoAIReq request);
@@ -70,22 +82,61 @@ public static synchronized ConvoAIClient create(ConvoAIConfig convoAIConfig) {
      * @return Returns the query response result, see {@link QueryConvoAIRes}
      * @brief Query the current status of the specified agent instance.
      * @example Use this to get the current status of the specified agent instance.
-     * @post After successful execution, the current running status information of the specified agent instance will be retrieved.
-     * @note Ensure the agent ID has been obtained by calling the join API before using this method.
+     * @post After successful execution, the current running status information of
+     *       the specified agent instance will be retrieved.
+     * @note Ensure the agent ID has been obtained by calling the join API before
+     *       using this method.
      * @since v0.3.0
      */
     public abstract Mono<QueryConvoAIRes> query(String agentId);
 
     /**
      * @param agentId Agent ID
-     * @param request Parameters for updating the conversational agent, see {@link UpdateConvoAIReq} for details.
-     * @return Returns the update response result, see {@link UpdateConvoAIRes}.
+     * @param request Parameters for updating the conversational agent, see
+     *                {@link UpdateConvoAIReq} for details.
+     * @return Returns the update response result, see {@link UpdateConvoAIRes}
+     *         for details.
      * @brief Adjusts the agent's parameters at runtime.
      * @example Use this to adjust the agent's parameters at runtime.
      * @post After successful execution, the agent's parameters will be adjusted.
-     * @note Ensure the agent ID has been obtained by calling the join API before using this method.
+     * @note Ensure the agent ID has been obtained by calling the join API before
+     *       using this method.
      * @since v0.3.0
      */
     public abstract Mono<UpdateConvoAIRes> update(String agentId, UpdateConvoAIReq request);
 
+    /**
+     * @brief Acquires the short-term memory of the specified agent instance
+     * @since v0.4.0
+     * @example Use this method to acquire the short-term memory of the specified
+     *          agent instance.
+     * @param agentId Agent ID.
+     * @return Returns the short-term memory of the specified agent instance. See
+     *         {@link HistoryConvoAIRes} for details.
+     */
+    public abstract Mono<HistoryConvoAIRes> getHistory(String agentId);
+
+    /**
+     * @brief Interrupts the specified agent instance
+     * @since v0.9.0
+     * @example Use this method to interrupt the specified agent instance.
+     * @param agentId Agent ID.
+     * @return Returns the interrupt response result, see
+     *         {@link InterruptConvoAIRes}.
+     */
+    public abstract Mono<InterruptConvoAIRes> interrupt(String agentId);
+
+    /**
+     * @brief Speaks a custom message for the specified agent instance
+     * @since v0.9.0
+     * @example Use this method to speak a custom message for the specified agent
+     *          instance.
+     * @param agentId Agent ID.
+     * @param request Request body for the specified agent to speak a custom
+     *                message. See {@link SpeakConvoAIReq} for details.
+     * @return Returns the response *SpeakResp. See {@link SpeakConvoAIRes} for
+     *         details.
+     */
+    public abstract Mono<SpeakConvoAIRes> speak(String agentId, SpeakConvoAIReq request);
+
 }

agora-rest-client-core/src/main/java/io/agora/rest/services/convoai/ConvoAIClientImpl.java

@@ -5,10 +5,14 @@
 import io.agora.rest.services.convoai.api.*;
 import io.agora.rest.services.convoai.req.JoinConvoAIReq;
 import io.agora.rest.services.convoai.req.ListConvoAIReq;
+import io.agora.rest.services.convoai.req.SpeakConvoAIReq;
 import io.agora.rest.services.convoai.req.UpdateConvoAIReq;
+import io.agora.rest.services.convoai.res.HistoryConvoAIRes;
+import io.agora.rest.services.convoai.res.InterruptConvoAIRes;
 import io.agora.rest.services.convoai.res.JoinConvoAIRes;
 import io.agora.rest.services.convoai.res.ListConvoAIRes;
 import io.agora.rest.services.convoai.res.QueryConvoAIRes;
+import io.agora.rest.services.convoai.res.SpeakConvoAIRes;
 import io.agora.rest.services.convoai.res.UpdateConvoAIRes;
 import reactor.core.publisher.Mono;
 
@@ -24,6 +28,12 @@ public class ConvoAIClientImpl extends ConvoAIClient {
 
     private final UpdateConvoAIAPI updateConvoAIAPI;
 
+    private final HistoryConvoAIAPI historyConvoAIAPI;
+
+    private final InterruptConvoAIAPI interruptConvoAIAPI;
+
+    private final SpeakConvoAIAPI speakConvoAIAPI;
+
     private final static String chineseMainlandPrefixTpl = "/cn/api/conversational-ai-agent/v2/projects/%s";
 
     private final static String globalPrefixTpl = "/api/conversational-ai-agent/v2/projects/%s";
@@ -35,6 +45,9 @@ protected ConvoAIClientImpl(Context context, ConvoAIServiceRegionEnum serviceReg
         listConvoAIAPI = new ListConvoAIAPI(context, pathPrefix);
         queryConvoAIAPI = new QueryConvoAIAPI(context, pathPrefix);
         updateConvoAIAPI = new UpdateConvoAIAPI(context, pathPrefix);
+        historyConvoAIAPI = new HistoryConvoAIAPI(context, pathPrefix);
+        interruptConvoAIAPI = new InterruptConvoAIAPI(context, pathPrefix);
+        speakConvoAIAPI = new SpeakConvoAIAPI(context, pathPrefix);
     }
 
     private String getPathPrefix(Context context, ConvoAIServiceRegionEnum serviceRegionEnum) {
@@ -75,4 +88,16 @@ public Mono<QueryConvoAIRes> query(String agentId) {
     public Mono<UpdateConvoAIRes> update(String agentId, UpdateConvoAIReq request) {
         return updateConvoAIAPI.handle(agentId, request);
     }
+
+    public Mono<HistoryConvoAIRes> getHistory(String agentId) {
+        return historyConvoAIAPI.handle(agentId);
+    }
+
+    public Mono<InterruptConvoAIRes> interrupt(String agentId) {
+        return interruptConvoAIAPI.handle(agentId);
+    }
+
+    public Mono<SpeakConvoAIRes> speak(String agentId, SpeakConvoAIReq request) {
+        return speakConvoAIAPI.handle(agentId, request);
+    }
 }

agora-rest-client-core/src/main/java/io/agora/rest/services/convoai/ConvoAIConfig.java

@@ -113,6 +113,11 @@ public Builder domainArea(DomainArea domainArea) {
             return this;
         }
 
+        public Builder httpProperty(HttpProperty httpProperty) {
+            this.httpProperty = httpProperty;
+            return this;
+        }
+
         public Builder serverRegion(ConvoAIServiceRegionEnum serverRegion) {
             this.serviceRegion = serverRegion;
             return this;

agora-rest-client-core/src/main/java/io/agora/rest/services/convoai/api/HistoryConvoAIAPI.java

@@ -0,0 +1,22 @@
+package io.agora.rest.services.convoai.api;
+
+import io.agora.rest.core.Context;
+import io.agora.rest.services.convoai.res.HistoryConvoAIRes;
+import io.netty.handler.codec.http.HttpMethod;
+import reactor.core.publisher.Mono;
+
+public class HistoryConvoAIAPI {
+    private final Context context;
+
+    private final String pathPrefix;
+
+    public HistoryConvoAIAPI(Context context, String pathPrefix) {
+        this.context = context;
+        this.pathPrefix = pathPrefix;
+    }
+
+    public Mono<HistoryConvoAIRes> handle(String agentId) {
+        String path = String.format("%s/agents/%s/history", pathPrefix, agentId);
+        return this.context.sendRequest(path, HttpMethod.GET, null, HistoryConvoAIRes.class);
+    }
+}

agora-rest-client-core/src/main/java/io/agora/rest/services/convoai/api/InterruptConvoAIAPI.java

@@ -0,0 +1,22 @@
+package io.agora.rest.services.convoai.api;
+
+import io.agora.rest.core.Context;
+import io.agora.rest.services.convoai.res.InterruptConvoAIRes;
+import io.netty.handler.codec.http.HttpMethod;
+import reactor.core.publisher.Mono;
+
+public class InterruptConvoAIAPI {
+    private final Context context;
+
+    private final String pathPrefix;
+
+    public InterruptConvoAIAPI(Context context, String pathPrefix) {
+        this.context = context;
+        this.pathPrefix = pathPrefix;
+    }
+
+    public Mono<InterruptConvoAIRes> handle(String agentId) {
+        String path = String.format("%s/agents/%s/interrupt", pathPrefix, agentId);
+        return this.context.sendRequest(path, HttpMethod.POST, null, InterruptConvoAIRes.class);
+    }
+}

agora-rest-client-core/src/main/java/io/agora/rest/services/convoai/api/SpeakConvoAIAPI.java

@@ -0,0 +1,24 @@
+package io.agora.rest.services.convoai.api;
+
+import io.agora.rest.core.Context;
+import io.agora.rest.services.convoai.req.SpeakConvoAIReq;
+import io.agora.rest.services.convoai.res.SpeakConvoAIRes;
+import io.netty.handler.codec.http.HttpMethod;
+import reactor.core.publisher.Mono;
+
+public class SpeakConvoAIAPI {
+    private final Context context;
+
+    private final String pathPrefix;
+
+    public SpeakConvoAIAPI(Context context, String pathPrefix) {
+        this.context = context;
+        this.pathPrefix = pathPrefix;
+    }
+
+    public Mono<SpeakConvoAIRes> handle(String agentId, SpeakConvoAIReq request) {
+        String path = String.format("%s/agents/%s/speak", pathPrefix, agentId);
+        return this.context.sendRequest(path, HttpMethod.POST, request, SpeakConvoAIRes.class);
+    }
+
+}