Client API

Java SDK 的客户端 API 位于 com.iwhaleai.byai.framework.client 包下，提供了向 Agent 网关发送消息、取消任务以及拦截器机制的能力。

GatewayClient\<T>

GatewayClient 是泛型客户端基类，通过 Redis 与 Gateway 通信，支持消息发送、任务取消和拦截器链。

构造方法

/**
 * 构造一个 GatewayClient 实例。
 *
 * @param redisClient Redis 客户端实例
 */
public GatewayClient(RedisClient redisClient);

使用示例：

RedisClient redisClient = new RedisClient("localhost", 6379);
GatewayClient<Object> client = new GatewayClient<>(redisClient);

sendMessage (简易版)

/**
 * 简化版消息发送。
 *
 * @param targetAgentType 目标 Agent 类型
 * @param sessionId       会话 ID
 * @param content         消息内容
 * @return SendResponse 响应对象
 */
public SendResponse sendMessage(
    String targetAgentType,
    String sessionId,
    Object content
);

使用示例：

SendResponse response = client.sendMessage("my_agent", "session_001", "帮我分析数据");
if (response.isSuccess()) {
    System.out.println("消息已发送，messageId: " + response.getMessageId());
}

sendMessage (完整版)

GatewayClient 实际上有多个 sendMessage 重载（3 参 / 4 参 / 11 参 / 13 参 / 16 参），下面是参数最全的 16 参重载，其余重载都是在这个基础上给未传的参数填默认值：

/**
 * 完整版消息发送，支持路由策略与可用性控制的全部参数。
 *
 * @param targetAgentType       目标 Agent 类型
 * @param sessionId             会话 ID
 * @param content               消息内容
 * @param userCode              用户编码
 * @param userName              用户名称
 * @param actionType            动作类型（字符串，如 "ASK_AGENT"）
 * @param parentMessageId       父消息 ID，用于消息链路追踪
 * @param messageId             消息 ID（传 null 则自动生成）
 * @param traceId               追踪 ID（传 null 则自动生成）
 * @param payload               额外负载
 * @param metadata              元数据
 * @param targetWorkerId        直接指定目标 Worker（跳过 agent type 路由），可为 null
 * @param routePolicy           路由策略：FAIL_FAST / SEND_ANYWAY / WAKE_AND_WAIT / WAKE_AND_QUEUE / QUEUE_ONLY
 * @param availabilityTimeoutMs WAKE_AND_WAIT 策略下的超时时间（毫秒）
 * @param region                路由用的可选 region
 * @param priority              路由用的可选优先级
 * @return SendResponse 响应对象
 */
public SendResponse sendMessage(
    String targetAgentType,
    String sessionId,
    T content,
    String userCode,
    String userName,
    String actionType,
    String parentMessageId,
    String messageId,
    String traceId,
    Map<String, Object> payload,
    Map<String, Object> metadata,
    String targetWorkerId,
    String routePolicy,
    long availabilityTimeoutMs,
    String region,
    String priority
);

使用示例：

SendResponse response = client.sendMessage(
    "report_agent",
    "session_001",
    "生成月度销售报表",
    "user_123",
    "张三",
    ActionType.ASK_AGENT,
    "",                             // parentMessageId
    null,                           // messageId（自动生成）
    null,                           // traceId（自动生成）
    Map.of("format", "pdf", "language", "zh"),  // payload
    Map.of("priority", "high"),     // metadata
    null,                           // targetWorkerId
    RoutePolicy.FAIL_FAST,
    0L,                             // availabilityTimeoutMs
    null,                           // region
    null                            // priority
);

向后兼容的 requireOnlineWorker 重载

还有一个 13 参重载接收 boolean requireOnlineWorker 而不是 String routePolicy（内部会自动转换： true → FAIL_FAST，false → SEND_ANYWAY），供从旧版本升级的调用方使用，新代码建议直接用 routePolicy。

sendCommand

/**
 * 发送预构造的 GatewayCommand 对象。
 *
 * @param command 预构造的命令对象
 * @return SendResponse 响应对象
 */
public SendResponse sendCommand(GatewayCommand command);

使用示例：

MessageHeader header = MessageHeader.builder()
    .messageId("msg_001")
    .sessionId("session_001")
    .traceId("trace_001")
    .targetAgentType("my_agent")
    .build();

AskAgentCommand command = AskAgentCommand.builder()
    .header(header)
    .content("分析这组数据")
    .build();

SendResponse response = client.sendCommand(command);

cancelTask

/**
 * 取消指定的任务。
 *
 * @param messageId       目标消息 ID
 * @param sessionId       会话 ID
 * @param reason          取消原因
 * @param targetAgentType 目标 Agent 类型（可选，传空字符串即可）
 * @param requestedBy     取消发起方标识
 * @param cancelMode      取消模式（"graceful" 或 "force"）
 * @return CancelTaskResponse 响应对象
 */
public CancelTaskResponse cancelTask(
    String messageId,
    String sessionId,
    String reason,
    String targetAgentType,
    String requestedBy,
    String cancelMode
);

// 还有一个 2 参简化重载：cancelTask(messageId, sessionId)，
// 等价于 cancelTask(messageId, sessionId, "", "", "client", "graceful")

使用示例：

CancelTaskResponse cancelResp = client.cancelTask(
    "msg_001",
    "session_001",
    "用户手动取消",
    "",
    "client",
    "graceful"
);

if (cancelResp.isSuccess()) {
    System.out.println("任务已成功取消");
}

addInterceptor

/**
 * 添加网关拦截器。
 *
 * @param interceptor 拦截器实例
 */
