回复渠道 - 高级特性
1. 多渠道配置
配置多个回复工具，支持不同场景：
spring:
ai:
alibaba:
codeact:
extension:
reply:
enabled: true
tools:
# 普通文本消息
- toolName: send_message
channelCode: IDE_TEXT
description: 发送文本消息
parameters:
- name: text
type: STRING
required: true
# 卡片消息
- toolName: send_card
channelCode: IDE_CARD
description: 发送富文本卡片
parameters:
- name: title
type: STRING
required: true
- name: content
type: STRING
required: true
- name: buttons
type: ARRAY
required: false
# IM 通知
- toolName: send_notification
channelCode: IM_NOTIFICATION
description: 发送即时通讯通知
parameters:
- name: message
type: STRING
required: true
- name: mentions
type: ARRAY
required: false
Agent 调用：
# 文本消息
reply.send_message(text="任务完成")
# 卡片消息
reply.send_card(
title="查询结果",
content="共找到 10 条记录",
buttons=[{"text": "查看详情", "action": "view"}]
)
# IM 通知
reply.send_notification(
message="紧急：服务器异常",
mentions=["user1", "user2"]
)
2. 自定义渠道实现
Webhook 渠道
@Component
public class WebhookChannelDefinition implements ReplyChannelDefinition {
private final RestTemplate restTemplate;
@Override
public String getChannelCode() {
return "WEBHOOK";
}
@Override
public String getDescription() {
return "通过 Webhook 推送消息到外部系统";
}
@Override
public ParameterSchema getSupportedParameters() {
return ParameterSchema.builder()
.parameter("url", ParameterSchema.ParameterType.STRING, true, "Webhook URL")
.parameter("payload", ParameterSchema.ParameterType.OBJECT, true, "推送数据")
.build();
}
@Override
public ReplyResult execute(ChannelExecutionContext context, Map<String, Object> params) {
String url = (String) params.get("url");
Object payload = params.get("payload");
try {
restTemplate.postForEntity(url, payload, String.class);
return ReplyResult.success("Webhook 推送成功");
} catch (Exception e) {
return ReplyResult.failure("Webhook 推送失败: " + e.getMessage());
}
}
@Override
public boolean supportsAsync() {
return true; // 支持异步执行
}
}
钉钉渠道
@Component
public class DingTalkChannelDefinition implements ReplyChannelDefinition {
private final DingTalkClient dingTalkClient;
@Override
public String getChannelCode() {
return "DINGTALK";
}
@Override
public ReplyResult execute(ChannelExecutionContext context, Map<String, Object> params) {
String message = (String) params.get("message");
List<String> atUsers = (List<String>) params.get("at_users");
DingTalkMessage msg = DingTalkMessage.builder()
.msgtype("text")
.text(new TextContent(message))
.at(new AtConfig(atUsers))
.build();
dingTalkClient.send(msg);
return ReplyResult.success("钉钉消息发送成功");
}
}
3. 渠道执行上下文
ChannelExecutionContext 提供丰富的上下文信息：
@Override
public ReplyResult execute(ChannelExecutionContext context, Map<String, Object> params) {
// 获取会话信息
String sessionId = context.getSessionId();
String userId = context.getUserId();
String projectId = context.getProjectId();
// 获取工具名称和来源
String toolName = context.getToolName();
ChannelExecutionContext.ExecutionSource source = context.getSource();
// 获取扩展信息
Map<String, Object> extensions = context.getExtensions();
// 实现发送逻辑...
}
4. 异步渠道
对于耗时的发送操作，支持异步执行：
@Component
public class EmailChannelDefinition implements ReplyChannelDefinition {
@Override
public String getChannelCode() {
return "EMAIL";
}
@Override
public boolean supportsAsync() {
return true; // 启用异步
}
@Override
public ReplyResult execute(ChannelExecutionContext context, Map<String, Object> params) {
String to = (String) params.get("to");
String subject = (String) params.get("subject");
String body = (String) params.get("body");
// 异步发送邮件
emailService.sendAsync(to, subject, body);
return ReplyResult.success("邮件已提交发送");
}
}
5. 参数映射
将工具参数映射到渠道参数：
spring:
ai:
alibaba:
codeact:
extension:
reply:
tools:
- toolName: notify_user
channelCode: IM_NOTIFICATION
description: 通知用户
parameters:
- name: message
type: STRING
required: true
mappedTo: content # 映射到渠道的 content 参数
- name: priority
type: STRING
required: false
defaultValue: normal # 默认值
6. 编程方式配置
通过 Bean 配置覆盖 YAML：
import com.alibaba.assistant.agent.extension.reply.spi.ReplyToolConfigProvider;
import com.alibaba.assistant.agent.extension.reply.config.ReplyToolConfig;
@Component
public class CustomReplyToolProvider implements ReplyToolConfigProvider {
@Override
public List<ReplyToolConfig> getToolConfigs() {
List<ReplyToolConfig> configs = new ArrayList<>();
ReplyToolConfig alertTool = new ReplyToolConfig();
alertTool.setToolName("send_alert");
alertTool.setChannelCode("ALERT");
alertTool.setDescription("发送告警消息");
alertTool.setParameters(List.of(
createParam("level", "STRING", true, "告警级别"),
createParam("message", "STRING", true, "告警内容")
));
configs.add(alertTool);
return configs;
}
}
7. 渠道选择逻辑
根据条件动态选择渠道：
@Component
public class SmartChannelRouter {
private final Map<String, ReplyChannelDefinition> channels;
public ReplyResult route(String message, ChannelExecutionContext context) {
// 根据消息长度选择渠道
if (message.length() > 500) {
return channels.get("IDE_CARD").execute(context,
Map.of("content", message));
}
// 根据用户偏好选择渠道
String preferred = getUserPreferredChannel(context.getUserId());
if (preferred != null && channels.containsKey(preferred)) {
return channels.get(preferred).execute(context,
Map.of("text", message));
}
// 默认渠道
return channels.get("IDE_TEXT").execute(context,
Map.of("text", message));
}
}
8. 消息模板
支持预定义消息模板：
@Component
public class TemplateChannelDefinition implements ReplyChannelDefinition {
private final TemplateEngine templateEngine;
@Override
public String getChannelCode() {
return "TEMPLATE_MESSAGE";
}
@Override
public ReplyResult execute(ChannelExecutionContext context, Map<String, Object> params) {
String templateName = (String) params.get("template");
Map<String, Object> variables = (Map<String, Object>) params.get("variables");
// 渲染模板
String rendered = templateEngine.render(templateName, variables);
// 发送渲染后的消息
messageSender.send(context.getSessionId(), rendered);
return ReplyResult.success("模板消息发送成功");
}
}
Agent 调用：
reply.template_message(
template="order_status",
variables={
"order_id": "ORD-001",
"status": "已发货",
"tracking_number": "SF123456"
}
)
9. 发送结果处理
处理发送结果：
@Override
public ReplyResult execute(ChannelExecutionContext context, Map<String, Object> params) {
try {
// 发送逻辑
SendResult result = doSend(params);
if (result.isSuccess()) {
return ReplyResult.success(result.getMessageId());
} else {
return ReplyResult.failure(result.getErrorMessage());
}
} catch (Exception e) {
log.error("ChannelDefinition#execute - reason=发送失败", e);
return ReplyResult.failure("发送失败: " + e.getMessage());
}
}
10. 日志与监控
logging:
level:
com.alibaba.assistant.agent.extension.reply: DEBUG
@Component
public class ReplyMetrics {
private final MeterRegistry meterRegistry;
public void recordSend(String channelCode, boolean success) {
meterRegistry.counter("reply.send.count",
"channel", channelCode,
"result", success ? "success" : "failure"
).increment();
}
}