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 Python example showing
query(fetch the list) andinvoke(trigger execution, three-stage callback: ack → state → result).
Minimum example
python
import time
from linksoul_agentsdk import (
AgentAuthCallback,
AgentParam,
AgentSdk,
ExtSkillInvokeCallback,
ExtSkillQueryCallback,
ExtSkillRequest,
IdGenerator,
)
url = "wss://open.agibot.com/api/V1/open-portal/app/wss/agent-sdk"
app_id = "<appId from the LinkSoul open platform>"
app_key = "<appKey from the LinkSoul open platform>"
app_secret = "<appSecret from the LinkSoul open platform>"
agent_id = "<agentId from your custom agent on the LinkSoul platform>"
# 1. Create the SDK instance
agent_sdk = AgentSdk.create(url, app_id, app_key, app_secret)
# 2. Register auth callback
class MyAuthCallback(AgentAuthCallback):
def on_auth_state(self, app_id: str, code: int, msg: str) -> None:
print(f"on_auth_state => app_id: {app_id}, code: {code}, msg: {msg}")
agent_sdk.register_auth(MyAuthCallback())
# 3. Open the WebSocket connection
agent_sdk.initialize()
time.sleep(2)
# 4. Register an extended-skill request instance
request_id = IdGenerator.generate_ext_skill_request_id()
ext_skill_request = ExtSkillRequest(agent_sdk, agent_id, request_id)
agent_sdk.register_ext_skill(ext_skill_request)
# 4.1 Query the available extended-skill list
class MyQueryCallback(ExtSkillQueryCallback):
def on_query_result(self, agent_id: str, request_id: str, event_id: str,
code: int, msg: str, result) -> None:
print(f"on_query_result => agent_id={agent_id}, request_id={request_id}, "
f"event_id={event_id}, code={code}, msg={msg}, result={result}")
query_event_id = ext_skill_request.query(MyQueryCallback(), 2000)
print(f"query event_id: {query_event_id}")
# 4.2 Trigger a skill to run
ext_skill_id = "test_ext_skill_id_001" # extended skill ID
input_param = ( # skill input
AgentParam.create()
.set_string("role", "male")
.set_integer("threshold", 0)
)
class MyInvokeCallback(ExtSkillInvokeCallback):
def on_invoke_ack(self, agent_id: str, request_id: str, event_id: str,
code: int, msg: str) -> None:
# stage 1: gateway accepted
print(f"on_invoke_ack => agent_id={agent_id}, request_id={request_id}, "
f"event_id={event_id}, code={code}, msg={msg}")
def on_state(self, agent_id: str, request_id: str, event_id: str,
state_name, state_value) -> None:
# stage 2: execution-time state report (zero or more times)
print(f"on_state => agent_id={agent_id}, request_id={request_id}, "
f"event_id={event_id}, state_name={state_name}, state_value={state_value}")
def on_invoke_result(self, agent_id: str, request_id: str, event_id: str,
code: int, msg: str, param) -> None:
# stage 3: skill execution output
print(f"on_invoke_result => agent_id={agent_id}, request_id={request_id}, "
f"event_id={event_id}, code={code}, msg={msg}, param={param}")
invoke_event_id = ext_skill_request.invoke(ext_skill_id, input_param, MyInvokeCallback(), 2000)
print(f"invoke event_id: {invoke_event_id}")
time.sleep(5)
# 5. Unregister to release
agent_sdk.unregister_ext_skill(request_id)
# agent_sdk.release()
Common variations
| Goal | What to change |
|---|---|
| List only, no trigger | Call query(...) and use result from on_query_result; skip invoke |
| Trigger a different skill | Change the first argument ext_skill_id of invoke; fill input_param per the target skill's definition |
| Pass structured input | AgentParam.create().set_string(...).set_integer(...); sent as flat key-values on the wire |
| Only care about the final result | on_invoke_ack may just log; the real output is param in on_invoke_result (non-None 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 agent_id (each with its own request_id); the SDK indexes by request_id, no conflict |