Skip to content

Commit 998a3a0

Browse files
seymourtangseymourtang
committed
feat: Implement Conversational AI service APIs for joining, leaving, listing, querying, and updating agents
1 parent e62dca6 commit 998a3a0

26 files changed

+4158
-5
lines changed

‎agora-rest-client-core/pom.xml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
<groupId>io.agora</groupId>
77

88
<artifactId>agora-rest-client-core</artifactId>
9-
<version>0.2.0</version>
9+
<version>0.3.0</version>
1010
<description>Agora REST Client for Java</description>
1111
<name>Agora REST Client</name>
1212
<url>https://github.com/AgoraIO-Community/agora-rest-client-java</url>
@@ -48,8 +48,8 @@
4848
<jackson.version>2.18.1</jackson.version>
4949
<junit.version>5.11.3</junit.version>
5050
<logback.version>1.3.14</logback.version>
51-
<reactor-core.version>3.6.2</reactor-core.version>
52-
<reactor-netty-core.version>1.1.24</reactor-netty-core.version>
51+
<reactor-core.version>3.7.4</reactor-core.version>
52+
<reactor-netty-core.version>1.2.4</reactor-netty-core.version>
5353

5454
</properties>
5555

@@ -89,14 +89,14 @@
8989
<dependency>
9090
<groupId>io.netty</groupId>
9191
<artifactId>netty-resolver-dns-native-macos</artifactId>
92-
<version>4.1.114.Final</version>
92+
<version>4.1.119.Final</version>
9393
<scope>runtime</scope>
9494
<classifier>osx-aarch_64</classifier>
9595
</dependency>
9696
<dependency>
9797
<groupId>io.netty</groupId>
9898
<artifactId>netty-resolver-dns</artifactId>
99-
<version>4.1.114.Final</version>
99+
<version>4.1.119.Final</version>
100100
</dependency>
101101

