ExtSkill examples (extended skills)

ExtSkill examples (extended skills)

⚠️ Not yet released: in-development v1.5.0-SNAPSHOT capability; interface and protocol may change. Do not use in production before the official release.

New in v1.5.0. A complete minimal Java example showing query (fetch the list) and invoke (trigger execution, three-stage callback: ack → state → result). Source: agentsdk_for_java/example/src/main/java/com/agibot/aiem/extskill/ExtSkillExample.java.

Minimal example: 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 obtained from your app created on the LinkSoul open platform";
        String appKey    = "appKey obtained from your app created on the LinkSoul open platform";
        String appSecret = "appSecret obtained from your app created on the LinkSoul open platform";
        String agentId   = "agentId obtained from your custom agent created on the LinkSoul platform";

        // Step 1: create the SDK instance
        AgentSdk agentSdk = AgentSdk.create(url, appId, appKey, appSecret);

        // Step 2: register the auth callback
        agentSdk.registerAuth(new AgentAuthCallback() {
            @Override
            public void onAuthState(String appId, int code, String msg) {
                System.out.println("onAuthState => appId: " + appId
                        + ", code: " + code + ", msg: " + msg);
            }
        });

        // Step 3: initialize
        agentSdk.initialize();

        Thread.sleep(2000);

        // Step 4: register the extended-skill request instance
        String requestId = IdGenerator.generateExtSkillRequestId();
        ExtSkillRequest extSkillRequest = new ExtSkillRequest(agentSdk, agentId, requestId);
        agentSdk.registerExtSkill(extSkillRequest);

        // 4.1 query the available extended-skill list
        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 trigger a skill to run
        String extSkillId = "test_ext_skill_id_001";           // extended skill ID
        AgentParam input = AgentParam.create();                // skill input
        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) {
                // stage 1: gateway accepted
                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) {
                // stage 2: execution-time state report (zero or more times)
                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) {
                // stage 3: skill execution 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);

        // Step 5: unregister to release
        agentSdk.unregisterExtSkill(requestId);
        // agentSdk.release();
    }
}

Common variations

GoalWhat to change
List only, no triggerCall query(...) and use result from onQueryResult; skip invoke
Trigger a different skillChange the first argument extSkillId of invoke; fill input per the target skill's definition
Pass structured inputAgentParam.create().setString(...).setInteger(...); sent as flat key-values on the wire
Only care about the final resultonInvokeAck may just log; the real output is param in onInvokeResult (non-null when code == 0)
Detect auth / disconnectcode == 1000 in query / invoke callbacks means the local connection is closed; reconnect and retry
Multiple agents in parallelCreate one ExtSkillRequest per agentId (each with its own requestId); the SDK indexes by requestId, no conflict