API 参考

数据流

下图展示完整的请求过程，IMLib 层收到 IMKit 的请求后，会将最大上下文消息条数返回给用户。用户获取不多于该数量的历史消息，并将其转换成上下文消息，返回给 IMLib，交由 IMLib 继续请求服务。

底层 API 介绍

Android
iOS

requestRecommendationWithParams 方法

AI聊天助手底层依赖于融云SDK提供的 RongCoreClient#requestRecommendationWithParams 方法，开发者可直接使用此方法实现自定义AI聊天助手。

API 定义

Java
public abstract void requestRecommendationWithParams(
    RequestRecommendationParams params,
    IRongCoreCallback.RecommendationRequestCallback callback);

参数说明

RequestRecommendationParams

用于配置智能推荐的请求参数，包含以下主要字段：

参数名	类型	必填	说明
identifier	ConversationIdentifier	是	会话标识符，包含会话类型(仅支持私聊)、会话 ID 和频道 ID
agentId	String	是	智能体 ID，用于指定使用哪种 AI 模型生成推荐
customInfo	`Map<String, Object>`	否	自定义信息，可传入额外参数辅助 AI 生成更准确的推荐

示例：

Java
ConversationIdentifier identifier = new ConversationIdentifier(
    Conversation.ConversationType.PRIVATE,
    targetId,
    channelId);
    
Map<String, Object> customInfo = new HashMap<>();
customInfo.put("user_name", "张三");
customInfo.put("target_name", "李四");

RequestRecommendationParams params = new RequestRecommendationParams(
    identifier,
    "deepseek",  // 智能体 ID
    customInfo
);

RecommendationRequestCallback

用于处理推荐请求的回调接口，包含以下主要方法：

方法	说明
onReady	在执行请求前准备阶段调用，用于获取历史消息上下文
onSuccess	推荐请求成功时调用，返回推荐结果列表
onError	推荐请求失败时调用，返回错误码
onFinish	请求结束后调用(无论成功或失败)

回调接口详细说明

Java
abstract class RecommendationRequestCallback {
    /**
     * 请求服务前准备，用于提供历史消息上下文
     *
     * @param count 请求的消息数量
     * @param callback 消息上下文回调
     */
    public abstract void onReady(int count, RecommendationRequestProgressCallback callback);

    /**
     * 请求结束，成功或失败回调之后会立刻执行该方法
     *
     * @param requestId 请求 ID
     */
    public abstract void onFinish(String requestId);

    /**
     * 成功回调
     *
     * @param recommendations 推荐列表
     */
    public abstract void onSuccess(List<SuperAgentRecommendation> recommendations);

    /**
     * 失败回调
     *
     * @param errorCode 错误码
     */
    public abstract void onError(IRongCoreEnum.CoreErrorCode errorCode);
}

使用示例

