启用工具权限 HITL

当你需要控制 agent 能调用哪些工具，并对敏感操作启用人工审批时，使用本页。

前置条件

• 已有可运行的 awaken runtime
• awaken 启用了 permission

[dependencies]
awaken = { package = "awaken-agent", version = "0.1", features = ["permission"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"

步骤

1. 注册 permission 插件：

use std::sync::Arc;
use awaken::engine::GenaiExecutor;
use awaken::ext_permission::PermissionPlugin;
use awaken::registry_spec::{AgentSpec, ModelSpec};
use awaken::{AgentRuntimeBuilder, Plugin};

let agent_spec = AgentSpec::new("my-agent")
    .with_model("gpt-4o-mini")
    .with_system_prompt("You are a helpful assistant.")
    .with_hook_filter("permission");

let runtime = AgentRuntimeBuilder::new()
    .with_provider("openai", Arc::new(GenaiExecutor::new()))
    .with_model(
        "gpt-4o-mini",
        ModelSpec {
            id: "gpt-4o-mini".into(),
            provider: "openai".into(),
            model: "gpt-4o-mini".into(),
        },
    )
    .with_agent_spec(agent_spec)
    .with_plugin("permission", Arc::new(PermissionPlugin) as Arc<dyn Plugin>)
    .build()
    .expect("failed to build runtime");

2. 以内联方式定义规则：

use awaken::ext_permission::{PermissionRulesConfig, PermissionRuleEntry, ToolPermissionBehavior};

let config = PermissionRulesConfig {
    default_behavior: ToolPermissionBehavior::Ask,
    rules: vec![
        PermissionRuleEntry {
            tool: "read_file".into(),
            behavior: ToolPermissionBehavior::Allow,
            scope: Default::default(),
        },
        PermissionRuleEntry {
            tool: "file_*".into(),
            behavior: ToolPermissionBehavior::Ask,
            scope: Default::default(),
        },
        PermissionRuleEntry {
            tool: "delete_*".into(),
            behavior: ToolPermissionBehavior::Deny,
            scope: Default::default(),
        },
    ],
};

3. 也可以从 YAML 文件加载：

default_behavior: ask
rules:
  - tool: "read_file"
    behavior: allow
  - tool: "Bash(npm *)"
    behavior: allow
  - tool: "file_*"
    behavior: ask
  - tool: "delete_*"
    behavior: deny

4. 通过 agent spec 激活：

let agent_spec = AgentSpec::new("my-agent")
    .with_model("gpt-4o-mini")
    .with_system_prompt("You are a helpful assistant.")
    .with_hook_filter("permission");

5. 理解规则优先级：

6. Deny

7. Allow

8. Ask

匹配 DSL 支持：

验证

1. 用一个命中 deny 的工具测试，调用应被拦截
2. 用一个命中 ask 的工具测试，run 应进入等待审批状态
3. 通过 mailbox 接口提交审批
4. 确认 run 恢复执行

常见错误

相关示例

• crates/awaken-ext-permission/tests/

关键文件

• crates/awaken-ext-permission/src/lib.rs
• crates/awaken-ext-permission/src/config.rs
• crates/awaken-ext-permission/src/rules.rs
• crates/awaken-ext-permission/src/plugin/plugin.rs
• crates/awaken-ext-permission/src/plugin/checker.rs
• crates/awaken-tool-pattern/

相关

• 添加 Plugin
• HITL 与 Mailbox
• Tool Trait