Shell | Agno

ShellTools enable an Agent to interact with the shell to run commands.

Prerequisites

Create and activate a virtual environment, then install:

uv pip install agno openai

The Agent model uses an OpenAI key, separately from any toolkit provider credentials.

Set OpenAI Key

Set your OPENAI_API_KEY as an environment variable. You can get one from OpenAI.

export OPENAI_API_KEY=sk-***

Example

The following agent will run a shell command and show contents of the current directory.

Mention your OS to the agent to make sure it runs the correct command.

cookbook/91_tools/shell_tools.py

from agno.agent import Agent
from agno.tools.shell import ShellTools

agent = Agent(tools=[ShellTools()])
agent.print_response("Show me the contents of the current directory", markdown=True)

ShellTools runs any command the model constructs, with no allowlist or confirmation gate. Setting base_dir only sets the working directory for the command; it does not restrict what the command can access. Keep human supervision for untrusted prompts, and run inside a sandbox (container, VM, or Daytona) for untrusted code execution.

Toolkit Params

Parameter	Type	Default	Description
`base_dir`	`Optional[Union[Path, str]]`	`None`	Base directory for shell command execution
`enable_run_shell_command`	`bool`	`True`	Enables functionality to run shell commands
`all`	`bool`	`False`	Enables all functionality when set to True

Toolkit Functions

Function	Description
`run_shell_command`	Runs a shell command and returns the output or error.

Developer Resources

Tools