Java
public void requestRecommendations() {
    // 1. 创建会话标识
    ConversationIdentifier identifier = new ConversationIdentifier(
        Conversation.ConversationType.PRIVATE,
        targetId,
        null);
    
    // 2. 准备自定义信息
    Map<String, Object> customInfo = new HashMap<>();
    customInfo.put("user_name", RongUserInfoManager.getInstance().getCurrentUserInfo().getName());
    customInfo.put("target_name", RongUserInfoManager.getInstance().getUserInfo(targetId).getName());
    
    // 3. 创建请求参数
    RequestRecommendationParams params = new RequestRecommendationParams(
        identifier,
        "deepseek_id",  // 使用的智能体 ID
        customInfo
    );
    
    // 4. 发起请求
    RongCoreClient.getInstance().requestRecommendationWithParams(
        params,
        new IRongCoreCallback.RecommendationRequestCallback() {
            @Override
            public void onReady(int count, RecommendationRequestProgressCallback callback) {
                // 准备历史消息上下文
                List<AgentContextMessage> contextMessages = new ArrayList<>();
                
                // 获取历史消息
                RongCoreClient.getInstance().getHistoryMessages(
                    identifier.getType(),
                    identifier.getTargetId(),
                    null, // 消息类型列表，null 表示获取所有类型
                    0,    // 开始时间戳
                    20,   // 获取数量
                    RongCommonDefine.GetMessageDirection.FRONT,
                    new IRongCoreCallback.ResultCallback<List<Message>>() {
                        @Override
                        public void onSuccess(List<Message> messages) {
                            // 转换为 AgentContextMessage 格式
                            for (Message message : messages) {
                                if (message.getContent() instanceof TextMessage) {
                                    TextMessage content = (TextMessage) message.getContent();
                                    AgentContextMessage msg = new AgentContextMessage();
                                    msg.setContent(content.getContent());
                                    msg.setTimestamp(message.getSentTime());
                                    msg.setType(AgentContextMessageType.TEXT);
                                    msg.setMessageId(message.getUId());
                                    UserInfo userInfo = RongUserInfoManager.getInstance()
                                            .getUserInfo(message.getSenderUserId());
                                    msg.setUserName(userInfo.getName());
                                    msg.setUserId(message.getSenderUserId());
                                    contextMessages.add(msg);
                                }
                            }
                            
                            // 提供消息上下文
                            callback.onReady(contextMessages);
                        }
                        
                        @Override
                        public void onError(IRongCoreEnum.CoreErrorCode e) {
                            // 获取历史消息失败，提供空列表
                            callback.onReady(new ArrayList<>());
                        }
                    });
            }
            
            @Override
            public void onFinish(String requestId) {
                // 请求完成的处理
                Log.d("RecommendationRequest", "Request finished: " + requestId);
            }
            
            @Override
            public void onSuccess(List<SuperAgentRecommendation> recommendations) {
                // 处理推荐结果
                if (recommendations != null && !recommendations.isEmpty()) {
                    for (SuperAgentRecommendation recommendation : recommendations) {
                        Log.d("RecommendationRequest", "Got recommendation: " + recommendation.getContent());
                    }
                    
                    // 更新 UI 显示推荐结果
                    updateRecommendationsUI(recommendations);
                }
            }
            
            @Override
            public void onError(IRongCoreEnum.CoreErrorCode errorCode) {
                // 处理错误
                Log.e("RecommendationRequest", "Error: " + errorCode.getValue());
                
                // 更新 UI 显示错误状态
                showErrorState(errorCode);
            }
        });
}

requestRecommendationWithParams 方法

AI聊天助手底层依赖于融云SDK提供的 RongCoreClient.requestRecommendationWithParams 方法，开发者可直接使用此方法实现自定义AI聊天助手。

请求推荐内容

objc
+ (void)requestRecommendationWithParams:(RCRequestRecommendationParams *)recommendationParams
                           processBlock:(RCAgentContextMessagesProcessBlock)processBlock
                             completion:(RCAgentRecommendationListCompletion)completion;

参数说明

用于配置智能推荐的请求参数，包含以下主要字段：

参数名	类型	必填	说明
recommendationParams	RCRequestRecommendationParams	是	请求参数对象，包含会话标识(仅支持私聊)、智能体 ID 和自定义信息
processBlock	block	否	上下文消息处理回调，用于获取一定数量的消息上下文, 包含最大消息数量和消息获取完成回调
completion	block	否	请求结果回调,包含推荐内容列表, 请求ID, 错误码

使用示例

创建请求参数

objc
// 创建会话标识
RCConversationIdentifier *identifier = [[RCConversationIdentifier alloc] initWithType:ConversationType_PRIVATE 
                                                                           targetId:@"targetId" 
                                                                          channelId:nil];

// 创建请求参数
RCRequestRecommendationParams *params = [[RCRequestRecommendationParams alloc] initWithIdentifier:identifier
                                                                                         agentId:@"agentId"
                                                                                      customInfo:@{@"key": @"value"}];

发起请求

