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

​
您可以做什么

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

​
核心概念

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

​
快速开始

from agkit.tools import create_bash_tool, LocalBashOperator

# 1. 选择后端并创建上下文
bash_operator = LocalBashOperator()
context = {"bash_operator": bash_operator}

# 2. 创建工具
bash_tool = create_bash_tool(context)

# 3. 使用工具运行命令
result = await bash_tool.invoke({
    "command": 'echo "Hello from the command line!"'
})

print(result.data.stdout)

​
选择正确的后端

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

​
核心操作和示例

​
运行简单命令

执行任何标准 shell 命令并获取 stdout、stderr 和 exitCode。 
result = await bash_tool.invoke({'command': 'ls -la'})
# result.data: { 
#   'stdout': 'total 48\ndrwxr-xr-x  12 user  staff   384 Jan 15 10:30 .\n...',
#   'stderr': '',
#   'exit_code': 0
# }

if result.success:
    print('Directory listing:', result.data.stdout)

​
管道命令

使用管道链接命令,就像在常规 shell 中一样。 
# 首先,使用文件系统工具创建文件
await fs_toolkit.get_tool('write_file').invoke({
    'file_path': 'data.txt',
    'content': 'This is a test.'
})

# 现在,使用 bash 工具读取它
result = await bash_tool.invoke({'command': 'cat data.txt'})
# result.data: { 'stdout': 'This is a test.', 'stderr': '', 'exit_code': 0 }
print(result.data.stdout)  # "This is a test."

​
流式输出

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

# 创建带有流式处理程序的操作符
streaming_operator = SandboxBashOperator(
    api_key=os.getenv('E2B_API_KEY'),
    on_stdout=lambda data: print(f"[STDOUT] {data.line}"),
    on_stderr=lambda data: print(f"[STDERR] {data.line}"),
)

bash_tool = create_bash_tool(bash_operator=streaming_operator)

# 运行长时间运行的命令
await bash_tool.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。

文件系统工具

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