Skip to content

快速开始:托管控制面 ​

适用范围:当前托管生产使用组织工作区。个人工作区及其所有者自审需等待控制面升级;自部署实例请按实际版本与身份配置判断。

用托管控制面时,控制面由我们运行。Agent 和 Guard SDK 跑在你们自己的环境里,每次工具调用都在那里、在执行之前判定。大多数团队走这条路。想自己部署控制面,看快速开始:自部署。

需要准备:

  • 已经和我们开通好。我们会给你们控制台地址和私有 SDK 源地址,例子里用 https://guard.example.com 和 https://sdk.guard.example.com 代替。
  • 一个当前部署接受的登录账号,具体登录方式以控制台为准。
  • 一个 Agent:Python 3.11 或 3.12,或者 TypeScript(Node.js 22.12 及以上,用 Vercel AI SDK)。
  • 另一个能审核策略的人。策略的作者不能批准自己的策略。

1. 登录 ​

打开控制台,点「用 Yi Labs 账号登录」。组织的所有者第一次登录时,Guard 自动开通这个组织的空间和一个叫 Guard 的项目,这个人就是项目所有者。如果空间是我们提前开好的,用我们登记的邮箱登录,并在 7 天内确认认领。

同事先在配置的组织身份提供方里加入组织,再用自己的账号登录 Guard。除了所有者,其他人第一次进来都是只读成员。所有者在「成员」页按项目分配角色,也可以按邮箱提前分配。见控制台与角色。

会话固定 15 分钟,不会延长。没保存的策略修改留在当前标签页里。

2. 签发 SDK 下载令牌 ​

SDK 不在公共的 PyPI 和 npm 上,只能从你们的私有 SDK 源安装,访问私有源要用 SDK 下载令牌。

  1. 所有者打开「接入」,点「签发 SDK 下载令牌」,选有效期(1 到 365 天)。
  2. 复制令牌。它只显示一次。这个令牌只能下载 SDK,调不了控制面的任何接口。
  3. 在执行安装命令的那台机器上,把控制台给出的那一行写进 ~/.netrc,并把文件权限设成只有自己可读(chmod 600 ~/.netrc):
machine sdk.guard.example.com login token password <SDK 下载令牌>

在 CI 里,把令牌放进 CI 的密钥,构建时写一个临时的 netrc 文件,用 NETRC 环境变量指向它。不要把令牌写进 requirements 文件或 Git。不用的令牌及时撤销。

不要从公共源安装

当前生产安装 Python preworld-guard-sdk==0.10.0 或 npm @preworld/guard@0.2.0。只用控制台给出的私有源安装命令,它固定了文件地址和哈希。

3. 新建接入 ​

一条接入对应一个 Agent。还是在「接入」页,所有者填接入名称、Agent ID 和框架,点「生成并下载接入包」。能选的框架见框架适配器,另外还有 MCP 代理和 Vercel AI SDK。

接入包 guard-connection.zip 里有:

文件是什么
guard.envPREWORLD_GUARD_ENDPOINT、PREWORLD_GUARD_PROJECT_ID、PREWORLD_GUARD_AGENT_ID 和 PREWORLD_GUARD_TOKEN,最后一个是这个 Agent 专用的执行器凭据。只发这一次,放进你们的密钥目录。
guard-connection.json这条接入的配置,检查接入时读它。
guard_integration.py按所选框架生成的接入示例。TypeScript 是 guard-integration.ts 加 .npmrc.example;MCP 代理是 guard-mcp.template.json。
guard-policy.json下载那一刻的策略快照。
guard-inventory.json把这个 Agent 登记成资产用的文件。
README.txt这条接入的安装命令和检查命令。

执行器凭据默认 90 天有效。怀疑泄露时,点「轮换并下载接入包」或「撤销接入」。撤销之后,Agent 下一次联系控制面就会被拒绝。

4. 安装 SDK ​