objc
[RCAgentService requestRecommendationWithParams:params
                                   processBlock:^(NSInteger maxCount, RCAgentContextMessagesCompletionBlock completionBlock) {
    // 获取上下文消息
    NSArray<RCAgentContextMessage *> *messages = [self getContextMessages:maxCount];
    completionBlock(messages);
} completion:^(NSArray<NSArray<RCAgentRecommendation *> *> *recommendations, NSString *requestId, RCErrorCode code) {
    if (code == RC_SUCCESS) {
        // 处理推荐内容
        [self handleRecommendations:recommendations];
    } else {
        // 处理错误
        [self handleError:code];
    }
}];

处理推荐内容

objc
- (void)handleRecommendations:(NSArray<NSArray<RCAgentRecommendation *> *> *)recommendations {
    for (NSArray<RCAgentRecommendation *> *group in recommendations) {
        for (RCAgentRecommendation *recommendation in group) {
            // 根据类型处理不同的推荐内容
            if ([recommendation.type isEqualToString:@"text/plain"]) {
                // 处理文本内容
                NSString *content = recommendation.content;
                // 进行业务处理...
            }
        }
    }
}

自定义页面集成

Android
iOS

AgentFacadePage API 参考

方法	描述
`onCreateView()`	创建并返回AI助手页面视图
`onResume()`	页面恢复时调用，刷新推荐内容
`onViewReady()`	视图准备完成时调用，设置数据观察者
`setAgentRecommendationListener()`	设置推荐内容交互监听器
`showLoadingView()`	显示加载中状态
`showRecommendations()`	显示推荐内容列表
`showEmptyView()`	显示空状态
`showErrorView()`	显示错误状态
`showDisabledView()`	显示功能禁用状态

AgentFacadeViewModel API 参考

方法	描述
`isFeatureEnabled()`	判断功能是否启用
`getAgentId()`	获取当前使用的AI模型ID
`requestRecommendations()`	请求推荐内容
`onAgentReady()`	准备AI上下文数据
`getRecommendationsLiveData()`	获取推荐内容LiveData
`getErrorEventLiveData()`	获取错误事件LiveData

自定义 AgentFacadePage 示例

通过继承AgentFacadePage类创建自定义的AI助手页面：

Java
public class CustomAgentFacadePage extends AgentFacadePage {

    public CustomAgentFacadePage(@NonNull Fragment fragment, ConversationIdentifier identifier) {
        super(fragment, identifier);
    }

    @NonNull
    @Override
    public View onCreateView(@NonNull Context context, @NonNull LayoutInflater inflater,
                            @NonNull ViewGroup container, @NonNull Bundle args) {
        // 调用父类方法获取基础视图
        View view = super.onCreateView(context, inflater, container, args);
        
        // 添加自定义视图或修改现有视图
        
        return view;
    }
    
    @Override
    protected AgentFacadeViewModel onCreateViewModel(@NonNull Bundle bundle) {
        // 使用自定义的ViewModel
        return new ViewModelProvider(this.fragment, new ViewModelFactory(bundle))
                .get(CustomAgentFacadeViewModel.class);
    }
    
    @Override
    protected void onViewReady(@NonNull AgentFacadeViewModel viewModel) {
        super.onViewReady(viewModel);
        
        // 添加自定义的数据观察和事件处理
        viewModel.getRecommendationsLiveData().observe(fragment, recommendations -> {
            // 处理推荐内容变化
        });
        
        // 自定义推荐项点击行为
        setAgentRecommendationListener(new AgentRecommendationListener() {
            @Override
            public void onItemEdit(List<AgentRecommendation> recommendations) {
                // 处理编辑推荐内容
                if (recommendations != null && recommendations.size() == 1) {
                    String content = recommendations.get(0).getContent();
                    // 将内容填充到输入框
                    if (fragment instanceof ConversationFragment) {
                        EditText inputEditText = ((ConversationFragment) fragment)
                                .getRongExtension().getInputEditText();
                        inputEditText.setText(content);
                        inputEditText.setSelection(content.length());
                    }
                }
            }
            
            @Override
            public void onItemClick(List<AgentRecommendation> recommendations) {
                // 处理点击推荐内容
                if (recommendations != null && !recommendations.isEmpty()) {
                    // 实现发送消息逻辑
                }
            }
        });
    }
}

