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

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

理解沙箱的运行边界

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

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

配置沙箱策略文件

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

tools:

allowed: ["http_get", "json_parse", "datetime_now"]

denied: ["exec_command", "write_file", "read_file"]

network:

allow_domains: ["api.example.com", "data.internal"]

deny_ips: ["192.168.0.0/16", "10.0.0.0/8"]

filesystem:

read_only_paths: ["/tmp/", "/var/lib/agentkit/"]

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

绑定沙箱到Agent实例

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

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

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

在agent.py入口处添加：

from agentkit.runtime import SandboxConfig

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"