Beige：基于沙盒与代码生成范式，重塑AI Agent工具调用效率与安全

1. 项目概述：一个让AI真正“动手”的沙盒系统

如果你和我一样，在AI Agent这个领域折腾过一阵子，肯定对“工具调用”这个环节又爱又恨。爱的是，它让大语言模型（LLM）从“嘴炮王者”变成了能真正干点实事的“准程序员”；恨的是，这过程实在太磨叽了。想象一下，你让一个Agent去数据库里查20个用户的信息，它得跟LLM来回沟通20次：“帮我查用户1”、“好的，这是用户1”、“再帮我查用户2”…… 每次调用都要消耗token，产生延迟，而且整个链条脆弱不堪，中间任何一步出错都可能让任务卡住。这感觉就像指挥一个手脚被捆住的天才，它脑子转得飞快，但每次只能动一根手指头。

今天要聊的这个项目——Beige，就是冲着解决这个核心痛点来的。它不是一个简单的Agent框架，而是一个安全的、开源的、沙盒化的Agent系统。它的核心理念非常激进：与其让LLM笨拙地、一次一次地调用工具，不如直接给Agent一个安全的“工作台”，让它把想干的事写成一段完整的代码（比如TypeScript脚本），然后一次性执行。所有的工具调用、数据处理都在这个沙盒里完成，最后只把最终结果返回给LLM。这样一来，LLM从一个“微观管理者”变成了一个“战略规划师”，它只需要构思好蓝图，然后把具体的砌砖、刷墙的活儿交给一段它自己写的、可执行的代码。

我第一次看到这个设计时，有种豁然开朗的感觉。这不就是我们做自动化脚本时的思路吗？把重复、琐碎的逻辑封装起来，用一个入口解决所有问题。Beige把这种“写代码然后执行”的能力，安全地赋予了AI Agent。它通过一个网关（Gateway）来协调一切：管理LLM的调用，强制执行安全策略，审计记录每一次工具调用，并将执行路由到正确的目的地。而所有代码的实际运行，都被严格限制在Docker容器这个坚不可摧的沙盒里。这意味着，Agent可以尽情地“写代码”，但它的代码永远无法触及你的宿主机文件系统、网络或其他敏感资源。这种“给予自由，但划定绝对边界”的设计哲学，是构建可信赖、可投入生产的AI系统的基石。

2. 核心设计理念：从“调用者”到“创造者”的范式转变

2.1 传统工具调用模式的瓶颈

在深入Beige之前，我们必须先认清当前主流AI Agent框架的工作模式。无论是基于OpenAI的Function Calling，还是Anthropic的Tool Use，其本质都是一个请求-响应循环。

1. 用户/系统提出请求：例如，“获取最近20个活跃用户的信息”。
2. LLM规划单步动作：LLM分析请求，决定第一步调用哪个工具（比如query_database），并生成符合工具定义的参数。
3. 系统执行工具：框架执行该工具，获取结果（例如，第一条用户记录）。
4. 结果返回LLM：将工具执行结果作为上下文，再次喂给LLM。
5. LLM规划下一步：LLM根据上一步的结果，决定是继续调用工具（获取下一条记录）还是合成最终答案。
6. 循环直至完成：重复步骤2-5，直到任务完成。

这个模式的问题显而易见：

• 效率低下：每个工具调用都是一次完整的LLM交互，产生双倍的延迟（请求+响应）和token消耗。对于需要循环或复杂条件判断的任务，开销呈线性甚至指数级增长。
• 上下文负担重：LLM需要记住之前所有步骤的结果，并基于此规划下一步。随着步骤增多，上下文窗口压力巨大，可能导致遗忘或规划错误。
• 脆弱性高：任何一次工具调用的失败（网络超时、参数错误、权限问题）都可能中断整个任务链，且难以从中断点恢复。
• 缺乏真正的“自动化”：Agent无法进行真正的编程逻辑，如for循环、if-else分支、错误处理（try-catch）、变量存储和中间计算。它只是在机械地执行LLM规划的单个指令序列。

2.2 Beige的“写后执行”范式

Beige彻底颠覆了这个循环。它将Agent的角色从“工具调用者”提升为“脚本创造者”。其工作流程可以概括为“思考-编码-执行-报告”。

