Bash/Command Line Tools

​

What You Can Do

• Run Any Shell Command: Execute standard commands like ls, grep, curl, or git.
• Execute Scripts: Run shell scripts (.sh) or other command-line scripts.
• Manage System Processes: Check running processes, manage services, or gather system information.
• Choose Your Environment: Run commands directly on the local machine for speed or in a secure sandbox for safety.

​

Core Concepts

1. BashTool: The main tool you provide to your agent. It takes a shell command as input and executes it.
2. BashOperator (Backend): The engine that runs the command. You can choose from two backends:
   • LocalBashOperator: Executes commands directly on the host machine. It’s fast but should only be used in trusted environments.
   • SandboxBashOperator: Executes commands inside a secure, isolated E2B container. It’s the safe choice for handling commands generated by LLMs or users.

​

Quick Start

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

// 1. Choose a backend and create the context
const bashOperator = new LocalBashOperator();
const context = { bashOperator };

// 2. Create the tool
const bashTool = createBashTool(context);

// 3. Use the tool to run a command
const { data } = await bashTool.invoke({ 
  command: 'echo "Hello from the command line!"' 
});

console.log(data.stdout);

​

Choosing the Right Backend

​

Core Operations & Examples

​

Running a Simple Command

​

Piping Commands

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);

​

Streaming Output

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

// Create an operator with streaming handlers
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 });

// Run a long-running command
await bashTool.invoke({
  command: 'for i in {1..5}; do echo "Step $i"; sleep 1; done'
});

// The output will be logged to the console in real-time.

​

Best Practices & Troubleshooting

• Prefer Specific Tools: If a dedicated tool exists (like the ls or grep tools in FilesystemToolkit), prefer it over the raw bash command. Dedicated tools often provide structured output and better error handling.
• Security: Never use the LocalBashOperator with commands generated by an LLM or external users. Always use the SandboxBashOperator for untrusted input.
• Error Handling: Always check the exitCode and stderr from the result to know if a command failed and why.
• Working Directory: Be mindful of the current working directory (cwd). Commands are executed relative to it. You can set the cwd when creating the BashOperator.

​

Next Steps