Bash/Command Line Tools

Execute shell commands and scripts in local or sandboxed environments

AG-Kit’s Bash tool gives your agents the power to execute shell commands, run scripts, and interact with the operating system. It’s a versatile tool for automation, system administration, and development tasks, with built-in support for both local and secure sandboxed execution.

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

TypeScript

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

Backend	Use Case	Key Benefit
LocalBashOperator	Trusted Scripts & Dev	Performance & Local Access
SandboxBashOperator	Untrusted Commands (LLMs)	Security & Isolation

Core Operations & Examples

Running a Simple Command

Execute any standard shell command and get the stdout, stderr, and exitCode.

Piping Commands

Chain commands together using pipes, just like in a regular shell.

TypeScript

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

For long-running commands like npm install or a development server, you can stream stdout and stderr in real-time instead of waiting for the command to finish. This is done by providing onStdout and onStderr handlers when creating the operator.

TypeScript

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

API Reference

See the full API for advanced configuration and options.

File System Tools

Combine with file operations for complete workflows.