1. 思考与规划：LLM接收到任务后，进行整体性思考。它不再规划单个工具调用，而是规划如何用代码解决问题。
2. 生成可执行脚本：LLM生成一段完整的、符合语法的代码（默认是TypeScript，运行在Deno环境中）。这段代码包含了所有必要的工具调用、逻辑控制、数据处理和错误处理。
3. 提交脚本至网关：Agent将写好的脚本提交给Beige网关。
4. 网关调度与沙盒执行：网关接收到脚本后，启动或复用一个新的Docker沙盒容器，将脚本文件和安全地注入到容器内的/workspace目录。然后，在容器内执行这个脚本（例如，运行deno run script.ts）。
5. 安全工具调用：当脚本在沙盒内运行并调用工具时（例如，调用/tools/bin/kv get），这些调用并不会直接访问外部资源。相反，它们通过容器内预配置的Unix Domain Socket或HTTP通道，被路由回网关。
6. 网关仲裁与执行：网关接收到来自沙盒的工具调用请求。此时，网关扮演着“守门人”和“执行官”的双重角色：
   • 策略检查：根据预先配置的策略（Policy），检查当前Agent是否有权限执行此工具，参数是否合规。
   • 秘密管理：工具执行可能需要API密钥、数据库密码等秘密信息。这些秘密永远只存在于网关侧，通过环境变量或安全存储管理，绝不会传递给沙盒内的脚本。
   • 审计日志：无论调用是否被允许，网关都会记录下这次工具调用的所有元数据：谁（哪个Agent）、何时、调用什么工具、参数是什么、结果如何。
   • 实际执行：检查通过后，网关在宿主环境（或另一个有权限的环境）中实际执行该工具，并将结果返回给沙盒内的脚本。
7. 脚本完成与结果返回：脚本在沙盒内运行完毕，将最终输出（通常是console.log的内容）通过标准输出（stdout）返回给网关，网关再将其作为本次Agent任务的单一结果，返回给LLM或用户。

这个范式的优势是革命性的：

实操心得：理解“网关”的核心地位很多刚接触Beige的开发者会误以为代码是在“裸奔”。实际上，网关是整套系统的安全与控制中枢。脚本本身只是一串文本，它没有直接执行任何危险操作的能力。所有对外的、有副作用的操作（读写文件、访问网络、查询数据库）都必须通过工具调用，而每一个工具调用都必须经过网关的审查和转发。这意味着，即使Agent写出rm -rf /这样的恶意代码，在Beige的体系下，它顶多是在沙盒里删除了自己的临时文件，因为rm工具根本不会被网关暴露给Agent，或者即使暴露了，其执行路径也被策略限制在沙盒内。这种架构确保了“能力”与“权限”的彻底解耦。

2.3 与其他框架（如OpenClaw）的异同

项目提到了OpenClaw，我们可以借此来定位Beige。像OpenClaw这类现代Agent框架，通常都具备一些共同的高级特性，Beige也同样支持：

• 多通道交互：提供TUI（终端用户界面）、Telegram机器人、HTTP API等多种方式与Agent对话，适应不同场景。
• 技能包：提供只读的知识包（Skills），作为背景信息注入给Agent，增强其上下文理解，而无需在每次对话中重复。
• 可扩展工具系统：允许开发者自定义工具，丰富Agent的能力集。
• 策略执行：可以对Agent能使用的工具、能访问的资源进行细粒度控制。
• 审计日志：记录所有交互和工具调用，满足合规性和调试需求。

那么，Beige的“不同”在哪里？最大的区别就在于执行模式和安全基线。

1. 执行模式：OpenClaw等框架遵循传统的“LLM驱动单步调用”模式。而Beige是“LLM生成代码，沙盒统一执行”模式。这是根本性的范式差异。
2. 安全基线：Beige将Docker沙盒化作为默认且唯一的运行时环境。没有“非沙盒”模式。所有代码执行，无一例外，都在容器内进行。通信仅通过受控的Socket。这是一种“零信任”原则在AI Agent运行时层面的贯彻。其他框架可能将沙盒作为可选项或仅用于特定危险工具。

3. 核心组件深度解析

3.1 网关：系统的指挥与控制中心

网关是Beige的“大脑”和“防火墙”。它不是一个简单的反向代理，而是一个具有丰富内部状态和逻辑的核心服务。

核心职责：

