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) andinvoke(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
| Goal | What to change |
|---|---|
| List only, no trigger | Call query(...) and use result from onQueryResult; skip invoke |
| Trigger a different skill | Change the first argument extSkillId of invoke; fill input per the target skill's definition |
| Pass structured input | AgentParam.create().setString(...).setInteger(...); sent as flat key-values on the wire |
| Only care about the final result | onInvokeAck may just log; the real output is param in onInvokeResult (non-null when code == 0) |
| Detect auth / disconnect | code == 1000 in query / invoke callbacks means the local connection is closed; reconnect and retry |
| Multiple agents in parallel | Create one ExtSkillRequest per agentId (each with its own requestId); the SDK indexes by requestId, no conflict |