Python SDK
包名是 preworld-guard-sdk,导入名是 preworld_guard。支持 Python 3.11 和 3.12。基础包只依赖 httpx、pydantic 和 PyYAML,框架通过 extra 安装。import preworld_guard 不会导入任何框架。
当前托管生产提供 preworld-guard-sdk==0.10.0。后续 0.11.0 将改名为 yi-guard-sdk;新名称须等实际发布并出现在私有源后使用。Python 导入名 preworld_guard 和 CLI 不变。
安装
SDK 是私有分发的,只从控制台指定的私有源安装,固定版本和哈希,不从公共 PyPI 安装。
- 托管控制面:从你们的私有 SDK 源安装,凭 SDK 下载令牌访问。用控制台给出的安装命令,它固定了 wheel 的地址和 sha256。见快速开始。
- 自部署控制面:用我们提供的 wheel 或私有源。固定版本和哈希。
| extra | 安装什么 |
|---|---|
mcp | MCP 代理 |
identity | broker 和 MCP 代理用的 JWT 校验(RS256、issuer、audience、scope) |
oauth | MCP 上游的逐用户 OAuth,以及加密 vault |
gateway | HTTP broker |
langchain、langgraph、claude、openai-agents、pydantic-ai、google-adk、agent-framework、llama-index、agno、dspy、crewai | 各对应一个框架适配器,见框架适配器 |
有几组组合不能装在一起,见不能装在一起的 extra。
GuardClient
python
GuardClient(endpoint, token, project_id, *, agent_id="python-agent", cache_path=None, timeout=5.0,
refresh_interval=60.0, max_stale_age=300.0, background_events=False, event_batch_size=50,
event_flush_interval=1.0, max_outbox_bytes=8_000_000, proxy=None, ca_bundle=None)| 参数 | 默认值 | 含义 |
|---|---|---|
endpoint | 控制面地址 | |
token | 执行器凭据(guard.env 里的 PREWORLD_GUARD_TOKEN) | |
project_id | 项目 | |
agent_id | python-agent | 这个凭据所属的 Agent |
cache_path | .preworld-guard/policy.json | 校验过的策略缓存在哪里,也可以用 PREWORLD_GUARD_CACHE 设置。事件队列和审批快照放在同一个目录 |
timeout | 5 秒 | 每次访问控制面的超时 |
refresh_interval | 60 秒 | 用到策略时多久刷新一次 |
max_stale_age | 300 秒 | 连不上控制面时,缓存的策略最多还能用多久。超过之后所有受保护的动作一律阻断 |
background_events | False | 改由后台线程发送事件,不在调用里同步发送。调用多的 Agent 用它 |
max_outbox_bytes | 8,000,000 | 本地事件队列的大小。满了之后新的动作会被阻断 |
proxy、ca_bundle | 访问控制面用的 HTTP(S) 代理和 CA 证书包;也可以用 PREWORLD_GUARD_PROXY 和 PREWORLD_GUARD_CA_BUNDLE |
SDK 不读 HTTPS_PROXY 和 SSL_CERT_FILE。代理和 CA 设置只作用于访问控制面的流量:策略、心跳、事件、审批、connection-check、trial-check、siem-export 和 onboard。受控 HTTP、broker、MCP 上游、OAuth 和 JWKS 的流量从不走这个代理,否则会绕过地址检查。
生命周期
| 方法 | 做什么 |
|---|---|
start(*, name="python-sdk", version=..., heartbeat_interval=15.0) | 注册执行器,把 Agent 登记为资产,发一次心跳,然后在后台线程里每 15 秒同步策略并发心跳。返回客户端本身 |
lifecycle_status | 执行器 ID、状态、最近的错误、已加载的策略版本和摘要,以及策略来自控制面还是缓存 |
close() | 发最后一次 stopped 心跳,停掉后台线程,能发的话把排队的事件发出去。程序退出时调用 |
保护调用
| 方法 | 做什么 |
|---|---|
@guard.tool(resource=None, *, action_type="tool.call", pending=False) | 包装同步或异步函数。每次调用前判定,记录 started 和 completed,遇到降级规则时执行注册的替代工具。pending=True 保存参数快照,用于审批后恢复执行 |
authorize(resource, arguments=None, *, action_type="tool.call", destination=None, data_labels=(), subject_id=None, ...) | 判定一个动作,返回 (action, decision),或者抛出异常。副作用由你们自己执行时用它 |
register_fallback(resource, function, *, map_arguments) | 注册降级规则指定的替代工具。运行中不能替换 |
approval_status(ticket_id)、cancel_approval(ticket_id) | 查询或撤回本执行器申请的审批票据 |
pending.status(ticket_id)、pending.resume(ticket_id)、pending.resume_async(ticket_id)、pending.cancel(ticket_id)、pending.list() | 标了 pending=True 的工具的审批快照 |
上下文
| 函数 | 做什么 |
|---|---|
guard_run(*, session_id=None, subject_id=None, run_id=None, trace_id=None) | 上下文管理器。为其中的每次 Guard 调用设置可信主体和关联 ID。主体必须来自你们的应用,不能来自模型 |
guard_approval(ticket_id) | 上下文管理器。下一次匹配的调用消费这张已批准的票据,之后再用都会失败 |
guard_resume(*ticket_ids) | 给适配器用的上下文管理器。同一个动作再次提出时消费已批准的票据,其他调用照常判定 |
current_run() | 当前生效的 guard_run 上下文(如果有) |
判定结果
GuardDenied.decision 和 authorize 返回的 decision 包含:
| 字段 | 含义 |
|---|---|
effect | allow、deny、allow_with_warning、require_approval 或 degrade |
would_effect | 强制执行时本应得到的判定 |
rule_id | 做出判定的规则,或者 default-allow、default-deny、policy-expired |
reason_code | ALLOWED、RULE_DENIED、DEFAULT_DENY、APPROVAL_REQUIRED、DEGRADED、POLICY_EXPIRED、SUBJECT_REQUIRED、APPROVED…… |
message | 规则里的说明 |
policy_version、policy_hash | 做出判定的策略 |
fallback_resource | 降级时的替代工具 |
异常
| 异常 | 什么时候抛出 |
|---|---|
GuardError | 基类。没有有效策略、缓存的策略超过 max_stale_age 时也抛它 |
GuardTransportError | 连不上控制面。校验过的缓存可能还能用 |
GuardRequestRejected | 控制面以 401/403 以外的 4xx 拒绝了请求,status_code 说明是哪个 |
GuardAuthError | 凭据无效。不会退回去用缓存;换新凭据并新建客户端 |
GuardDenied | 判定是拒绝,decision 里是判定内容 |
GuardApprovalRequired | GuardDenied 的子类:已经申请了票据。有 ticket_id、expires_at、status |
GuardDegradeRequired | GuardDenied 的子类:命中降级规则,这条路径上没有执行替代工具 |
GuardSubjectRequired | 需审批规则命中了一次没有可信主体的调用 |
GuardFallbackUnavailable | 降级规则指定的替代工具没注册,或者在这条路径上跑不了 |
GuardUnavailable | 适配器里(preworld_guard._adapter):Guard 无法判定。它的 payload 可以安全地交给模型 |
无论哪种异常,工具都不能执行。
访问控制面的重试
从 0.9.0 起,访问控制面遇到连接级错误时会立即再发一次,但只在不会重复副作用时才这样做:请求根本没发出去时总是重试。可能已经发出去时,只重试读取、事件上报和审批申请,这几种控制面会去重。消费票据、注册、心跳从不重复发送。所以一个请求最长可能用掉两倍的 timeout。
其他模块
| 模块 | 用途 |
|---|---|
preworld_guard.egress | GuardedHTTPClient、GuardedAsyncHTTPClient,见 HTTP 出站 |
preworld_guard.gateway | HTTP broker(python -m preworld_guard.gateway --config ...) |
preworld_guard.policy_dsl | parse_policy_document、load_policy_yaml、compile_policy、policy_json_schema |
preworld_guard.langgraph、.pydantic_ai、.google_adk、.agent_framework、.llama_index、.agno、.dspy、.crewai | 框架适配器。GuardMiddleware、GuardHooks 和 protect_function_tool 可以直接从 preworld_guard 导入 |