1. 生命周期管理：管理Agent会话、沙盒容器的创建与销毁。
2. LLM提供商集成：对接Anthropic、OpenAI等LLM API，处理对话上下文和提示词工程。
3. 策略引擎：加载并执行策略配置。策略可以定义诸如“Agent A只能在工作时间访问数据库工具B”、“禁止所有Agent执行网络扫描工具”等规则。策略检查发生在每个工具调用请求经过网关时。
4. 工具路由与执行：维护一个工具注册表。当沙盒内的脚本发起工具调用时，网关根据工具名找到对应的本地可执行文件或函数，注入秘密和环境变量后执行，并将结果返回。
5. 审计日志：结构化地记录所有事件。日志不仅包括工具调用，还包括Agent的创建、沙盒的启动、策略决策等。这些日志对于安全事件回溯、性能分析和计费都至关重要。
6. 秘密管理：安全地存储和管理API密钥、数据库连接字符串等敏感信息。秘密通过环境变量或安全的配置文件提供给网关，在工具执行时由网关动态注入，确保秘密永远不会进入沙盒或暴露给LLM。

网关配置初探：首次运行beige gateway start后，会在~/.beige/目录下生成默认配置。一个简化的核心配置可能如下所示（格式为JSON5，支持注释）：

// ~/.beige/config.json5 { gateway: { // 网关监听的地址和端口 host: 'localhost', port: 7788, // 审计日志存储路径 auditLogPath: './audit.log', // 沙盒配置 sandbox: { runtime: 'docker', // 目前仅支持docker image: 'beige-sandbox:latest', // 沙盒基础镜像 workspaceMount: '/workspace', // 容器内工作目录 } }, // LLM提供商配置 providers: { anthropic: { apiKey: '${ANTHROPIC_API_KEY}', // 从环境变量读取 defaultModel: 'claude-3-5-sonnet-20241022', } }, // 工具定义 tools: { 'kv': { path: '/usr/local/bin/beige-kv-tool', // 工具可执行文件路径 description: 'A simple key-value store tool.', // 工具所需的秘密，由网关管理 secrets: ['KV_STORAGE_PATH'] } }, // 策略定义 policies: [ { // 允许名为 'data-agent' 的Agent使用 'kv' 工具的 'get' 操作 agent: 'data-agent', tool: 'kv', action: 'get', effect: 'allow' }, { // 禁止所有Agent使用 'kv' 工具的 'delete' 操作 agent: '*', tool: 'kv', action: 'delete', effect: 'deny' } ] }

3.2 沙盒：坚不可摧的代码执行监狱

沙盒是Beige安全模型的基石。它基于Docker构建，但设计上比简单地docker run更加精细和受限。

沙盒的关键特性：

• 最小化镜像：沙盒镜像通常基于非常精简的Linux发行版（如Alpine），只包含运行Agent脚本所必需的最少组件：Deno运行时、必要的系统库、以及一个与网关通信的轻量级客户端。
• 无持久化存储：容器内的/workspace目录通常是一个临时卷（tmpfs）或每次启动时从空状态创建。脚本运行结束后，容器被销毁，所有生成的文件也随之消失。这防止了Agent在多次会话间持久化恶意代码或数据。
• 无网络访问：默认情况下，沙盒容器没有外部网络访问权限。脚本不能随意curl外部API或下载未知代码。所有与外界的数据交换，必须通过声明为工具并经由网关授权后执行。
• 受限的系统调用：通过Docker的Seccomp、AppArmor或SELinux配置，可以进一步限制容器内进程可以执行的系统调用，防止其逃逸或进行内核攻击。
• 资源限制：严格限制CPU、内存的使用量，防止脚本进行资源耗尽攻击（如无限循环消耗CPU）。

通信机制：沙盒与网关之间如何通信？通常通过以下几种安全方式：

1. Unix Domain Socket：在宿主机上创建一个Socket文件，并将其挂载到容器内的特定路径。沙盒内的工具调用客户端通过这个Socket与网关通信。这是最高效、最安全的方式，因为Socket文件有严格的权限控制。
2. HTTP over Localhost：网关在宿主机环回地址（127.0.0.1）上开启一个HTTP服务，并将此端口映射到容器内。容器内的客户端通过HTTP请求与网关交互。这种方式便于调试，但需要注意端口隔离，避免多个沙盒冲突。

注意事项：Docker守护进程权限Beige的沙盒依赖于Docker守护进程。这意味着运行Beige网关的用户必须具有执行docker命令的权限（通常是加入docker用户组）。在生产环境中，需要仔细评估由此带来的安全影响。一种更安全的方式是使用Docker的远程API配合TLS证书，或者使用rootless Docker模式。

3.3 工具系统：能力扩展的基石

工具是Agent能力的载体。在Beige中，工具不仅仅是函数，它们是独立的可执行文件。

