扩展技能(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 索引,互不冲突 |