主动请求 API 参考

v1.4.0：当前 AgentSdk 仅公开 任务流 一个主动入口。技能查询、状态查询、拉流、推流监听暂未开放。状态推送已合并到 PassiveCallback.onState(...)，详见被动回调指南。

TaskFlowRequest

构造

java

// COMPLEX模式（默认）
TaskFlowRequest flow = new TaskFlowRequest(agentSdk, agentId, flowId);

// 指定模式
TaskFlowRequest flow = new TaskFlowRequest(agentSdk, agentId, flowId, FlowMode.SIMPLE);

方法

方法	返回值	说明
`startRequest(payload, callback, timeout)`	`String` (eventId)	启动流程
`taskRequest(payload, callback, timeout)`	`String` (eventId)	发送任务步骤
`endRequest(callback, timeout)`	`String` (eventId)	结束流程
`interruptRequest(callback, timeout)`	`String` (eventId)	中断流程
`getFlowId()`	`String`	获取流程ID
`getAgentId()`	`String`	获取目标智能体 ID（灵心平台配置的智能体 ID）

payload: JSON 字符串（任务流协议要求为 JSON 数组，如 "[{...}]"，详见任务流 payload 协议）
timeout: 超时时间（毫秒），最小50ms

流程回调

java

public abstract class FlowStartCallback {
    public abstract void onStartRequestAck(String flowId, String eventId, int code, String msg);
    public abstract void onStartExecuteAck(String flowId, String eventId, int code, String msg);
}

public abstract class FlowTaskCallback {
    public abstract void onTaskRequestAck(String flowId, String eventId, int code, String msg);
    public abstract void onTaskExecuteAck(String flowId, String eventId, int code, String msg);
}

public abstract class FlowEndCallback {
    public abstract void onEndRequestAck(String flowId, String eventId, int code, String msg);
}

public abstract class FlowInterruptCallback {
    public abstract void onInterruptRequestAck(String flowId, String eventId, int code, String msg);
}

两阶段确认：RequestAck = 机器人收到请求，ExecuteAck = 机器人执行完成。code=0 表示成功。

工具类

AgentParam（扩展参数）

支持链式调用的键值对容器：

java

// 创建并设置参数
AgentParam param = AgentParam.create()
    .setString("action", "navigate")
    .setInteger("step", 3)
    .setDouble("speed", 1.5)
    .setBoolean("safe", true)
    .setLong("timestamp", System.currentTimeMillis());

// 读取参数
String action = param.getString("action");
Integer step = param.getInteger("step");

完整方法列表：

方法	类型
`getString/setString`	String
`getInteger/setInteger`	Integer
`getLong/setLong`	Long
`getDouble/setDouble`	Double
`getShort/setShort`	Short
`getBoolean/setBoolean`	Boolean
`getObject/setObject`	Object
`getList/setList`	List<?>
`getExtParam()`	Map（获取底层JSON对象）

AgentMeta（机器人元数据）

机器人上线时通过 onRobotOnline(agentId, agentMeta) 获取：

java

@Override
public void onRobotOnline(String agentId, AgentMeta agentMeta) {
    String wakeup = agentMeta.getWakeupWord();    // 唤醒词
    String city = agentMeta.getCity();            // 所在城市
    String name = agentMeta.getRobotName();       // 机器人名字
    String buzzWord = agentMeta.getBuzzWord();    // 热词
    String custom = agentMeta.getString("yourKey"); // 自定义字段
}

IdGenerator（ID生成器）

java

String flowId = IdGenerator.generateFlowId();     // "flow_xxxxx..."
String eventId = IdGenerator.generateEventId();   // "event_xxxxx..."
String itemId = IdGenerator.generateItemId();     // "item_xxxxx..."
String signalId = IdGenerator.generateSignalId(); // "signal_xxxxx..."

所有ID为 前缀 + 21位随机字符串（大小写字母+数字），使用 SecureRandom 保证唯一性。