跳转到主要内容
AG-Kit 的 Bash 工具使您的 Agent 能够执行 shell 命令、运行脚本并与操作系统交互。这是一个用于自动化、系统管理和开发任务的多功能工具,内置对本地和安全沙箱执行的支持。

​
您可以做什么

  • 运行任何 Shell 命令: 执行标准命令,如 ls、grep、curl 或 git。
  • 执行脚本: 运行 shell 脚本(.sh)或其他命令行脚本。
  • 管理系统进程: 检查运行中的进程、管理服务或收集系统信息。
  • 选择您的环境: 直接在本地机器上运行命令以获得速度,或在安全沙箱中运行以确保安全。

​
核心概念

  1. BashTool: 您提供给 Agent 的主要工具。它接受 shell 命令作为输入并执行它。
  2. BashOperator (后端): 运行命令的引擎。您可以从两个后端中选择:
    • LocalBashOperator: 直接在主机上执行命令。速度快但应仅在受信任的环境中使用。
    • SandboxBashOperator: 在安全、隔离的 E2B 容器中执行命令。这是处理 LLM 或用户生成的命令的安全选择。

​
快速开始

import { createBashTool, LocalBashOperator } from '@ag-kit/tools';

// 1. 选择后端并创建上下文
const bashOperator = new LocalBashOperator();
const context = { bashOperator };

// 2. 创建工具
const bashTool = createBashTool(context);

// 3. 使用工具运行命令
const { data } = await bashTool.invoke({ 
  command: 'echo "Hello from the command line!"' 
});

console.log(data.stdout);

​
选择正确的后端

后端用例主要优势
LocalBashOperator受信任的脚本和开发性能和本地访问
SandboxBashOperator不受信任的命令 (LLM)安全性和隔离

​
核心操作和示例

​
运行简单命令

执行任何标准 shell 命令并获取 stdout、stderr 和 exitCode。

​
管道命令

使用管道链接命令,就像在常规 shell 中一样。 
const result = await bashTool.invoke({
  command: 'ps aux | grep node'
});
// result.data: { 
//   stdout: 'user  12345  0.5  1.2  node server.js\nuser  12346  0.3  0.8  node worker.js',
//   stderr: '',
//   exitCode: 0
// }

console.log('Node processes:', result.data.stdout);

​
流式输出

对于像 npm install 或开发服务器这样的长时间运行的命令,您可以实时流式传输 stdout 和 stderr,而不是等待命令完成。这是通过在创建操作符时提供 onStdout 和 onStderr 处理程序来完成的。 
import { createBashTool, SandboxBashOperator } from '@ag-kit/tools';

// 创建带有流式处理程序的操作符
const streamingOperator = new SandboxBashOperator({
  apiKey: process.env.E2B_API_KEY,
  onStdout: (data) => console.log(`[STDOUT] ${data.line}`),
  onStderr: (data) => console.error(`[STDERR] ${data.line}`),
});

const bashTool = createBashTool({ bashOperator: streamingOperator });

// 运行长时间运行的命令
await bashTool.invoke({
  command: 'for i in {1..5}; do echo "Step $i"; sleep 1; done'
});

// 输出将实时记录到控制台。

​
最佳实践和故障排除

  • 优先使用特定工具: 如果存在专用工具(如 FilesystemToolkit 中的 ls 或 grep 工具),请优先使用它而不是原始 bash 命令。专用工具通常提供结构化输出和更好的错误处理。
  • 安全性: 永远不要将 LocalBashOperator 用于 LLM 或外部用户生成的命令。始终对不受信任的输入使用 SandboxBashOperator。
  • 错误处理: 始终检查结果中的 exitCode 和 stderr,以了解命令是否失败以及原因。
  • 工作目录: 注意当前工作目录 (cwd)。命令相对于它执行。您可以在创建 BashOperator 时设置 cwd。

​
下一步

API 参考

查看高级配置和选项的完整 API。

文件系统工具

与文件操作结合以实现完整的工作流。