AgentKit智能体沙箱环境配置实现安全运行

AgentKit沙箱通过工具白名单、网络DNS/IP过滤和文件路径挂载限制三重拦截机制，实现逻辑执行围栏；默认禁用，需在agent.yaml中设sandbox: true并配置sandbox-policy.yaml策略文件，支持CLI、代码声明及环境变量三种启用方式。

在生产环境中让智能体调用内部API、操作数据库或访问第三方服务时，必须确保其行为受控、不可越权、无法逃逸执行边界——AgentKit智能体沙箱环境正是为解决这一核心安全诉求而设。

理解沙箱的运行边界

AgentKit沙箱不是虚拟机或容器隔离层，而是基于Runtime策略引擎构建的逻辑执行围栏。它通过三重拦截机制生效：工具调用白名单校验、HTTP外发请求DNS/IP级过滤、文件系统路径挂载限制。若跳过此步直接部署agent，

。

沙箱启用与否由agent.yaml中sandbox字段控制，默认为false；设为true后，Runtime会自动加载预置的安全策略集。

配置沙箱策略文件

在项目根目录创建sandbox-policy.yaml，内容需严格遵循YAML语法：

工具：
允许的：["http_get", "json_parse", "datetime_now"]
禁止的：["exec_command", "write_file", "read_file"]
网络：
允许的域名：["api.example.com", "data.internal"]
禁止的IP：["192.168.0.0/16", "10.0.0.0/8"]
文件系统：
只读路径：["/tmp/", "/var/lib/agentkit/"]

注意：deny_ips字段不支持通配符，必须使用CIDR格式；若填写192.168.*.*将导致策略加载失败并中断启动流程。

绑定沙箱到Agent实例

方法一：CLI方式部署时启用

执行agentkit deploy --sandbox --policy ./sandbox-policy.yaml --agent ./my_agent.py

方法二：代码内显式声明（适用于本地调试）

在agent.py入口处添加：

import SandboxConfig from agentkit.runtime
config = SandboxConfig(policy_path="./sandbox-policy.yaml")
agent.run(sandbox=config)

方法三：环境变量全局开关（仅限开发测试）

export AGENTKIT_SANDBOX=true
export AGENTKIT_SANDBOX_POLICY=./sandbox-policy.yaml

验证沙箱是否生效

第一步：启动带日志的沙箱实例

agentkit serve --sandbox --log-level debug

第二步：向/sandbox/status端点发送GET请求

curl http://localhost:8000/sandbox/status

第三步：检查返回JSON中的enabled字段是否为true，且policy_hash值非空字符串

第四步：触发一个被禁止的工具调用（如exec_command），观察响应是否返回403 Forbidden及reason字段包含"tool_blocked_by_sandbox"