hostanagent-client 0.2.5

用于产品后端的独立异步 SDK，Python >=3.10，仅依赖 httpx；不安装 HostAnAgent 服务、Worker 或 aisuite。协议兼容 1.0，0.2.5 增补平台标准工具的接入说明，并验证平台等待、快照、错误及取消的兼容性。本 SDK 及随包文档采用 MIT，版权归 GeekArt Inc.；这项授权覆盖 SDK 目录，服务端另行管理。

python -m pip install hostanagent-client==0.2.5

在自己的控制台发布 Agent，用服务端应用 Key 连接。平台管理模型供应商凭证。当前代码已整合 D01：创建限制到目标 Agent 的 runtime:read、runtime:write Key；工具执行额外需要 tools:execute。运行发现使用 await client.bootstrap()，不需要配置管理权限。部署状态以文档仓库实施记录为准。

import os
from hostanagent import AgentClient, HostingError, idempotency_key

async def chat(trusted_product_user_id):
    async with AgentClient("https://api.hostanagent.com/v1", os.environ["HAA_APPLICATION_KEY"],
                           subject=trusted_product_user_id) as client:
        # Subject 必须来自产品验证过的登录态，不能直接取浏览器提交的 user_id。
        models = await client.models()  # reasoning_options 决定可用五档思考强度
        session = await client.create_session()
        key = idempotency_key()  # 产品保存本请求的 key、正文和参数，未知结果时原样重试
        try:
            accepted = await client.run(session["id"], os.environ["HAA_AGENT_VERSION"], "整理我的任务",
                idempotency_key=key, reasoning_effort="high", execution_mode="propose",
                limits={"max_cost_usd": "1.000000000000"})
        except HostingError as error:
            if error.code == "INSUFFICIENT_BALANCE":
                # 没有模型调用；当前人工测试入账，在线充值尚未开放。
                return
            raise
        async for event in client.events(accepted["run_id"]):
            print(event["sequence"], event["type"])

endpoint 可使用主机根路径或 /v1。run 支持规范所有现有参数；create_run(body, idempotency_key=...) 直接发送完整 RunCreate。 bootstrap() 读取受限运行目录；agent_runtime(agent_id, version_id=...) 读取可启动状态和模型元数据；capabilities/models 读取能力；sessions/session/messages/delete_session 管理授权历史；snapshot/cancel/add_input/approve/claim/receipt/events 沿用协议。create_session 暴露 history_mode/runtime_mode，但 unsupported 模式仍由服务器拒绝，不能据此承诺 external/ephemeral 已实现。

网络与恢复：

• SDK 不自动重试 POST，也不生成隐式新请求。httpx 连接异常意味着结果可能未知，应原样重试原 key 或查询已接受 Run；不能换 key 重启付费 Run。
• events 是单次观察订阅，按 UTF-8、CRLF、多行 data 解析，不调用工具 handler。网络断开后先 snapshot(run_id) 替换自己的投影，再 events(run_id, after=snapshot["resume_cursor"])。用事件 sequence 去重；缺口重新取快照。终态结束重连。401/403 停止恢复并重新核对权限。
• cancel(run_id) 才是明确的停止请求。停止读取 events 或 close 客户端不取消 Agent/业务任务。
• add_input 用同一幂等键重试。claim 的 replayed=true 要读取已有持久回执或由产品核对；绝不再次执行副作用。receipt_id 持久保存到确认完成。
• HostingError 提供 code、status_code、request_id、details；不要将内部异常或完整请求正文写入浏览器或日志。USD 原样保持十进制字符串。
• 恢复已有 session 保持其 agent_version；升级使用新会话。停用/归档由 D05 服务端最终拒绝，不自动换版本或提权。

构建：安装 hatchling 后从干净提交执行 python scripts/build_sdk.py；生成 dist/sdk/0.2.5/ 的 wheel、源码包、来源提交、固定契约摘要、构建工具版本与 SHA-256 清单。目录存在则拒绝覆盖。开发使用 --candidate。运行 python scripts/check_sdk_release.py <产物目录> 核对文件和包内容；加 --publish-ready 会额外拒绝许可证缺失、private 标记和未提交来源。python scripts/test_sdk_install.py <wheel 或 tar.gz> 在系统临时目录新建 venv、实际安装并调用，不依赖源码路径。离线依赖可通过 HAA_WHEELHOUSE 指定本地 wheelhouse。

0.2.2 已整合 D01/D02/D03/D04/D05，保留固定版本调用方式；新增 run(session_id, content="文本", agent_id="逻辑 Agent ID", idempotency_key=key)。agent_id 和 agent_version 必须二选一。使用逻辑 ID 时由服务端在首次接受 Run 时固定版本，已有 Session 不跟随新发布；停用后原请求仍可按原 key 核对。0.2.2 快照与事件均拒绝非 1.0 协议。旧版 0.2.0/0.2.1/0.2.2 保留，不覆盖原文件。已用本机真实 API 签发的受限测试 Key 验证运行发现、文本 Run、SSE、跨 Agent 拒绝和撤销；模型及邮件均使用 mock。D02 执行器接口可经通用 request 调用，参考 examples/README-executor.md。

0.2.3 保留上述 SDK API，增加源码包、发布检查和安装矩阵；采用包含 D07 与 durable 执行补齐的协议基线。

0.2.4 补充客户端 MIT 许可；0.2.3 及更早产物保持不变。

httpx 及传递依赖由 pip 独立安装，不打入本 wheel。第三方许可见 THIRD_PARTY_NOTICES.md。MIT 许可见 LICENSE；真实产品与付费模型运行仍需在接入方验收。

平台标准工具（0.2.5）

wait 与三个聊天历史工具由 Hosting 内部执行，需要在 Agent 的 platform_tools.enabled 显式开启并发布新版本，默认历史范围为 current_session。跨会话需发布 allowlist 并满足调用者原有权限。Snapshot 中 execution_owner="platform" 的调用仅用于展示；不要为它注册 handler、claim 或投递 receipt。platform_waiting 表示持久定时等待，platform_running 表示平台读取；等待成功不证明产品业务已经完成。

已发布 0.2.4 SDK 对这些附加字段保持兼容，服务端仍拒绝外部领取平台调用。0.2.5 聊天组件提供平台执行的中文状态；Python SDK 不自动执行工具。旧 Agent 不会因客户端升级自动启用工具。平台读取结果包含 source_ref/覆盖与分页信息；跨会话源删除会清空依赖会话的云端历史及派生摘要，产品自存副本需自行清理。