扩展技能(ExtSkill)示例

扩展技能(ExtSkill)示例

⚠️ 尚未上线:本能力为 v1.5.0-SNAPSHOT 开发中特性,接口与协议可能调整,正式发布前请勿用于生产环境。

v1.5.0 新增。完整的 Python 端最小示例,展示 query(拉取清单)与 invoke(触发执行,三段回调:ack → state → result)全流程。

最小示例

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"
app_key    = "您通过灵心开放平台创建的应用获取的appKey"
app_secret = "您通过灵心开放平台创建的应用获取的appSecret"
agent_id   = "您通过灵心平台创建的二开智能体获取的agentId"

# 第一步:创建 SDK 实例
agent_sdk = AgentSdk.create(url, app_id, app_key, app_secret)


# 第二步:注册验签回调
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())

# 第三步:初始化
agent_sdk.initialize()
time.sleep(2)

# 第四步:注册扩展技能请求实例
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 查询可用扩展技能清单
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 触发某个扩展技能执行
ext_skill_id = "test_ext_skill_id_001"           # 扩展技能 ID
input_param = (                                   # 扩展技能入参
    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:
        # 第一段:网关已受理
        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:
        # 第二段:执行期间状态上报(0 到多次)
        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:
        # 第三段:技能执行输出
        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)

# 第五步:反注册释放
agent_sdk.unregister_ext_skill(request_id)
# agent_sdk.release()

常见改写要点

想做改哪里
只拉清单不触发只调 query(...),拿到 on_query_result 的 result 即可;invoke 可省略
触发不同技能换 invoke 的第一个参数 ext_skill_id;input_param 按目标技能定义填 AgentParam
传结构化入参AgentParam.create().set_string(...).set_integer(...);wire 上以扁平键值下发
只关心最终结果on_invoke_ack 可只记日志;真正输出在 on_invoke_result 的 param(code == 0 时非 None)
感知 SDK 鉴权 / 断连query / invoke 回调收到 code == 1000 表示本地连接已关闭,应重连后重试
多智能体并行每个 agent_id 建一个 ExtSkillRequest(各自独立 request_id);SDK 按 request_id 索引,互不冲突