Metadata-Version: 2.4
Name: hostanagent-client
Version: 0.2.4
Summary: Thin async client for the HostAnAgent public protocol
Project-URL: Repository, https://github.com/ffskyfan/HostAnAgentBackend
Project-URL: Documentation, https://pypi.org/project/hostanagent-client/
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.28
Description-Content-Type: text/markdown

# hostanagent-client 0.2.4

用于产品后端的独立异步 SDK，Python >=3.10，仅依赖 httpx；不安装 HostAnAgent 服务、Worker 或 aisuite。协议兼容 1.0。0.2.4 为 MIT 许可准备版本，提供 wheel 和源码包，尚未公开发布到 PyPI。本 SDK 及随包文档采用 [MIT](https://opensource.org/license/mit)，版权归 GeekArt Inc.；这项授权覆盖 SDK 目录，服务端另行管理。正式发布后，本 README 会随 PyPI 项目页公开；当前元数据中的 PyPI 文档地址尚未上线。

```bash
python -m pip install ./hostanagent_client-0.2.4-py3-none-any.whl
```

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

```python
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.4/` 的 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；公开发布和真实产品/生产联合验收另行安排。
