Python SDK

hostanagent-client==0.2.5 是产品服务端的异步 SDK，Python 3.10+，使用 httpx。先在 API Keys 页面创建目标 Agent 的受限 Key；模型供应商凭证由平台持有。

python -m pip install hostanagent-client==0.2.5

下面的函数由产品已验证的请求处理器调用。trusted_product_user_id 必须来自产品登录态；示例请求可能产生模型费用，只有账户有余额且 Agent 已发布时才调用。

import os
from hostanagent import AgentClient, HostingError, idempotency_key

async def chat(trusted_product_user_id: str, session_id: str):
    async with AgentClient(
        "https://api.hostanagent.com/v1",
        os.environ["HAA_APPLICATION_KEY"],
        subject=trusted_product_user_id,
    ) as client:
        key = idempotency_key()
        # 产品须保存原请求正文、参数和 key；未知结果时原样核对或重试。
        try:
            accepted = await client.run(
                session_id,
                os.environ["HAA_AGENT_VERSION"],
                "整理我的任务",
                idempotency_key=key,
            )
        except HostingError as error:
            if error.code == "INSUFFICIENT_BALANCE":
                # 异步事件流只能直接结束；产品可以在外层把此错误映射为充值提示。
                return
            raise
        async for event in client.events(accepted["run_id"]):
            yield event

要先做独立服务端冒烟检查，可把下面内容保存为 smoke.py，在测试服务端设置 HAA_APPLICATION_KEY、HAA_AGENT_VERSION 和由该产品确认的 HAA_TEST_SUBJECT，然后运行 python smoke.py。这段不接收浏览器自报 Subject；它会创建一个新 Session，并在余额充足时发起真实、可能计费的模型 Run。

import asyncio
import os
from hostanagent import AgentClient, HostingError, idempotency_key

async def main():
    async with AgentClient(
        "https://api.hostanagent.com/v1",
        os.environ["HAA_APPLICATION_KEY"],
        subject=os.environ["HAA_TEST_SUBJECT"],
    ) as client:
        session = await client.create_session()
        print("session_id", session["id"])
        try:
            run = await client.run(
                session["id"], os.environ["HAA_AGENT_VERSION"], "你好",
                idempotency_key=idempotency_key(),
            )
            print("run_id", run["run_id"])
            async for event in client.events(run["run_id"]):
                print(event["sequence"], event["type"])
        except HostingError as error:
            print(error.status_code, error.code, error.request_id)

asyncio.run(main())

预期：无余额时输出 402 INSUFFICIENT_BALANCE 且不请求模型；余额足够时先输出 Session/Run ID，再收到有序事件。网络或进程在 POST 响应前中断时，该演示脚本不会自动安全恢复：正式产品须事先持久化请求参数和幂等键，并用原键核对，不能简单重跑脚本生成新键。

先通过 await client.bootstrap() 读取运行发现，或 await client.create_session() 创建 managed + durable 会话，保存其 ID 后调用上面的函数。SDK 还提供模型目录、运行元数据、会话/消息、Run 快照、取消、追加输入、审批、claim/receipt 和事件订阅。Agent 的 history_mode / runtime_mode 枚举不意味着未开放模式可用；服务器只接受当前支持的组合。

网络断开时 events() 停止观察，不取消 Run。先读取 snapshot(run_id)，再从 resume_cursor 订阅后续事件；POST 响应未知时保存并重用原幂等键和完整参数，不换键新建付费 Run。HostingError 含状态码、稳定 code 和 request ID。运行 API、恢复指南。

如需收紧本轮输入窗口，可给 run 传 limits={"max_context_tokens": 128000}，且不能超过 Agent 发布配置。0.2.5 会按传入字典发送，无需为本次服务升级更换 SDK；但须从自己的模板中删除 max_context_chars、max_result_bytes、max_result_tokens。工具结果预算 max_result_context_bytes 配置在工具集，默认 16 KiB、最高 32 KiB，不是 run 参数。配置与迁移及版本边界。