Skip to content

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安装什么
mcpMCP 代理
identitybroker 和 MCP 代理用的 JWT 校验(RS256、issuer、audience、scope)
oauthMCP 上游的逐用户 OAuth,以及加密 vault
gatewayHTTP 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_idpython-agent这个凭据所属的 Agent
cache_path.preworld-guard/policy.json校验过的策略缓存在哪里,也可以用 PREWORLD_GUARD_CACHE 设置。事件队列和审批快照放在同一个目录
timeout5 秒每次访问控制面的超时
refresh_interval60 秒用到策略时多久刷新一次
max_stale_age300 秒连不上控制面时,缓存的策略最多还能用多久。超过之后所有受保护的动作一律阻断
background_eventsFalse改由后台线程发送事件,不在调用里同步发送。调用多的 Agent 用它
max_outbox_bytes8,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 包含:

字段含义
effectallow、deny、allow_with_warning、require_approval 或 degrade
would_effect强制执行时本应得到的判定
rule_id做出判定的规则,或者 default-allow、default-deny、policy-expired
reason_codeALLOWED、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 里是判定内容
GuardApprovalRequiredGuardDenied 的子类:已经申请了票据。有 ticket_id、expires_at、status
GuardDegradeRequiredGuardDenied 的子类:命中降级规则,这条路径上没有执行替代工具
GuardSubjectRequired需审批规则命中了一次没有可信主体的调用
GuardFallbackUnavailable降级规则指定的替代工具没注册,或者在这条路径上跑不了
GuardUnavailable适配器里(preworld_guard._adapter):Guard 无法判定。它的 payload 可以安全地交给模型

无论哪种异常,工具都不能执行。

访问控制面的重试 ​

从 0.9.0 起,访问控制面遇到连接级错误时会立即再发一次,但只在不会重复副作用时才这样做:请求根本没发出去时总是重试。可能已经发出去时,只重试读取、事件上报和审批申请,这几种控制面会去重。消费票据、注册、心跳从不重复发送。所以一个请求最长可能用掉两倍的 timeout。

其他模块 ​

模块用途
preworld_guard.egressGuardedHTTPClient、GuardedAsyncHTTPClient,见 HTTP 出站
preworld_guard.gatewayHTTP broker(python -m preworld_guard.gateway --config ...)
preworld_guard.policy_dslparse_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 导入