Python SDK 使用指南

envloop.Client 是同步客户端。远程模式只需安装 envloop；本地执行需额外安装 EnvPlatform。安装步骤见 Quickstart。

Connect to the platform

from envloop import Client

with Client.remote() as client:
    print(client.jobs.list(limit=10))

读取 ENVLOOP_BASE_URL、ENVLOOP_API_KEY 及可选 ENVLOOP_WORKSPACE_ID；SDK 不自动读取 .env.local。也可显式传入地址和 workspace，Key 仍从环境读取：

with Client.remote("https://api.envloop.ai", timeout=30) as client:
    print(client.jobs.list(limit=10))

这里 timeout 是 HTTP 请求期限，不是任务执行期限或 wait 的总期限。Client() 不会自动连接平台；必须传入调用方管理的 server，或使用工厂方法。

Run locally without a platform account

在 envloop 仓库目录安装可选后端（已有 checkout 时复用，不覆盖）：

git clone https://github.com/EnvLoop/EnvPlatform.git ../EnvPlatform
uv pip install --python .venv/bin/python -e ../EnvPlatform

准备 Quickstart 的两文件 ./my-task，将以下保存为 local_demo.py 并运行 uv run --no-sync python local_demo.py：

from envloop import Client

with Client.local(work_dir="./runs") as client:
    trial = client.tasks.submit("./my-task")
    final = client.tasks.wait(trial["trial_id"], timeout=30)
    assert final["status"] == "succeeded", final
    result = client.tasks.result(trial["trial_id"])
    assert result["stdout"] == "hello\n", result
    assert result["outputs"][0]["content"] == "hello\n", result
    print(result)

本地运行直接执行可信脚本。关闭 context 会等待已接受任务结束，但不删除输出或日志。没有 repository 绑定时，跨客户端无法找回内存中的历史 Trial。

Wait and inspect failures

with Client.remote() as client:
    trial = client.tasks.submit("./my-task")
    trial_id = trial["trial_id"]
    try:
        final = client.tasks.wait(trial_id, timeout=60)
    except TimeoutError:
        print(client.tasks.status(trial_id))  # 任务仍可能在运行
    else:
        print(final["status"])
        print(client.tasks.result(trial_id))

脚本非零退出时 wait 返回 failed，不会因为任务失败自动抛异常。目录读取、输入校验、HTTP 和权限错误可能抛异常；不要记录原始请求、密钥或任意服务端错误正文。

接口签名见 Python SDK reference。