feat: Add Speak API for conversational AI service with request and response handling

Author: seymourtang

examples/convoai/service/service.go

@@ -197,6 +197,23 @@ func (s *Service) RunWithCustomTTS(ttsVendor req.TTSVendor, ttsParam req.TTSVend
 
 	time.Sleep(time.Second * 1)
 
+	speakResp, err := convoaiClient.Speak(ctx, agentId, &req.SpeakBody{
+		Text:          agoraUtils.Ptr("Hello, how can I help you?"),
+		Priority:      agoraUtils.Ptr("INTERRUPT"),
+		Interruptable: agoraUtils.Ptr(true),
+	})
+	if err != nil {
+		log.Fatalln(err)
+	}
+
+	if speakResp.IsSuccess() {
+		log.Printf("Speak success:%+v", speakResp)
+	} else {
+		log.Printf("Speak failed:%+v", speakResp)
+		return
+	}
+	time.Sleep(time.Second * 1)
+
 	updateResp, err := convoaiClient.Update(ctx, agentId, &req.UpdateReqBody{
 		Token: updateToken,
 	})

services/convoai/api/history.go renamed to services/convoai/api/gethistory.go

@@ -0,0 +1,66 @@
+package api
+
+import (
+	"context"
+	"errors"
+	"net/http"
+
+	"github.com/AgoraIO-Community/agora-rest-client-go/agora"
+	"github.com/AgoraIO-Community/agora-rest-client-go/agora/client"
+	"github.com/AgoraIO-Community/agora-rest-client-go/agora/log"
+	"github.com/AgoraIO-Community/agora-rest-client-go/services/convoai/req"
+	"github.com/AgoraIO-Community/agora-rest-client-go/services/convoai/resp"
+)
+
+type Speak struct {
+	baseHandler
+}
+
+func NewSpeak(module string, logger log.Logger, client client.Client, prefixPath string) *Speak {
+	return &Speak{
+		baseHandler: baseHandler{
+			module:     module,
+			logger:     logger,
+			client:     client,
+			prefixPath: prefixPath,
+		},
+	}
+}
+
+// buildPath returns the request path.
+//
+// /api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/speak
+func (s *Speak) buildPath(agentId string) string {
+	return s.prefixPath + "/agents/" + agentId + "/speak"
+}
+
+func (s *Speak) Do(ctx context.Context, agentId string, body *req.SpeakBody) (*resp.SpeakResp, error) {
+	path := s.buildPath(agentId)
+	responseData, err := s.client.DoREST(ctx, path, http.MethodPost, body)
+	if err != nil {
+		var internalErr *agora.InternalErr
+		if !errors.As(err, &internalErr) {
+			return nil, err
+		}
+	}
+
+	var speakResp resp.SpeakResp
+
+	speakResp.BaseResponse = responseData
+
+	if responseData.HttpStatusCode == http.StatusOK {
+		var successResponse resp.SpeakSuccessResp
+		if err = responseData.UnmarshalToTarget(&successResponse); err != nil {
+			return nil, err
+		}
+		speakResp.SuccessRes = successResponse
+	} else {
+		var errResponse resp.ErrResponse
+		if err = responseData.UnmarshalToTarget(&errResponse); err != nil {
+			return nil, err
+		}
+		speakResp.ErrResponse = errResponse
+	}
+
+	return &speakResp, nil
+}

services/convoai/api/speak.go

@@ -25,6 +25,7 @@ type Client struct {
 	updateAPI    *api.Update
 	interruptAPI *api.Interrupt
 	historyAPI   *api.History
+	speakAPI     *api.Speak
 }
 
 // @brief ServiceRegion represents the region of the Conversational AI engine service
@@ -113,6 +114,7 @@ func NewClient(config *Config) (*Client, error) {
 		updateAPI:    api.NewUpdate("convoai:update", config.Logger, c, prefixPath),
 		interruptAPI: api.NewInterrupt("convoai:interrupt", config.Logger, c, prefixPath),
 		historyAPI:   api.NewHistory("convoai:history", config.Logger, c, prefixPath),
+		speakAPI:     api.NewSpeak("convoai:speak", config.Logger, c, prefixPath),
 	}, nil
 }
 
@@ -266,3 +268,22 @@ func (c *Client) Interrupt(ctx context.Context, agentId string) (*resp.Interrupt
 func (c *Client) GetHistory(ctx context.Context, agentId string) (*resp.HistoryResp, error) {
 	return c.historyAPI.Do(ctx, agentId)
 }
+
+// Speak
+//
+// @brief Speaks a custom message for the specified agent instance
+//
+// @since v0.9.0
+//
+// @param ctx Context to control the request lifecycle.
+//
+// @param agentId Agent ID.
+//
+// @param payload Request body for the specified agent to speak a custom message. See api.SpeakBody for details.
+//
+// @return Returns the response *SpeakResp. See api.SpeakResp for details.
+//
+// @return Returns an error object. If the request fails, the error object is not nil and contains error information.
+func (c *Client) Speak(ctx context.Context, agentId string, payload *req.SpeakBody) (*resp.SpeakResp, error) {
+	return c.speakAPI.Do(ctx, agentId, payload)
+}

services/convoai/client.go

@@ -0,0 +1,20 @@
+package req
+
+// @brief Defines the request body for the Speak API
+//
+// @since v0.9.0
+type SpeakBody struct {
+	// The text content to be spoken, with a maximum length of 512 bytes.(Required)
+	Text *string `json:"text"`
+	// The priority of the speech behavior, which supports the following values(Optional):
+	//
+	//  - "INTERRUPT" (default): High priority, interrupt and speak. The agent will terminate the current interaction and speak the message directly.
+	//  - "APPEND": Middle priority, append and speak. The agent will speak the message after the current interaction.
+	//  - "IGNORE": Low priority, speak when idle. If the agent is currently interacting, it will directly ignore and discard the message to be spoken; only when the agent is not interacting will it speak the message.
+	Priority *string `json:"priority"`
+	// Whether to allow the user to speak to interrupt the agent's speech(Optional):
+	//
+	//  - true (default): Allow.
+	//  - false: Disallow.
+	Interruptable *bool `json:"interrupt"`
+}

services/convoai/req/speak.go

@@ -0,0 +1,23 @@
+package resp
+
+// @brief SpeakResp returned by the Conversational AI engine Speak API
+//
+// @since v0.9.0
+type SpeakResp struct {
+	// Response returned by the Conversational AI engine API, see Response for details
+	Response
+	// Successful response, see SpeakSuccessResp for details
+	SuccessRes SpeakSuccessResp
+}
+
+// @brief Successful response returned by the Conversational AI engine Speak API
+//
+// @since v0.9.0
+type SpeakSuccessResp struct {
+	// The channel name of the agent
+	Channel string `json:"channel"`
+	// Unique identifier of the agent
+	AgentId string `json:"agent_id"`
+	// The start timestamp of the agent
+	StartTs int64 `json:"start_ts"`
+}