工具的本质：一个Beige工具，从网关的角度看，就是一个可以通过命令行调用的程序。它接受标准输入（stdin）或命令行参数作为输入，并将结果输出到标准输出（stdout）或标准错误（stderr）。工具的描述（名称、参数、返回值类型）通过一个定义文件（如tool.json）注册到网关。

内置工具示例：KV存储Beige自带了一个简单的键值存储工具，非常适合演示。假设我们有一个工具定义：

// kv-tool-definition.json { "name": "kv", "description": "A persistent key-value store.", "parameters": { "action": { "type": "string", "enum": ["get", "set", "list"], "description": "The operation to perform." }, "key": { "type": "string", "description": "The key for get/set operations." }, "value": { "type": "string", "description": "The value for set operation." } } }

对应的可执行文件beige-kv-tool（可以用任何语言编写）会读取环境变量和参数。当Agent脚本调用/tools/bin/kv get user:123时：

1. 沙盒内的客户端将调用请求发送给网关。
2. 网关找到kv工具的定义，检查策略。
3. 网关执行beige-kv-tool --action=get --key=user:123，并将工具所需的环境变量（如存储路径KV_STORAGE_PATH）注入到执行环境中。
4. 工具程序读取本地数据库文件，返回结果。
5. 网关将结果返回给沙盒客户端。

如何开发自定义工具？这是Beige强大扩展性的体现。你可以用任何语言编写工具，只要它满足命令行交互的契约。

1. 选择语言：Python、Node.js、Go、Rust，甚至Shell脚本都可以。
2. 解析参数：你的程序需要能解析命令行参数（如使用argparsefor Python,commanderfor Node.js）。
3. 执行逻辑：实现工具的核心功能，如调用外部API、操作数据库、处理文件等。
4. 输出结果：将结果以JSON格式或纯文本打印到stdout。
5. 错误处理：非零退出码和stderr输出通常会被网关捕获并视为工具调用失败。
6. 注册工具：将工具的可执行文件路径和定义文件配置到网关的配置中。

例如，一个用Python写的“获取天气”工具：

#!/usr/bin/env python3 # weather-tool.py import argparse import requests import sys import os def main(): parser = argparse.ArgumentParser(description='Get weather for a city.') parser.add_argument('--city', required=True, help='City name') args = parser.parse_args() # 从环境变量获取API密钥，该密钥由网关管理，不会出现在脚本中 api_key = os.getenv('WEATHER_API_KEY') if not api_key: print("API key not configured", file=sys.stderr) sys.exit(1) try: # 调用外部API response = requests.get( f'https://api.weatherapi.com/v1/current.json', params={'key': api_key, 'q': args.city} ) response.raise_for_status() data = response.json() # 输出结构化结果 result = { 'city': data['location']['name'], 'temp_c': data['current']['temp_c'], 'condition': data['current']['condition']['text'] } print(json.dumps(result)) except Exception as e: print(f"Error fetching weather: {e}", file=sys.stderr) sys.exit(1) if __name__ == '__main__': main()

将这个脚本设为可执行，并在网关配置中注册，你的Agent就可以在沙盒脚本里通过exec('/tools/bin/weather --city=London')来获取天气了。

4. 从零开始：实战部署与配置指南

4.1 环境准备与安装

系统要求：

• Node.js 22+：Beige网关本身是Node.js应用。
• Docker & Docker Compose：用于沙盒隔离。确保Docker守护进程正在运行，且当前用户有权限执行docker命令。
• LLM API密钥：支持Anthropic Claude、OpenAI GPT等。我们以Anthropic为例。

安装步骤：

1. 全局安装CLI：这是与Beige交互的主要方式。

   npm install -g @matthias-hausberger/beige

   安装完成后，运行beige --help确认安装成功。

2. 配置API密钥：将你的Anthropic API密钥设置为环境变量。这是最推荐的方式，避免密钥硬编码在配置文件中。

   export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"

   你也可以稍后在生成的配置文件~/.beige/config.json5中配置。

3. 启动网关：网关是常驻服务。

   beige gateway start

   首次运行会进行初始化：

   • 在~/.beige/目录下创建配置文件、数据目录和日志目录。
   • 拉取或构建默认的沙盒Docker镜像（beige-sandbox:latest）。
   • 启动网关服务，默认监听localhost:7788。

4. 启动TUI（终端用户界面）：打开一个新的终端。

   beige tui

   TUI是一个交互式终端界面，你可以在这里直接与配置好的Agent对话。首次进入，你会看到一个简单的提示符。

4.2 核心配置文件详解

初始化后，~/.beige/目录结构如下：

