Shell and System

Shell execution, environment variables, scheduling, and desktop automation. Gate shell with execution_permissions.

← Prebuilt Tools overview

Tool	Extra	Description
environment	base	Read, set, and unset environment variables.
shell	base	Execute shell commands with stdout/stderr capture.
cron	base	Add, list, and remove cron jobs.
use_computer	use-computer	Desktop automation — mouse, keyboard, and OCR.

---

environment

Read, set, and unset environment variables.

from elsai_tools.environment import environment

Parameter	Type	Required	Description
action	str	Yes	list, get, set, delete, or validate
name	str	No	Variable name
value	str	No	Value to set
prefix	str	No	Filter by prefix (list)
masked	bool	No	Mask sensitive values

shell

Execute shell commands with stdout/stderr capture.

from elsai_tools.shell import shell

Parameter	Type	Required	Description
command	Union[str, List[Union[str, Dict[str, Any]]]]	Yes	Command string, list of commands, or command objects
parallel	bool	No	Run commands in parallel
ignore_errors	bool	No	Continue on failure
timeout	int	No	Timeout in seconds
work_dir	str	No	Working directory
non_interactive	bool	No	Skip confirmation prompt

A2A isolation

On A2A servers, shell declares PER_CONTEXT scope. Each context_id receives its own ShellTool instance via clone_for_a2a_context(). When work_dir is omitted, the default working directory is scoped to:

$ELSAI_A2A_SESSION_DIR/<context_id>/shell/

Using on an A2A server

from elsai import Agent

# Register the tool on the template agent; PER_CONTEXT cloning is automatic.
agent = Agent(tools=[...])  # e.g. tools=[python_repl], tools=[graph], …

Full A2AServer + session-manager wiring lives in Concepts — see Stateful prebuilt tools — examples.

• When work_dir is omitted, defaults to $ELSAI_A2A_SESSION_DIR/<context_id>/shell/.
• Each context_id gets its own ShellTool instance.

See Stateful tools on A2A and Stateful prebuilt tools — examples.

cron

Add, list, and remove cron jobs.

from elsai_tools.cron import cron

Parameter	Type	Required	Description
action	str	Yes	add, list, or remove
schedule	str	No	Cron expression
command	str	No	Command to run
job_id	int	No	Job ID (remove)
description	str	No	Human-readable description

use_computer

Desktop automation — mouse, keyboard, and OCR.

from elsai_tools.use_computer import use_computer

Extra: use-computer

Parameter	Type	Required	Description
action	str	Yes	Action type (click, type, screenshot, etc.)
x	int	No	Screen X coordinate
y	int	No	Screen Y coordinate
text	str	No	Text to type
key	str	No	Key to press
region	List[int]	No	Screen region [x, y, w, h]
app_name	str	No	Target application
click_type	str	No	Click type

A2A isolation

On A2A servers, use_computer declares PER_CONTEXT scope. Each context_id gets its own tool instance; screenshots are stored under:

$ELSAI_A2A_SESSION_DIR/<context_id>/use_computer/screenshots/

Using on an A2A server

from elsai import Agent

# Register the tool on the template agent; PER_CONTEXT cloning is automatic.
agent = Agent(tools=[...])  # e.g. tools=[python_repl], tools=[graph], …

Full A2AServer + session-manager wiring lives in Concepts — see Stateful prebuilt tools — examples.

• Requires elsai-agents-tools[use-computer] and a GUI desktop on the host.
• Screenshots are stored under $ELSAI_A2A_SESSION_DIR/<context_id>/use_computer/screenshots/.

See Stateful tools on A2A and Stateful prebuilt tools — examples.