zhuye (Python SDK)
让 Python 项目直接驱动 Zhuye Agent 的轻量 SDK。底层通过 spawn zhuye serve 子进程、走 JSONL stdio 协议,零运行时依赖(仅 stdlib)。
安装
pip install zhuye
安装即用:PyPI 提供平台 wheel(macOS arm64 / x86_64,Linux x86_64 /
aarch64 glibc,Windows x86_64),内嵌对应平台的 zhuye 二进制,SDK
优先解析它 —— 无需自装二进制、无需配环境变量。
二进制解析优先级:显式 options.bin → ZHUYE_BIN → wheel 内嵌
二进制 → PATH 上的 zhuye。当前平台不在支持矩阵(如 musl/Alpine)
时回退 PATH:从 GitHub Releases
下载,或从本仓库 make build 产出 target/release/zhuye 后以
ZHUYE_BIN 指向。
用法
from zhuye import ZhuyeAgent, ToolOutput, ContentBlock
agent = ZhuyeAgent.spawn()
# 注册客户端自定义工具(LLM 调用时由本地函数返回结果)
def get_weather(args):
return ToolOutput(
content=[ContentBlock(type="text", text=f"{args['city']} 今天晴 26℃")],
is_error=False,
metadata={},
elapsed_ms=0,
)
agent.register_tool(
name="get_weather",
description="查询城市天气",
parameters={
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
handler=get_weather,
)
# 高层:聚合 delta,返回最终文本
print(agent.prompt("北京天气如何?"))
# 低层:遍历 turn 事件
for ev in agent.submit("第二轮"):
msg = ev["msg"]
if msg["type"] == "agent_message_delta":
print(msg["delta"], end="", flush=True)
if msg["type"] == "turn_complete":
break
agent.close()
全局事件
next_global_event(timeout_secs=5) 读取 id="" 的会话事件,与 submit() 的
按 submission 路由的事件迭代器独立。超时抛 queue.Empty,进程 stdout
关闭后返回 None;未知变体原样返回。
handshake = agent.next_global_event(timeout_secs=5)
环境变量
| 变量 | 作用 |
|---|---|
ZHUYE_BIN |
zhuye 二进制路径(最高优先级覆盖;缺省用 wheel 内嵌二进制)。 |
ZHUYE_MODEL |
模型 spec(mock/mock-1 用于离线 SDK 集成测试)。 |
ZHUYE_REMOTE_TOOL_TIMEOUT_SECS |
远程工具等待客户端回执的上限,默认 120s。 |
测试
python3 -m pip install pytest
python3 -m pytest -ra
mock serve 进程跑在 Node 上(Node ≥ 18),不依赖真 zhuye 二进制 —— 测试完全离线,也不需要网络/API key。仓库内开发直接以源码树运行(python -m pytest 会把本目录加入 sys.path),无需构建安装;打包后端为 maturin(平台 wheel 由 CI 产出并内嵌二进制,见 docs/release.md),本地构建需 Rust 工具链。
端到端测试(对真 zhuye serve 子进程的集成)在仓库 CI 里跑;在仓库根配置好 ZHUYE_BIN 后执行 ./tests/run_all.sh sdk-python。
协议
SDK 与 zhuye serve 之间的 wire 协议见 ../PROTOCOL.md(同仓库 sdks/PROTOCOL.md)。Rust 核心新增协议变体时,SDK 自动降为 UnknownEventMsg,不会中断下游。
1 maintainer
Metadata
1 maintainer
Release files for zhuye 0.1.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| zhuye-0.1.8.tar.gz | 14.7 kB | With provenance | Details for zhuye-0.1.8.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| zhuye-0.1.8-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details for zhuye-0.1.8-py3-none-win_amd64.whl |
| zhuye-0.1.8-py3-none-manylinux_2_34_x86_64.whl | Python 3 | none | Linux glibc 2.34+ x86-64 | Details for zhuye-0.1.8-py3-none-manylinux_2_34_x86_64.whl |
| zhuye-0.1.8-py3-none-manylinux_2_34_aarch64.whl | Python 3 | none | Linux glibc 2.34+ ARM64 | Details for zhuye-0.1.8-py3-none-manylinux_2_34_aarch64.whl |
| zhuye-0.1.8-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details for zhuye-0.1.8-py3-none-macosx_11_0_arm64.whl |
| zhuye-0.1.8-py3-none-macosx_10_12_x86_64.whl | Python 3 | none | macOS 10.12+ x86-64 | Details for zhuye-0.1.8-py3-none-macosx_10_12_x86_64.whl |
Total release size: 66.5 MB
Release files / zhuye-0.1.8.tar.gz
| Download URL | zhuye-0.1.8.tar.gz |
|---|---|
| Size | 14.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5dadd0b6804380a0cb75cfedeb8b58fdf2112eaf499f4981aa2236ac501977a7
|
|
BLAKE2b-256 checksum How to use checksums |
038201575646c1b968c2e499b03bd109adaf94ed3219db7bc6e04c69d0ec6f8f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logRelease files / zhuye-0.1.8-py3-none-win_amd64.whl
| Download URL | zhuye-0.1.8-py3-none-win_amd64.whl |
|---|---|
| Size | 13.4 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
4b0b86a365c7496a2eaaa092ac7f28062fc6a930248d65b881e807e6b68cb5d5
|
|
BLAKE2b-256 checksum How to use checksums |
cda31102afba6b2eda4a2f5c9808fb5978a11cac14c079b40d2df4c7eb02e1c4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logRelease files / zhuye-0.1.8-py3-none-manylinux_2_34_x86_64.whl
| Download URL | zhuye-0.1.8-py3-none-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 14.3 MB |
| Tags | Linux glibc 2.34+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
2d884730539cc3b4237db2ac471f0e6684d0ae7296b3b09199fdc619d004a754
|
|
BLAKE2b-256 checksum How to use checksums |
fbf4d10e549a0ce461227dbdb54cb9c243d365f7361c11258385a23ae12c8d1b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logRelease files / zhuye-0.1.8-py3-none-manylinux_2_34_aarch64.whl
| Download URL | zhuye-0.1.8-py3-none-manylinux_2_34_aarch64.whl |
|---|---|
| Size | 13.4 MB |
| Tags | Linux glibc 2.34+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
d83fe579636aac634cfeee4bf0f285595ca309659c09086c3e4168a03bc532bc
|
|
BLAKE2b-256 checksum How to use checksums |
cb3fbdf772c223da7701829b57ed8dff2c97d61cc398b9e9a61f04874e00656b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logRelease files / zhuye-0.1.8-py3-none-macosx_11_0_arm64.whl
| Download URL | zhuye-0.1.8-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 12.4 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
d31cbd85ee42c5077c171d7a8a448a29f77a50d577e0ae61123a99dd817ff4e3
|
|
BLAKE2b-256 checksum How to use checksums |
57130294015b6d85e48633608ccae7748b2f15a3424d63140912d44c69059b22
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logRelease files / zhuye-0.1.8-py3-none-macosx_10_12_x86_64.whl
| Download URL | zhuye-0.1.8-py3-none-macosx_10_12_x86_64.whl |
|---|---|
| Size | 13.0 MB |
| Tags | Python 3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
77a11cc745b887c181d110e83b097908acceae1e9d8213477955e34c16d10471
|
|
BLAKE2b-256 checksum How to use checksums |
f3d5108674a9d060cb44ce21cfbf2066a9767dfbf421cc9ed02e41bf635adc04
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logSecurity for zhuye 0.1.8
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 6 files in this release have been uploaded with provenance metadata.
Attestation for zhuye-0.1.8.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