.beige/ ├── config.json5 # 主配置文件 ├── data/ # 网关数据（如KV存储文件） ├── logs/ # 网关和审计日志 ├── tools/ # 自定义工具可执行文件存放目录 └── skills/ # 技能包（知识文档）目录

让我们深入config.json5，这是控制Beige行为的核心。

{ // 1. 网关全局设置 gateway: { host: '0.0.0.0', // 改为0.0.0.0允许远程连接（谨慎！） port: 7788, auditLogPath: './logs/audit.jsonl', // 审计日志使用JSON Lines格式 sandbox: { runtime: 'docker', image: 'ghcr.io/matthias-hausberger/beige-sandbox:main', // 沙盒容器资源限制 resources: { cpus: '1.0', // 限制使用1个CPU核心 memory: '512m', // 限制内存为512MB pids: 100 // 限制最大进程数 } } }, // 2. LLM提供商配置 - 支持多个 providers: { anthropic: { apiKey: '${ANTHROPIC_API_KEY}', // 引用环境变量 defaultModel: 'claude-3-5-sonnet-20241022', // 可选：设置请求超时、重试策略等 timeout: 30000, maxRetries: 2 }, openai: { apiKey: '${OPENAI_API_KEY}', defaultModel: 'gpt-4o', baseURL: 'https://api.openai.com/v1' // 可配置为代理地址 } // 可以添加更多提供商，如本地Ollama }, // 3. 代理定义 - 你可以定义多个不同特性的Agent agents: [ { id: 'data-analyst', // Agent唯一标识 name: '数据分析员', provider: 'anthropic', // 使用哪个提供商 model: 'claude-3-5-sonnet-20241022', // 使用哪个模型 // 系统提示词，定义Agent的角色和能力 systemPrompt: `你是一个专业的数据分析助手。你擅长编写TypeScript代码来处理和分析数据。 你可以使用KV工具来读取存储的数据。请将复杂任务编写成完整、健壮的脚本。 你的输出应该是可以直接执行的代码。`, // 此Agent可以使用的工具列表 tools: ['kv', 'math', 'file-reader'], // 注入给此Agent的技能包（上下文知识） skills: ['company-schema', 'analytics-guide'], // 温度参数，控制创造性 temperature: 0.2, // 最大token数 maxTokens: 4096 }, { id: 'general-assistant', name: '通用助手', provider: 'openai', model: 'gpt-4o', systemPrompt: `你是一个乐于助人的通用助手。`, tools: ['kv', 'web-search', 'calculator'], temperature: 0.7 } ], // 4. 工具配置 - 声明可用的工具及其路径 tools: { // 内置的KV工具 'kv': { path: '${BEIGE_HOME}/tools/kv', // 路径支持环境变量 description: 'Key-value storage tool.', env: { 'KV_STORAGE_PATH': '${BEIGE_HOME}/data/kv-store.json' } }, // 一个自定义的“计算器”工具示例 'math': { path: '/usr/local/bin/my-math-tool', description: 'Advanced mathematical operations.', // 如果工具需要秘密，在这里声明，实际值在网关环境变量中设置 secrets: ['MATH_API_KEY'] } }, // 5. 策略配置 - 安全规则的灵魂 policies: [ // 规则从上到下匹配，第一条匹配的规则生效 { id: 'allow-data-analyst-kv-read', agent: 'data-analyst', tool: 'kv', action: 'get', // 允许get操作 effect: 'allow' }, { id: 'deny-data-analyst-kv-write', agent: 'data-analyst', tool: 'kv', action: 'set', effect: 'deny' // 禁止set操作 }, { id: 'deny-all-delete', agent: '*', // 通配符，匹配所有Agent tool: 'kv', action: 'delete', effect: 'deny' }, // 基于时间的策略示例（需网关支持条件表达式） { id: 'office-hours-only', agent: 'general-assistant', tool: 'web-search', // 假设条件字段，实际语法取决于实现 condition: 'time.between("09:00", "17:00")', effect: 'allow' } ] }

4.3 创建你的第一个自动化Agent任务

假设我们想让Agent帮我们分析一组用户数据。数据已经以JSON格式存储在KV工具中，键为user:<id>。

步骤1：在TUI中选择或创建Agent在TUI中，通常有一个命令来切换或创建Agent。例如，输入/agent>// 文件名：analyze-users.ts import { parseArgs } from "https://deno.land/std@0.203.0/cli/parse_args.ts"; // 获取当前时间戳（毫秒） const now = Date.now(); const oneWeekAgo = now - (7 * 24 * 60 * 60 * 1000); async function execTool(cmd: string): Promise<string> { const proc = Deno.run({ cmd: cmd.split(" "), stdout: "piped", stderr: "piped" }); const output = await proc.output(); const outStr = new TextDecoder().decode(output); await proc.status(); proc.close(); return outStr.trim(); } async function main() { const users = []; let totalAge = 0; const activeEngineers = []; // 假设我们知道有50个用户，更健壮的做法是先调用 `kv list` 获取所有key for (let i = 1; i <= 50; i++) { const result = await execTool(`/tools/bin/kv get user:${i}`); try { const user = JSON.parse(result); users.push(user); totalAge += user.age; // 检查是否为活跃的工程师 if (user.department === "Engineering" && new Date(user.lastLogin).getTime() > oneWeekAgo) { activeEngineers.push({ id: user.id, name: user.name }); } } catch (e) { console.error(`Failed to parse user:${i}:`, e); } } const report = { totalUsers: users.length, averageAge: users.length > 0 ? totalAge / users.length : 0, activeEngineers: activeEngineers, generatedAt: new Date().toISOString() }; console.log(JSON.stringify(report, null, 2)); } if (import.meta.main) { main().catch(console.error); }

步骤4：执行与获取结果在Beige的TUI中，Agent在输出这段代码后，会自动（或根据你的确认）进入“执行”阶段。网关会：

1. 将这段代码写入沙盒容器的/workspace/analyze-users.ts。
2. 在沙盒内执行deno run --allow-run /workspace/analyze-users.ts。
3. 脚本运行，循环50次调用kv get工具。注意：这50次调用都经过网关的策略检查和审计。
4. 脚本计算并输出最终的JSON报告。
5. 网关捕获这个输出，并将其作为本次Agent交互的最终结果，显示在TUI中。

整个过程，LLM只参与了一次（生成脚本），用户只看到了一次请求和一次最终结果报告，但背后完成了50次数据查询和复杂的逻辑处理。这就是Beige效率的体现。

5. 高级应用与最佳实践

5.1 设计高效的Agent提示词

Beige将LLM从执行者转变为架构师，因此提示词（System Prompt）的设计至关重要。目标是指引LLM写出正确、安全、高效的代码。

优秀提示词要素：

1. 明确角色与能力：清晰告知Agent它的角色和可用的工具。

   “你是一个数据工程助手，擅长编写TypeScript代码。你可以使用kv工具读写数据，使用http工具调用内部API。你的核心任务是将复杂的数据处理需求转化为可执行的、高效的脚本。”

2. 强调代码生成范式：明确要求输出可执行代码，而不是一步步的计划。

   “对于任何涉及重复操作、条件判断或数据转换的任务，请直接输出一个完整的TypeScript脚本。脚本应包含必要的错误处理（try-catch）和日志输出（console.error）。只需输出代码本身，不要输出解释。”

3. 约定输出格式：定义好脚本的输入输出规范，便于后续自动化处理。

   “脚本的最终结果必须通过console.log(JSON.stringify(result))输出，以便被系统捕获。如果遇到错误，用console.error描述并process.exit(1)。”

4. 注入安全与约束意识：提醒Agent在沙盒环境中写作。

   “你生成的代码将在受限的Docker沙盒中运行，没有网络和文件系统访问权限（除了通过工具）。请不要尝试使用fetch、Deno.readFile等非授权API。所有外部交互必须通过提供的工具进行。”

5. 提供代码风格与库的指引：Deno支持直接导入URL，可以推荐一些标准库。

   “你可以使用Deno的标准库，例如从https://deno.land/std@0.203.0/导入fmt/,async/等模块。请使用ES模块语法（import）。工具通过Deno.run调用。”

5.2 构建自定义工具链

Beige的真正威力在于其可扩展的工具系统。你可以将内部系统、API、数据库都封装成工具。

实战：封装一个内部用户查询API为工具假设你有一个内部REST API：GET https://internal-api.example.com/users/{id}。

1. 编写工具包装脚本(internal-user-tool)：

   #!/bin/bash # 这是一个Bash脚本示例，实际生产环境建议用Python/Go等更健壮的语言 set -euo pipefail # 解析参数 while [[ $# -gt 0 ]]; do case $1 in --id) USER_ID="$2" shift 2 ;; *) echo "Unknown option: $1" >&2 exit 1 ;; esac done if [[ -z "${USER_ID:-}" ]]; then echo "Error: --id parameter is required" >&2 exit 1 fi # API密钥由网关通过环境变量注入 API_KEY="${INTERNAL_API_KEY:?INTERNAL_API_KEY environment variable is not set}" # 调用内部API response=$(curl -s -f -H "Authorization: Bearer $API_KEY" \ "https://internal-api.example.com/users/$USER_ID") # 输出结果 echo "$response"

   记得给脚本加执行权限：chmod +x internal-user-tool

2. 在网关配置中注册工具：

   tools: { 'internal-user': { path: '/path/to/your/scripts/internal-user-tool', description: 'Fetch user details from internal API.', secrets: ['INTERNAL_API_KEY'] // 声明需要的秘密 } }

3. 在Agent配置中启用该工具：

   agents: [{ id: 'hr-agent', // ... tools: ['kv', 'internal-user'], // 添加新工具 // ... }]

4. 设置环境变量：在运行网关的环境中，设置INTERNAL_API_KEY。

   export INTERNAL_API_KEY="your-secret-token"

现在，你的HR Agent就可以在脚本中这样使用了：

const userIds = [101, 102, 103]; const userDetails = []; for (const id of userIds) { const result = await execTool(`/tools/bin/internal-user --id=${id}`); userDetails.push(JSON.parse(result)); }

5.3 策略即代码：实现细粒度安全控制

策略是Beige安全模型的执行单元。好的策略应该遵循“最小权限原则”。

常见策略模式：

• 角色分离：为不同职责的Agent分配不同的工具集。

  { agent: 'data-reader', tool: '*', action: 'get', effect: 'allow' }, { agent: 'data-reader', tool: '*', action: 'set|delete', effect: 'deny' }, { agent: 'data-writer', tool: 'kv', action: '*', effect: 'allow' }

• 时间限制：（如果网关支持）限制工具只能在特定时间使用。
• 参数校验：（需要网关或工具支持）在策略中定义参数白名单或正则匹配，例如只允许查询特定前缀的键：{ agent: '*', tool: 'kv', action: 'get', condition: 'params.key matches "^user:d+"', effect: 'allow' }。
• 速率限制：防止Agent脚本滥用工具，例如限制每分钟最多调用某个API工具60次。

策略的生效顺序通常是自上而下，第一条匹配的规则生效。因此，应该把最具体的规则放在前面，最通用的规则（如兜底的拒绝规则）放在最后。

policies: [ // 1. 特别允许：允许admin-agent做任何事 { agent: 'admin-agent', tool: '*', action: '*', effect: 'allow' }, // 2. 具体业务规则：允许data-agent在上班时间读KV { agent: 'data-agent', tool: 'kv', action: 'get', condition: 'time.weekday() < 6 && time.hour() between 9 and 17', effect: 'allow' }, // 3. 通用拒绝：禁止所有Agent删除操作 { agent: '*', tool: '*', action: 'delete', effect: 'deny' }, // 4. 兜底拒绝：默认拒绝所有未明确允许的操作（可选，取决于网关默认行为） { agent: '*', tool: '*', action: '*', effect: 'deny' } ]

6. 生产环境部署考量与故障排查

6.1 部署架构建议

对于生产环境，单机运行的beige gateway start可能不够。需要考虑高可用、可观测性和安全性。

推荐架构：

1. 网关服务化：将beige gateway作为Systemd或Docker Compose服务运行，配置自动重启。
2. 反向代理：在网关前放置Nginx或Traefik作为反向代理，处理TLS终止、负载均衡（如果你运行多个网关实例）、基础认证和访问日志。
3. 独立数据库：将审计日志和工具所需的数据（如KV存储）配置到外部数据库（如PostgreSQL）或对象存储中，而不是本地文件。
4. 集中式日志：使用Fluentd、Vector或直接配置网关将审计日志发送到ELK Stack或Loki等日志聚合系统。
5. 秘密管理：使用HashiCorp Vault、AWS Secrets Manager或Kubernetes Secrets来管理工具所需的API密钥，并通过sidecar或初始化容器注入到网关环境，而不是明文环境变量。
6. 沙盒镜像管理：构建自己的沙盒基础镜像，严格控制其中的软件包，并定期进行安全扫描和更新。

使用Docker Compose部署示例：

# docker-compose.yml version: '3.8' services: beige-gateway: image: ghcr.io/matthias-hausberger/beige:latest # 假设有官方镜像 container_name: beige-gateway restart: unless-stopped ports: - "7788:7788" volumes: - ./config:/home/beige/.beige:ro # 挂载配置文件 - /var/run/docker.sock:/var/run/docker.sock # 挂载Docker socket以创建沙盒 environment: - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY} - INTERNAL_API_KEY=${INTERNAL_API_KEY} # 注意：挂载Docker socket有安全风险，生产环境应考虑更安全的方案，如使用Docker-in-Docker或独立的Docker API端点。 # 可选：反向代理 nginx: image: nginx:alpine ports: - "443:443" volumes: - ./nginx.conf:/etc/nginx/nginx.conf:ro - ./ssl:/etc/nginx/ssl:ro depends_on: - beige-gateway

6.2 常见问题与排查技巧

即使设计再精良，在实际操作中也会遇到各种问题。以下是一些常见坑点及解决方法。

问题1：Agent生成的代码执行失败，报“Permission denied”或“Tool not found”。

• 可能原因A：沙盒容器内/tools/bin/路径下没有对应的工具可执行文件。
  • 排查：检查网关配置中tools.kv.path指向的路径是否正确，并且该文件在宿主机上存在且可执行。
  • 解决：确保工具可执行文件被正确复制到配置指定的路径，或确保自定义工具的Docker镜像在构建时将其放入/tools/bin/。
• 可能原因B：网关运行用户对工具文件或Docker socket没有执行权限。
  • 排查：检查beige gateway进程的用户身份，以及/var/run/docker.sock的文件权限。
  • 解决：将运行用户加入docker组，或调整文件权限（注意安全风险）。

问题2：工具调用超时或无响应。

• 可能原因A：工具脚本本身执行缓慢或卡死。
  • 排查：直接在宿主机上手动执行工具命令，看是否正常。
  • 解决：优化工具脚本，增加超时和错误处理。在网关配置中为工具设置执行超时。
• 可能原因B：网络问题（针对需要网络访问的工具）。
  • 排查：检查工具脚本中的API端点是否可从宿主机访问。沙盒容器本身无网络，但工具是在宿主机（或网关侧）执行的。
  • 解决：确保宿主机网络通畅，检查防火墙规则。

问题3：LLM无法生成有效的TypeScript代码，总是输出自然语言计划。

• 可能原因：Agent的systemPrompt没有明确指示其输出代码。
  • 排查：查看分配给该Agent的systemPrompt内容。
  • 解决：强化提示词。明确要求“输出可执行的TypeScript代码”，并给出清晰的格式示例。可以尝试在提示词开头使用“你是一个TypeScript代码生成专家...”这样的强角色定义。

问题4：审计日志文件增长过快。

• 可能原因：每个工具调用都被记录，高频任务会产生大量日志。
  • 解决：
    1. 日志轮转：配置logrotate等工具对日志文件进行轮转和压缩。
    2. 调整日志级别：如果网关支持，降低非关键信息的日志级别。
    3. 输出到外部系统：如前所述，将审计日志配置为输出到标准输出（stdout），然后由Docker或容器编排平台收集，或直接集成日志库输出到Syslog/云日志服务。

问题5：Docker沙盒启动慢，影响响应速度。

• 可能原因：每次Agent任务都启动一个新的容器，冷启动开销大。
  • 解决：
    1. 连接池/容器复用：检查Beige网关是否支持容器复用。一些实现会保持一个“热”容器池，任务完成后清理/workspace而不是销毁容器。
    2. 优化基础镜像：使用更小的基础镜像（如Alpine），减少层数。
    3. 预热：在系统启动后，预先启动几个沙盒容器。

调试技巧：

• 启用详细日志：启动网关时使用beige gateway start --verbose或查看配置文件中的日志级别设置。
• 检查沙盒内部：如果任务失败，可以尝试手动运行一个沙盒容器进行调试：docker run -it --rm beige-sandbox:latest /bin/sh，然后在容器内尝试执行工具调用命令，模拟Agent脚本的环境。
• 查看审计日志：审计日志是了解“发生了什么”的黄金标准。仔细查看失败请求对应的日志条目，通常会有错误信息。

Beige代表了一种构建AI Agent系统的新思路，它将代码生成与安全沙盒执行相结合，在赋予Agent强大自主能力的同时，通过严格的网关控制和容器隔离确保了系统的安全性。这种架构特别适合需要处理复杂、多步骤逻辑，且对安全性和审计有要求的自动化场景，如数据分析流水线、内部运维自动化、客户数据报告生成等。它的学习曲线比简单的聊天机器人框架要陡峭，但带来的效率和安全提升是显著的。开始使用它，意味着你开始以“软件工程”的思维来设计和部署你的AI智能体，而不仅仅是进行提示词工程。