public void addInterceptor(GatewayInterceptor interceptor);

使用示例：

client.addInterceptor(params -> {
    System.out.println("即将发送消息到: " + params.getTargetAgentType());
    return params;  // 可以在返回前修改 params 的字段
});

---

ByaiGatewayClient

ByaiGatewayClient 继承自 GatewayClient，自动注册了 ByaiMessageInterceptor，用于适配 BeyonAI 平台内部的消息格式。

/**
 * ByaiGatewayClient 构造方法。
 * 自动包含 ByaiMessageInterceptor，无需手动添加。
 *
 * @param redisClient Redis 客户端实例
 */
public ByaiGatewayClient(RedisClient redisClient);

使用示例：

RedisClient redisClient = new RedisClient("localhost", 6379);
ByaiGatewayClient client = new ByaiGatewayClient(redisClient);

// 直接使用，无需额外配置拦截器
SendResponse response = client.sendMessage("agent_type", "session_001", "Hello");

---

GatewayInterceptor

GatewayInterceptor 是一个单方法函数式接口，在消息发送前执行，接收并返回 SendMessageParams——可以用来 修改即将发出的请求参数（日志记录、参数校验、内容转换等）。它只有 beforeSend，没有 afterSend 钩子； 如果需要观察发送结果，在调用 sendMessage(...) 之后直接检查返回的 SendResponse 即可。

public interface GatewayInterceptor {
    /**
     * 发送前拦截，接收当前参数并返回（可能修改过的）参数。
     */
    SendMessageParams beforeSend(SendMessageParams params);
}

使用示例：

GatewayInterceptor logInterceptor = params -> {
    System.out.println("[INFO] 发送消息 - target: " + params.getTargetAgentType());
    return params;
};

client.addInterceptor(logInterceptor);

SendResponse response = client.sendMessage("my_agent", "session_001", "帮我分析数据");
if (response.isSuccess()) {
    System.out.println("[INFO] 消息发送成功 - messageId: " + response.getMessageId());
} else {
    System.err.println("[ERROR] 消息发送失败 - " + response.getError());
}

---

SendResponse

SendResponse 是 GatewayClient 的内部类，封装了消息发送的响应结果。

public class SendResponse {
    /** 消息发送是否成功 */
    public boolean isSuccess();

    /** 获取分配的消息 ID */
    public String getMessageId();

    /** 获取本次发送使用的 trace ID */
    public String getTraceId();

    /** 获取目标 Worker ID */
    public String getTargetWorkerId();

    /** 获取发送状态 */
    public String getStatus();

    /** 获取时间戳 */
    public long getTimestamp();

    /** 获取错误信息（如有） */
    public String getError();

    /** 获取错误码（如有） */
    public String getErrorCode();
}

属性表

方法	返回类型	描述
isSuccess()	boolean	消息是否发送成功
getMessageId()	String	分配的消息 ID
getTraceId()	String	本次发送使用的 trace ID
getTargetWorkerId()	String	目标 Worker ID
getStatus()	String	发送状态
getTimestamp()	long	时间戳
getError()	String	错误信息（成功时为空字符串）
getErrorCode()	String	错误码（成功时为空）

---

CancelTaskResponse

CancelTaskResponse 是 GatewayClient 的内部类，封装了任务取消操作的响应结果。

public class CancelTaskResponse {
    /** 取消操作是否成功 */
    public boolean isSuccess();

    /** 被取消的消息 ID */
    public String getMessageId();

    /** 被取消的执行 ID */
    public String getExecutionId();

    /** 处理该执行的 Worker ID */
    public String getWorkerId();

    /** 取消状态 */
    public String getStatus();

    /** 时间戳 */
    public long getTimestamp();

    /** 错误信息（如有） */
    public String getError();
}

属性表

方法	返回类型	描述
isSuccess()	boolean	取消操作是否成功
getMessageId()	String	被取消的消息 ID
getExecutionId()	String	被取消的执行 ID
getWorkerId()	String	处理该执行的 Worker ID
getStatus()	String	取消操作状态
getTimestamp()	long	时间戳
getError()	String	错误信息（成功时为空字符串）

---

完整使用示例

// 1. 初始化客户端
RedisClient redisClient = new RedisClient("localhost", 6379);
ByaiGatewayClient client = new ByaiGatewayClient(redisClient);

// 2. 添加自定义拦截器（单方法接口，发送前执行，返回可能修改过的参数）
client.addInterceptor(params -> {
    System.out.println("[LOG] 准备发送消息到: " + params.getTargetAgentType());
    return params;
});

// 3. 发送消息（11 参重载：不需要路由策略控制时用这个更简单）
SendResponse response = client.sendMessage(
    "data_analyzer",
    "session_abc",
    "请分析最近一周的数据",
    "user_001",
    "李四",
    ActionType.ASK_AGENT,
    "",                                    // parentMessageId
    null,                                  // messageId（自动生成）
    null,                                  // traceId（自动生成）
    Map.of("dataSource", "mysql"),         // payload
    Map.of("priority", "normal")           // metadata
);

// 4. 检查响应
if (response.isSuccess()) {
    System.out.println("消息发送成功，messageId: " + response.getMessageId());
    System.out.println("目标 Worker: " + response.getTargetWorkerId());
} else {
    System.err.println("消息发送失败: " + response.getError());
}

// 5. 取消任务（如果需要）
CancelTaskResponse cancelResp = client.cancelTask(
    response.getMessageId(),
    "session_abc",
    "不再需要结果",
    "",              // targetAgentType
    "client",        // requestedBy
    "graceful"       // cancelMode
);

System.out.println("取消结果: " + cancelResp.isSuccess());