ExtSkill API (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. Classes live in com.agibot.aiem.sdk.extskill. See the ExtSkill guide for the workflow.

Class diagram

text

AgentSdk
  ├── registerExtSkill(ExtSkillRequest)               // binds LinkskyClient
  └── unregisterExtSkill(String requestId): void

ExtSkillRequest
  ├── ExtSkillRequest(agentSdk, agentId, requestId)
  ├── query(ExtSkillQueryCallback cb, long timeout): String            // returns eventId
  └── invoke(String extSkillId, AgentParam input,
             ExtSkillInvokeCallback cb, long timeout): String          // returns eventId

ExtSkillQueryCallback            // abstract base class
  └── onQueryResult(agentId, requestId, eventId, code, msg, AgentParam result): void

ExtSkillInvokeCallback           // abstract base class
  ├── onInvokeAck(agentId, requestId, eventId, code, msg): void
  ├── onState(agentId, requestId, eventId, stateName, stateValue): void
  └── onInvokeResult(agentId, requestId, eventId, code, msg, AgentParam param): void

IdGenerator
  └── generateExtSkillRequestId(): String    // "extskill_<21 random chars>"

`AgentSdk` (new methods)

Method	Description
`registerExtSkill(ExtSkillRequest request): void`	Binds the request to the current SDK's `LinkskyClient` and adds it to the global `AgentSdkExtSkillMgr` index. Must be called before `query` / `invoke`.
`unregisterExtSkill(String requestId): void`	Removes it from the index. Call when done.

`ExtSkillRequest`

java

new ExtSkillRequest(AgentSdk agentSdk, String agentId, String requestId)

Method	Semantics
`query(ExtSkillQueryCallback cb, long timeout): String`	Query the extended skills currently available on the agent. `timeout < 50` is clamped to 50 (stored but currently inert). Returns the message `eventId`. Result comes back via `cb.onQueryResult`.
`invoke(String extSkillId, AgentParam input, ExtSkillInvokeCallback cb, long timeout): String`	Trigger a skill to run. `extSkillId` is the skill ID; `input` is structured input (`AgentParam`); `timeout` handled as in `query`. Returns the message `eventId`. `cb.onInvokeAck` fires first (accept), then `cb.onInvokeResult` (output).
`getUpdateTs(): long`	Last send time (ms). Idle for 7200s → reclaimed by the background cleaner.
`getAgentId()` / `getRequestId(): String`	Session identity.
`getQueryCallback()` / `getInvokeCallback()`	Most recently bound callbacks.

Callback codes

`code`	Meaning
`0`	Success (gateway business ACK; `result` / `param` carries content)
`-1`	Server returned failure; `msg` carries `errorMsg`
`1000`	Local failure: `LinkskyClient` was closed at send time; the SDK invokes this code synchronously on the calling thread

`ExtSkillQueryCallback`

Abstract base class; extend and override onQueryResult:

java

import com.agibot.aiem.sdk.AgentParam;
import com.agibot.aiem.sdk.extskill.ExtSkillQueryCallback;

ExtSkillQueryCallback queryCallback = new ExtSkillQueryCallback() {
    @Override
    public void onQueryResult(String agentId, String requestId, String eventId,
                              int code, String msg, AgentParam result) {
        // code == 0 success, result carries the skill list; -1 server reject; 1000 local close (result == null)
    }
};

Abstract base class; invoke reports in three stages (all three methods are abstract and must be overridden): onInvokeAck (accept) → onState (zero or more execution-time state reports) → onInvokeResult (output).

java

import com.agibot.aiem.sdk.AgentParam;
import com.agibot.aiem.sdk.extskill.ExtSkillInvokeCallback;

ExtSkillInvokeCallback invokeCallback = new ExtSkillInvokeCallback() {
    @Override
    public void onInvokeAck(String agentId, String requestId, String eventId, int code, String msg) {
        // stage 1: gateway accepted this invoke (code == 0)
    }

    @Override
    public void onState(String agentId, String requestId, String eventId,
                        String stateName, String stateValue) {
        // execution-time progress reported via agentsdk.ext_skill.report_state; zero or more times
    }

    @Override
    public void onInvokeResult(String agentId, String requestId, String eventId,
                               int code, String msg, AgentParam param) {
        // stage 3: skill execution output; param carries the result when code == 0
    }
};

Both callback base classes also carry a timeout field (injected internally via setTimeout(...), clamped to a ≥50ms placeholder).

`IdGenerator.generateExtSkillRequestId()`

Generates a session ID like extskill_ABCDEFGHIJKLMNOPQRSTU (prefix + 21 random chars). It does not collide with flow_ / event_ / teleop_ and other prefixes.

Event types (`AgentEventType`)

See the AGENTSDK_EXT_SKILL_* section in the enums reference.