运行控制台或 README.txt 里给出的安装命令。命令里写明了 wheel 的地址和 sha256,下载到的文件只要字节不一致就装不上。例如:

sh
python -m pip install 'preworld-guard-sdk[langchain] @ https://sdk.guard.example.com/packages/preworld_guard_sdk-0.10.0-py3-none-any.whl#sha256=…'

方括号里是框架的 extra(langchain、langgraph、claude、openai-agents、pydantic-ai、google-adk、agent-framework、llama-index、agno、dspy、crewai、mcp)。有几组 extra 不能装在一起,见框架适配器。

用 uv 的项目,把私有源的 /simple/ 地址配成 explicit 索引,再用 [tool.uv.sources] 指定 preworld-guard-sdk 只从这个索引取。

TypeScript 见 TypeScript SDK,npm 用的是同一个 SDK 下载令牌。

5. 把 Guard 接到工具前面 ​

照着 guard_integration.py 改。普通的 Python 工具是这样:

python
from preworld_guard import GuardClient, GuardDenied

guard = GuardClient(
    endpoint="https://guard.example.com",
    token="pwg_...",
    project_id="prj_...",
    agent_id="support-agent",
)
guard.start(name="support-agent")

@guard.tool("search_customer")
def search_customer(customer_id: str):
    return database.search(customer_id)

try:
    search_customer("customer-42")
except GuardDenied as error:
    print(error.decision.reason_code, error.decision.message)

实际代码里,这四个值从 guard.env 设置的环境变量读,不要写在源码里。guard.start() 注册执行器,每 15 秒发一次心跳,并拉取新的策略版本。LangChain、OpenAI Agents 等框架的写法见框架适配器。每个有副作用的工具都要包上。

Agent 替某个已登录用户做事时,把这个用户作为可信主体传进来:with guard_run(subject_id=user_id): ...。审批规则需要它,规则也可以拿参数和它比较。

同一台机器上跑多个 Agent

SDK 0.8.0 及更早的版本里,从同一个目录启动的多个 Agent 共用一个事件队列,其中一个 Agent 可能因此被阻断。给每个 Agent 设各自的 PREWORLD_GUARD_CACHE,或者用 SDK 0.9.0 及以上,这个问题已经修好。

6. 检查接入 ​

加载 guard.env 里的变量,然后运行:

sh
preworld-guard connection-check --config guard-connection.json

TypeScript 项目在装了 @preworld/guard 的目录里运行:

sh
npx --no preworld-guard connection-check --config guard-connection.json

检查不执行任何业务工具,报告四项,和控制台「检查接入」显示的一样:

  • 凭据有效
  • 执行器在线
  • 当前策略已加载
  • 首条事件已收到

Agent 做过一次受保护的调用之后,才会有首条事件。哪一项没通过,见常见问题。

7. 先观察 ​

新项目默认是只观察模式。动作照常执行,Guard 只记录本来会怎样判定。让 Agent 正常干一段时间活,再看事件:它调了哪些工具、带哪些参数名、替哪些用户做事。

8. 起草、预演、审核、发布 ​

心里有数之后:

  1. 起草:在「策略工作流」点「从观察生成候选」,根据成功执行过的动作生成一份最小权限的放行清单。也可以直接在「策略」页改 DSL,在那里还能写拒绝、需审批和降级规则。见策略。
  2. 预演:点「预演」,看带行号的语法错误、和当前策略的差异、近期动作在新策略下会怎样判定,以及提醒(比如强制执行模式却没有一条放行规则)。然后点「保存为候选」。
  3. 审核:点「提交独立审核」,由另一个有审核员角色的人批准或驳回。
  4. 发布:所有者或管理员点「准备发布」,核对模式、版本和变化,再发布。发布的内容必须和审核时完全一致。

执行器在下一次心跳时加载新版本,所以大约 15 秒内生效。要撤回就发布一个回滚版本。完整流程见发布策略。

接下来 ​