102102
<dependency>

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

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
package io.agora.rest.services.convoai;
2+
3+
import io.agora.rest.core.AgoraConfig;
4+
import io.agora.rest.core.DefaultContext;
5+
import io.agora.rest.services.convoai.req.JoinConvoAIReq;
6+
import io.agora.rest.services.convoai.req.ListConvoAIReq;
7+
import io.agora.rest.services.convoai.req.UpdateConvoAIReq;
8+
import io.agora.rest.services.convoai.res.JoinConvoAIRes;
9+
import io.agora.rest.services.convoai.res.ListConvoAIRes;
10+
import io.agora.rest.services.convoai.res.QueryConvoAIRes;
11+
import io.agora.rest.services.convoai.res.UpdateConvoAIRes;
12+
import reactor.core.publisher.Mono;
13+
14+
public abstract class ConvoAIClient {
15+
16+
private static ConvoAIClient mInstance;
17+
18+
/**
19+
* @param convoAIConfig Instance of {@link ConvoAIConfig}.
20+
* @return Returns the Conversational AI engine client instance.
21+
* @brief Creates a Conversational AI engine client with the specified configuration.
22+
* @since v0.3.0
23+
*/
24+
public static synchronized ConvoAIClient create(ConvoAIConfig convoAIConfig) {
25+
if (mInstance == null) {
26+
AgoraConfig agoraConfig = AgoraConfig.builder()
27+
.appId(convoAIConfig.getAppId())
28+
.credential(convoAIConfig.getCredential())
29+
.domainArea(convoAIConfig.getDomainArea())
30+
.httpProperty(convoAIConfig.getHttpProperty())
31+
.build();
32+
mInstance = new ConvoAIClientImpl(new DefaultContext(agoraConfig), convoAIConfig.getServiceRegion());
33+
}
34+
35+
return mInstance;
36+
}
37+
38+
/**
39+
* @param request Parameters for the join request to the conversational AI engine, see {@link JoinConvoAIReq}.
40+
* @return Returns the join response result, see {@link JoinConvoAIRes}.
41+
* @brief Creates an agent instance and joins the specified RTC channel.
42+
* @example Use this to create an agent instance in an RTC channel.
43+
* @post After successful execution, the agent will join the specified channel. You can perform subsequent operations using the returned agent ID.
44+
* @since v0.3.0
45+
*/
46+
public abstract Mono<JoinConvoAIRes> join(JoinConvoAIReq request);
47+
48+
/**
49+
* @param agentId Agent ID
50+
* @brief Stops the specified agent instance and leaves the RTC channel.
51+
* @example Use this to stop an agent instance.
52+
* @post After successful execution, the agent will be stopped and leave the RTC channel.
53+
* @note Ensure the agent ID has been obtained by calling the join API before using this method.
54+
* @since v0.3.0
55+
*/
56+
public abstract Mono<Void> leave(String agentId);
57+
58+
/**
59+
* @param request Parameters for listing conversational agents, see {@link ListConvoAIReq}.
60+
* @return Returns the list response result, see {@link ListConvoAIRes} for details.
61+
* @brief Retrieves a list of agents that meet the specified criteria.
62+
* @example Use this to get a list of agents that meet the specified criteria.
63+
* @post After successful execution, a list of agents that meet the specified criteria will be retrieved.
64+
* @since v0.3.0
65+
*/
66+
public abstract Mono<ListConvoAIRes> list(ListConvoAIReq request);
67+
68+
/**
69+
* @param agentId Agent ID
70+
* @return Returns the query response result, see {@link QueryConvoAIRes}
71+
* @brief Query the current status of the specified agent instance.
72+
* @example Use this to get the current status of the specified agent instance.
73+
* @post After successful execution, the current running status information of the specified agent instance will be retrieved.
74+
* @note Ensure the agent ID has been obtained by calling the join API before using this method.
75+
* @since v0.3.0
76+
*/
77+
public abstract Mono<QueryConvoAIRes> query(String agentId);
78+
79+
/**
80+
* @param agentId Agent ID
81+
* @param request Parameters for updating the conversational agent, see {@link UpdateConvoAIReq} for details.
82+
* @return Returns the update response result, see {@link UpdateConvoAIRes}.
83+
* @brief Adjusts the agent's parameters at runtime.
84+
* @example Use this to adjust the agent's parameters at runtime.
85+
* @post After successful execution, the agent's parameters will be adjusted.
86+
* @note Ensure the agent ID has been obtained by calling the join API before using this method.
87+
* @since v0.3.0
88+
*/
89+
public abstract Mono<UpdateConvoAIRes> update(String agentId, UpdateConvoAIReq request);
90+
91+
}

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

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
package io.agora.rest.services.convoai;
2+
3+
import io.agora.rest.core.Context;
4+
import io.agora.rest.exception.AgoraInvalidArgumentException;
5+
import io.agora.rest.services.convoai.api.*;
6+
import io.agora.rest.services.convoai.req.JoinConvoAIReq;
7+
import io.agora.rest.services.convoai.req.ListConvoAIReq;
8+
import io.agora.rest.services.convoai.req.UpdateConvoAIReq;
9+
import io.agora.rest.services.convoai.res.JoinConvoAIRes;
10+
import io.agora.rest.services.convoai.res.ListConvoAIRes;
11+
import io.agora.rest.services.convoai.res.QueryConvoAIRes;
12+
import io.agora.rest.services.convoai.res.UpdateConvoAIRes;
13+
import reactor.core.publisher.Mono;
14+
15+
public class ConvoAIClientImpl extends ConvoAIClient {
16+
17+
private final JoinConvoAIAPI joinConvoAIAPI;
18+
19+
private final LeaveConvoAIAPI leaveConvoAIAPI;
20+
21+
private final ListConvoAIAPI listConvoAIAPI;
22+
23+
private final QueryConvoAIAPI queryConvoAIAPI;
24+
25+
private final UpdateConvoAIAPI updateConvoAIAPI;
26+
27+
private final static String chineseMainlandPrefixTpl = "/cn/api/conversational-ai-agent/v2/projects/%s";
28+
29+
private final static String globalPrefixTpl = "/api/conversational-ai-agent/v2/projects/%s";
30+
31+
protected ConvoAIClientImpl(Context context, ConvoAIServiceRegionEnum serviceRegionEnum) {
32+
String pathPrefix = getPathPrefix(context, serviceRegionEnum);
33+
joinConvoAIAPI = new JoinConvoAIAPI(context, pathPrefix);
34+
leaveConvoAIAPI = new LeaveConvoAIAPI(context, pathPrefix);
35+
listConvoAIAPI = new ListConvoAIAPI(context, pathPrefix);
36+
queryConvoAIAPI = new QueryConvoAIAPI(context, pathPrefix);
37+
updateConvoAIAPI = new UpdateConvoAIAPI(context, pathPrefix);
38+
}
39+
40+
private String getPathPrefix(Context context, ConvoAIServiceRegionEnum serviceRegionEnum) {
41+
if (serviceRegionEnum == null) {
42+
throw new AgoraInvalidArgumentException("service region is null");
43+
}
44+
45+
String pathPrefixTpl = null;
46+
47+
switch (serviceRegionEnum) {
48+
case CHINESE_MAINLAND:
49+
pathPrefixTpl = chineseMainlandPrefixTpl;
50+
break;
51+
case GLOBAL:
52+
pathPrefixTpl = globalPrefixTpl;
53+
break;
54+
}
55+
56+
return String.format(pathPrefixTpl, context.getAgoraConfig().getAppId());
57+
}
58+
59+
public Mono<JoinConvoAIRes> join(JoinConvoAIReq request) {
60+
return joinConvoAIAPI.handle(request);
61+
}
62+
63+
public Mono<Void> leave(String agentId) {
64+
return leaveConvoAIAPI.handle(agentId);
65+
}
66+
67+
public Mono<ListConvoAIRes> list(ListConvoAIReq request) {
68+
return listConvoAIAPI.handle(request);
69+
}
70+
71+
public Mono<QueryConvoAIRes> query(String agentId) {
72+
return queryConvoAIAPI.handle(agentId);
73+
}
74+
75+
public Mono<UpdateConvoAIRes> update(String agentId, UpdateConvoAIReq request) {
76+
return updateConvoAIAPI.handle(agentId, request);
77+
}
78+
}

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

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
package io.agora.rest.services.convoai;
2+
3+
import io.agora.rest.core.Credential;
4+
import io.agora.rest.core.DomainArea;
5+
import io.agora.rest.core.HttpProperty;
6+
7+
8+
/**
9+
* @brief Defines the configuration for the Conversational AI engine client
10+
* @since v0.3.0
11+
*/
12+
public class ConvoAIConfig {
13+
14+
/**
15+
* Agora AppID
16+
*/
17+
private final String appId;
18+
19+
/**
20+
* Credential for accessing the Agora service.
21+
* <p>
22+
* Available credential types:
23+
* <p>
24+
* - BasicAuthCredential: See {@link io.agora.rest.core.BasicAuthCredential}
25+
*/
26+
private final Credential credential;
27+
28+
/**
29+
* Domain area for the REST Client. See {@link DomainArea}
30+
*/
31+
private final DomainArea domainArea;
32+
33+
/**
34+
* HTTP properties for the REST Client. See {@link HttpProperty}
35+
*/
36+
private final HttpProperty httpProperty;
37+
38+
/**
39+
* Service region for the Conversational AI engine. See {@link ConvoAIServiceRegionEnum}
40+
*/
41+
private final ConvoAIServiceRegionEnum serviceRegion;
42+
43+
private ConvoAIConfig(Builder builder) {
44+
this.appId = builder.appId;
45+
this.credential = builder.credential;
46+
this.domainArea = builder.domainArea;
47+
this.httpProperty = builder.httpProperty;
48+
this.serviceRegion = builder.serviceRegion;
49+
}
50+
51+
public static Builder builder() {
52+
return new Builder();
53+
}
54+
55+
public String getAppId() {
56+
return appId;
57+
}
58+
59+
public Credential getCredential() {
60+
return credential;
61+
}
62+
63+
public DomainArea getDomainArea() {
64+
return domainArea;
65+
}
66+
67+
public HttpProperty getHttpProperty() {
68+
return httpProperty;
69+
}
70+
71+
public ConvoAIServiceRegionEnum getServiceRegion() {
72+
return serviceRegion;
73+
}
74+
75+
@Override
76+
public String toString() {
77+
return "ConvoAIConfig{" +
78+
"appId='" + appId + '\'' +
79+
", credential=" + credential +
80+
", domainArea=" + domainArea +
81+
", httpProperty=" + httpProperty +
82+
", serviceRegion=" + serviceRegion +
83+
'}';
84+
}
85+
86+
public static class Builder {
87+
88+
private String appId;
89+
90+
private Credential credential;
91+
92+
private DomainArea domainArea;
93+
94+
private HttpProperty httpProperty;
95+
96+
private ConvoAIServiceRegionEnum serviceRegion;
97+
98+
private Builder() {
99+
}
100+
101+
public Builder appId(String appId) {
102+
this.appId = appId;
103+
return this;
104+
}
105+
106+
public Builder credential(Credential credential) {
107+
this.credential = credential;
108+
return this;
109+
}
110+
111+
public Builder domainArea(DomainArea domainArea) {
112+
this.domainArea = domainArea;
113+
return this;
114+
}
115+
116+
private Builder httpProperty(HttpProperty httpProperty) {
117+
this.httpProperty = httpProperty;
118+
return this;
119+
}
120+
121+
public Builder serverRegion(ConvoAIServiceRegionEnum serverRegion) {
122+
this.serviceRegion = serverRegion;
123+
return this;
124+
}
125+
126+
public ConvoAIConfig build() {
127+
if (httpProperty == null) {
128+
this.httpProperty = HttpProperty.builder().build();
129+
}
130+
return new ConvoAIConfig(this);
131+
}
132+
}
133+
}

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
package io.agora.rest.services.convoai;
2+
3+
/**
4+
* @brief ServiceRegion represents the region of the Conversational AI engine service
5+
* @note The service in Chinese mainland and the global region are two different services
6+
* @since v0.3.0
7+
*/
8+
public enum ConvoAIServiceRegionEnum {
9+
/**
10+
* CHINESE_MAINLAND represents the Conversational AI engine service in Chinese mainland
11+
*/
12+
CHINESE_MAINLAND,
13+
14+
/**
15+
* GLOBAL represents the Conversational AI engine service in the global region, except Chinese mainland
16+
*/
17+
GLOBAL,
18+
}

0 commit comments

Comments
 (0)