# 配置工具授权 (/docs/developers/agent/embed/tool-authorization)





为已启用的工具选择直接执行或每次询问，让用户在操作发生前确认意图。本页以订单 MCP 的查询和退货工具为例；业务权限仍须由工具服务端校验。

## 准备工具 [#prepare]

准备一个已能接入的服务智能体，并在「配置 → MCP 与凭据」连接名为 `orders` 的 MCP 服务器。示例要求它提供已启用的 `list_orders` 和 `request_return`。替换为你实际的服务器和工具名称，不要用示例名称配置不存在的工具。

确认卡不能代替身份认证。公网 MCP 服务必须先认证平台调用方，再按终端用户限定数据范围，见[保护嵌入接入](/docs/developers/agent/embed/security#tool-access)。

## 选择执行策略 [#policies]

| 策略             | 对普通已启用工具的效果               |
| -------------- | ------------------------- |
| `always_allow` | 不询问，直接执行                  |
| `always_ask`   | 暂停并等待用户确认，允许后执行；拒绝则不执行该调用 |

目前支持这两档。不要使用 `auto`：即使某处类型接受它，运行时也会拒绝执行。需要禁止使用一个工具时，关闭该工具；「每次询问」仍允许用户同意调用。

策略不绕过工具自身的强制交互、安全边界或业务检查。前端 `custom` 工具由你的页面执行，不经过这套确认策略。

## 设置工具与默认值 [#configure]

<Tabs items="['控制台', 'API']">
  <Tab value="控制台">
    在当前控制台依次打开「服务智能体 → 你的智能体 → 接入与配置 → 配置 → 工具与授权」。

    1. 在「授权方式」找到 `orders · 默认授权`，选择「每次询问」。
    2. 将 `list_orders` 设为「自动执行」，`request_return` 设为「每次询问」。逐工具选择项只显示已配置的工具；未显示的工具可使用默认策略，或通过 API 添加逐工具配置。
    3. 保存配置。&#x2A;*预期：** 当前配置版本增加；原有会话继续使用原版本。
  </Tab>

  <Tab value="API">
    替换 `agent_example`，把代码保存为 `authorize-tools.ts`，在已设置 `PRAXIS_API_KEY` 的宿主服务端运行 `bun authorize-tools.ts`。示例读取并保留其他工具和设置，仅修改订单工具授权。`version` 用于检测并发修改。

    ```ts
    // authorize-tools.ts — run on the server with: bun authorize-tools.ts
    const key = process.env.PRAXIS_API_KEY;
    if (!key) throw new Error("Set PRAXIS_API_KEY on the server");
    const url = "https://api-develop.deepraxis.com/agent/v1/agents/agent_example";
    const headers = { Authorization: `Bearer ${key}`, "Content-Type": "application/json" };
    const read = await fetch(url, { headers });
    if (!read.ok) throw new Error(`Read failed: ${read.status}`);
    const current = await read.json();
    const tools = current.tools ?? [];
    const orders = tools.find((tool: { type: string; mcp_server_name?: string }) =>
      tool.type === "mcp_toolset" && tool.mcp_server_name === "orders");
    if (!orders) throw new Error("Connect the orders MCP server first");
    orders.default_config = {
      ...orders.default_config,
      permission_policy: { type: "always_ask" },
    };
    orders.configs = orders.configs ?? [];
    for (const [name, type] of [
      ["list_orders", "always_allow"],
      ["request_return", "always_ask"],
    ]) {
      const existing = orders.configs.find((item: { name: string }) => item.name === name);
      if (existing) existing.permission_policy = { type };
      else orders.configs.push({ name, permission_policy: { type } });
    }
    const response = await fetch(url, {
      method: "POST", headers,
      body: JSON.stringify({ version: current.version, tools }),
    });
    if (!response.ok) throw new Error(`Update failed: ${response.status}`);
    const saved = await response.json();
    console.log({ id: saved.id, version: saved.version });
    ```

    **预期：** 更新返回 HTTP 200，终端显示新版本。若读取或更新失败，脚本停止；先处理报错，再重新读取版本，不要盲目重发旧配置。
  </Tab>
</Tabs>

解析顺序为单工具 `configs[].permission_policy` → 工具集 `default_config.permission_policy` → 工具默认策略。未设置 MCP 策略时，服务器声明 `annotations.readOnlyHint === true` 才默认放行，否则默认询问。该提示仅影响缺省，显式配置优先。

内置工具集未设置默认策略时为 `always_allow`，但工具自身要求的交互仍然存在。对退款、删除和对外发送等动作，明确设置询问，不要仅依赖服务器提示。

## 验证确认过程 [#verify]

签发使用新版本的嵌入令牌并新建会话；若嵌入策略固定版本，先更新固定版本或在签发时指定新版本。保存智能体不会自动升级已有会话。

先让智能体调用查询工具，再请求一次测试退货。&#x2A;*预期：** 查询直接返回；退货显示 Kit 确认卡。拒绝后工具服务端不应执行退货；再次提出请求并允许后才执行。以工具服务端记录核实调用是否发生，不要只看智能体的回答。

Kit 自带确认卡，无须另写界面。嵌入用户的允许只针对这次调用，不会保存为永久工具权限。完整测试情境见[测试嵌入接入](/docs/developers/agent/embed/testing)。

## 下一步 [#next]

[保护工具服务](/docs/developers/agent/embed/security#tool-access) · [前端工具](/docs/developers/agent/embed/client-tools) · [更新智能体 API](/docs/api/native/agent/updateAgent)。