扩展技能(ExtSkill)示例
扩展技能(ExtSkill)示例
⚠️ 尚未上线:本能力为 v1.5.0-SNAPSHOT 开发中特性,接口与协议可能调整,正式发布前请勿用于生产环境。
v1.5.0 新增。完整的 Java 端最小示例,展示
query(拉取清单)与invoke(触发执行,三段回调:ack → state → result)全流程。示例源码位于仓库agentsdk_for_java/example/src/main/java/com/agibot/aiem/extskill/ExtSkillExample.java。
最小示例:ExtSkillExample.java
java
package com.agibot.aiem.extskill;
import com.agibot.aiem.sdk.AgentAuthCallback;
import com.agibot.aiem.sdk.AgentParam;
import com.agibot.aiem.sdk.AgentSdk;
import com.agibot.aiem.sdk.IdGenerator;
import com.agibot.aiem.sdk.extskill.ExtSkillInvokeCallback;
import com.agibot.aiem.sdk.extskill.ExtSkillQueryCallback;
import com.agibot.aiem.sdk.extskill.ExtSkillRequest;
import lombok.extern.slf4j.Slf4j;
@Slf4j
public class ExtSkillExample {
public static void main(String[] args) throws InterruptedException {
String url = "wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk";
String appId = "您通过灵心开放平台创建的应用获取的appId";
String appKey = "您通过灵心开放平台创建的应用获取的appKey";
String appSecret = "您通过灵心开放平台创建的应用获取的appSecret";
String agentId = "您通过灵心平台创建的二开智能体获取的agentId";
// 第一步:创建 SDK 实例
AgentSdk agentSdk = AgentSdk.create(url, appId, appKey, appSecret);
// 第二步:注册验签回调接口
agentSdk.registerAuth(new AgentAuthCallback() {
@Override
public void onAuthState(String appId, int code, String msg) {
System.out.println("onAuthState => appId: " + appId
+ ", code: " + code + ", msg: " + msg);
}
});
// 第三步:初始化
agentSdk.initialize();
Thread.sleep(2000);
// 第四步:注册扩展技能请求实例
String requestId = IdGenerator.generateExtSkillRequestId();
ExtSkillRequest extSkillRequest = new ExtSkillRequest(agentSdk, agentId, requestId);
agentSdk.registerExtSkill(extSkillRequest);
// 4.1 查询可用扩展技能清单
String queryEventId = extSkillRequest.query(new ExtSkillQueryCallback() {
@Override
public void onQueryResult(String agentId, String requestId, String eventId,
int code, String msg, AgentParam result) {
log.info("onQueryResult => agentId {}, requestId {}, eventId {}, code {}, msg {}, result {}",
agentId, requestId, eventId, code, msg, result);
}
}, 2000);
log.info("query queryEventId {}", queryEventId);
// 4.2 触发某个扩展技能执行
String extSkillId = "test_ext_skill_id_001"; // 扩展技能 ID
AgentParam input = AgentParam.create(); // 扩展技能入参
input.setString("role", "male");
input.setInteger("threshold", 0);
String invokeEventId = extSkillRequest.invoke(extSkillId, input, new ExtSkillInvokeCallback() {
@Override
public void onInvokeAck(String agentId, String requestId, String eventId, int code, String msg) {
// 第一段:网关已受理
log.info("onInvokeAck => agentId {}, requestId {}, eventId {}, code {}, msg {}",
agentId, requestId, eventId, code, msg);
}
@Override
public void onState(String agentId, String requestId, String eventId, String stateName, String stateValue) {
// 第二段:执行期间状态上报(0 到多次)
log.info("onState => agentId {}, requestId {}, eventId {}, stateName {}, stateValue {}",
agentId, requestId, eventId, stateName, stateValue);
}
@Override
public void onInvokeResult(String agentId, String requestId, String eventId,
int code, String msg, AgentParam output) {
// 第三段:技能执行输出
log.info("onInvokeResult => agentId {}, requestId {}, eventId {}, code {}, msg {}, output {}",
agentId, requestId, eventId, code, msg, output);
}
}, 2000);
log.info("invoke invokeEventId {}", invokeEventId);
Thread.sleep(5000);
// 第五步:反注册释放
agentSdk.unregisterExtSkill(requestId);
// agentSdk.release();
}
}
常见改写要点
| 想做 | 改哪里 |
|---|---|
| 只拉清单不触发 | 只调 query(...),拿到 onQueryResult 的 result 即可;invoke 可省略 |
| 触发不同技能 | 换 invoke 的第一个参数 extSkillId;input 按目标技能定义填 AgentParam |
| 传结构化入参 | AgentParam.create().setString(...).setInteger(...);wire 上以扁平键值下发 |
| 只关心最终结果 | onInvokeAck 可只记日志;真正输出在 onInvokeResult 的 param(code == 0 时非空) |
| 感知 SDK 鉴权 / 断连 | query / invoke 回调收到 code == 1000 表示本地连接已关闭,应重连后重试 |
| 多智能体并行 | 每个 agentId 建一个 ExtSkillRequest(各自独立 requestId);SDK 按 requestId 索引,互不冲突 |