扩展技能(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 索引,互不冲突