自定义 ViewModel 示例

通过继承AgentFacadeViewModel类创建自定义的ViewModel：

Java
public class CustomAgentFacadeViewModel extends AgentFacadeViewModel {

    public CustomAgentFacadeViewModel(Bundle bundle) {
        super(bundle);
    }
    
    @Override
    public boolean isFeatureEnabled() {
        // 自定义功能开关逻辑
        Context context = IMCenter.getInstance().getContext();
        if (context != null) {
            SharedPreferences sp = context.getSharedPreferences("ai_settings", Context.MODE_PRIVATE);
            return sp.getBoolean("feature_enabled", false);
        }
        return super.isFeatureEnabled();
    }
    
    @Override
    public String getAgentId() {
        // 自定义AI模型选择逻辑
        Context context = IMCenter.getInstance().getContext();
        if (context != null) {
            SharedPreferences sp = context.getSharedPreferences("ai_settings", Context.MODE_PRIVATE);
            String style = sp.getString("chat_style", "default");
            
            // 根据选择的风格返回对应的AgentId
            switch (style) {
                case "style1":
                    return "agent_id_1";
                case "style2":
                    return "agent_id_2";
                default:
                    return "default_agent_id";
            }
        }
        return super.getAgentId();
    }
    
    @Override
    public boolean onAgentReady(RequestRecommendationParams params, int count,
                              IRongCoreCallback.RecommendationRequestProgressCallback callback) {
        // 自定义消息历史获取逻辑
        String targetId = params.getIdentifier().getTargetId();
        Conversation.ConversationType type = params.getIdentifier().getType();
        
        // 获取最近的消息作为上下文
        RongCoreClient.getInstance().getHistoryMessages(
                type, targetId, null, 0, count, 
                RongCommonDefine.GetMessageDirection.FRONT,
                new IRongCoreCallback.ResultCallback<List<Message>>() {
                    @Override
                    public void onSuccess(List<Message> messages) {
                        // 将消息转换为AI上下文
                        List<AgentContextMessage> contextMessages = convertMessagesToContext(messages);
                        
                        // 回调结果
                        if (callback != null) {
                            callback.onReady(contextMessages);
                        }
                    }
                    
                    @Override
                    public void onError(IRongCoreEnum.CoreErrorCode e) {
                        if (callback != null) {
                            callback.onReady(new ArrayList<>());
                        }
                    }
                });
                
        return true; // 返回true表示已处理
    }
    
    // 辅助方法：将消息转换为AI上下文
    private List<AgentContextMessage> convertMessagesToContext(List<Message> messages) {
        List<AgentContextMessage> contextMessages = new ArrayList<>();
        for (Message message : messages) {
            if (message.getContent() instanceof TextMessage) {
                TextMessage textMessage = (TextMessage) message.getContent();
                
                AgentContextMessage contextMessage = new AgentContextMessage();
                contextMessage.setContent(textMessage.getContent());
                contextMessage.setTimestamp(message.getSentTime());
                contextMessage.setType(AgentContextMessageType.TEXT);
                contextMessage.setMessageId(message.getUId());
                
                // 设置用户信息
                UserInfo userInfo = RongUserInfoManager.getInstance()
                        .getUserInfo(message.getSenderUserId());
                if (userInfo != null) {
                    contextMessage.setUserName(userInfo.getName());
                }
                contextMessage.setUserId(message.getSenderUserId());
                
                contextMessages.add(contextMessage);
            }
        }
        return contextMessages;
    }
}

RCAgentFacadeModel 相关接口

初始化方法

objc
- (instancetype)initWithIdentifier:(RCConversationIdentifier*)identifier
                          delegate:(id<RCAgentFacadeDelegate>)delegate;

主要属性

objc
/// 列表页
@property (nonatomic, strong) RCAgentView *agentView;

/// 上下文消息数据源
@property (nonatomic, weak) id<RCAgentMessageDataSource> dataSource;

/// UI 功能代理[设置, 刷新]
@property (nonatomic, weak) id<RCAgentFacadeUIDelegate> uiDelegate;

