# LinkSoul AgentSDK for Python

LinkSoul 智能体二开 SDK 的 Python 版本，与 Java 版 API 等价。当前对齐 Java `v1.4.0-SNAPSHOT`。

## 安装

```bash
pip install -e .
# 或：pip install -r requirements.txt
```

依赖：`websocket-client>=1.7`, `PyJWT>=2.8`。

## 30 秒上手（Asr2Llm）

```python
from linksoul_agentsdk import AgentSdk, AgentAuthCallback, AgentParam, IdGenerator
from linksoul_agentsdk.passive import Asr2LlmCallback, Asr2LlmResponse

agent_sdk = AgentSdk.create(
    url="wss://agentsdk.agibot.com/v1/agentsdk",
    app_id="<your appId>",
    app_secret="<your appSecret, at least 32 bytes>",
)


class AuthCb(AgentAuthCallback):
    def on_auth_state(self, app_id: str, code: int, msg: str) -> None:
        print(f"auth => {app_id} {code} {msg}")


class MyCallback(Asr2LlmCallback):
    def on_request(self, agent_id, event_id, text, param, response: Asr2LlmResponse):
        if not text:  # 拒识：什么都不做
            return
        item_id = IdGenerator.generate_item_id()
        # 有效指令 — 必须先打断，再下发技能/LLM
        response.on_interrupt(event_id, "chat", None)
        response.on_llm_item_delta(event_id, item_id, "好的，正在处理。")
        response.on_llm_item_done(event_id, item_id)
        response.on_llm_done(event_id)


agent_sdk.register_auth(AuthCb())
agent_sdk.register_asr2_llm(MyCallback(agent_sdk))
agent_sdk.initialize()
```

更多示例见 `examples/`。

## 公开 API（v1.4.0）

- 被动回调注册：`register_audio2_llm` / `register_audio2_tts` / `register_asr2_llm` /
  `register_asr2_tts` / `register_asr_video2_vlm` / `register_asr_video2_tts` /
  `register_audio_video2_vlm` / `register_audio_video2_tts`
- 主动接口：`register_task_flow(TaskFlowRequest)` / `unregister_task_flow(flow_id)`
- 打招呼信令、状态推送、人脸/UID、视频帧透传 — 在任一被动回调子类里重载 `on_greet_signal` /
  `on_state` / `on_face_info` / `on_video_frame`

完整文档见仓库根目录 `agentsdk_docs/`。

## 运行测试

```bash
pip install -e ".[dev]"
pytest
```

测试不依赖真实 WebSocket 服务器——内部用 `FakeLinkskyClient` 打桩。