主要方法

objc
/// 向智能体发起请求
- (void)requestRecommendationWith:(NSString *)agentId
                       customInfo:(NSDictionary *)customInfo;

/// 更改智能体ID
- (void)changeAgentIDIfNeed:(NSString *)agentId;

/// 移除 AI 视图并清空数据
- (void)removeAndCleanAgentView;

代理方法实现示例

objc
// 实现推荐内容选择代理方法
- (void)agent:(RCAgentFacadeModel *)agent 
didSelectedRecommendations:(NSArray<RCAgentRecommendation *>*)recommendations {
    for (RCAgentRecommendation *recommendation in recommendations) {
        if ([recommendation imkit_category] == RCAgentRecommendationCategoryText) {
            // 发送文本消息
            RCTextMessage *textMessage = [RCTextMessage messageWithContent:recommendation.content];
            [self sendMessage:textMessage];
        }
    }
    // 清理智能体视图
    [agent removeAndCleanAgentView];
}

// 实现推荐内容编辑代理方法
- (void)agent:(RCAgentFacadeModel *)agent
editRecommendation:(NSArray <RCAgentRecommendation *> *)recommendations {
    if (recommendations.count > 0) {
        RCAgentRecommendation *recommendation = recommendations[0];
        // 设置输入框内容
        self.inputTextView.text = recommendation.content;
    }
    [agent removeAndCleanAgentView];
}

// 实现数据源方法
- (void)agent:(RCAgentFacadeModel *)agent
fetchMessageWithIdentifier:(RCConversationIdentifier *)identifier
     maxCount:(NSInteger)maxCount
   completion:(void(^)(NSArray <RCAgentContextMessage *>* messages))completion {
    // 获取历史消息
    [[RCCoreClient sharedCoreClient] getHistoryMessages:identifier.type
                                              targetId:identifier.targetId
                                           objectNames:@[@"RC:TxtMsg"]
                                              sentTime:0
                                             isForward:YES
                                                 count:(int)maxCount
                                            completion:^(NSArray<RCMessage *> * _Nullable messages) {
        // 转换为上下文消息
        NSMutableArray *contextMessages = [NSMutableArray array];
        for (RCMessage *msg in messages) {
            RCAgentContextMessage *contextMsg = [self convertToContextMessage:msg];
            [contextMessages addObject:contextMsg];
        }
        completion(contextMessages);
    }];
}

IMLib

IMKit

Global IM UIKit

推送服务

IMLib

IMKit

CallLib

CallKit

CallPlus

RTCLib

CallLib

CallPlus

RTCLib

IM 服务端

IM Server SDK

RTC 服务端

北极星数据查询

数据流​

底层 API 介绍​

requestRecommendationWithParams 方法​

API 定义​

参数说明​

RequestRecommendationParams​

RecommendationRequestCallback​

回调接口详细说明​

使用示例​

requestRecommendationWithParams 方法​

请求推荐内容​

参数说明​

使用示例​

自定义页面集成​

AgentFacadePage API 参考​

AgentFacadeViewModel API 参考​

自定义 AgentFacadePage 示例​

自定义 ViewModel 示例​

RCAgentFacadeModel 相关接口​

初始化方法​

主要属性​

主要方法​

相关代理接口​

RCAgentFacadeDelegate​

RCAgentFacadeUIDelegate​

RCAgentMessageDataSource​

代理方法实现示例​

数据流

底层 API 介绍

requestRecommendationWithParams 方法

API 定义

参数说明

RequestRecommendationParams

RecommendationRequestCallback

回调接口详细说明

使用示例

requestRecommendationWithParams 方法

请求推荐内容

参数说明

使用示例

自定义页面集成

AgentFacadePage API 参考

AgentFacadeViewModel API 参考

自定义 AgentFacadePage 示例

自定义 ViewModel 示例

RCAgentFacadeModel 相关接口

初始化方法

主要属性

主要方法

相关代理接口

RCAgentFacadeDelegate

RCAgentFacadeUIDelegate

RCAgentMessageDataSource

代理方法实现示例