A workspace gives an agent a working environment, not just a collection of predefined tools. It combines code execution, a filesystem, and a command-line interface (CLI), so the agent can write code, save intermediate results, inspect files, and run commands during a task. section 8.4.1 section 8.4
The difference matters when a task calls for an operation nobody registered as a tool. To find log files containing “error,” the agent can write a short Python search or run `grep -r -l "error" --include="*.log" .`. Neither route needs a dedicated `search_logs` tool. section 8.4.1
Connect a sandboxed workspace
Create an `Agent` with `code_execution="e2b"` to register `execute_python`, and add `bash_tool` and `upload_file` for commands and file transfer. Tell the agent it can upload files, run bash, and execute Python. The workspace is then available within the agent’s task loop rather than as a separate manual workflow. section 8.4.3 section 1.5.6
Listing 8.26 Setting up an agent with workspace for Excel analysis
from scratch_agents import Agent, LlmClient
from scratch_agents.tools.code_execution import bash_tool, upload_file
agent = Agent(
model=LlmClient(model="gpt-5"),
tools=[bash_tool, upload_file],
instructions="""You have access to a sandboxed Linux environment.
You can upload files, run bash commands, and execute Python code.
Use these capabilities to analyze data and solve problems.""",
code_execution="e2b"
)
prompt = f"""The attached spreadsheet contains the sales of menu items
for a regional fast-food chain. Which city had the greater total sales:
Wharvton or Algrimand?
The file is located at: ./gaia_workspace/7cc4acfa-63fd-4acc-a1a1-e8e529e0a97f.xlsx
"""
result = await agent.run(prompt, verbose=True)
print(result.output)
The agent setup shows the three capabilities together: sandboxed Python execution, a registered bash tool, and a registered upload tool. section 8.4.3
Analyze an attached spreadsheet
For a question comparing total sales in two cities, the agent uploads the Excel file, installs needed libraries in the sandbox, and uses pandas to aggregate sales by city. Session state lets a later step use results from an earlier one. There is no need to implement a new Excel-reading tool for this task. section 8.4.3
Isolation changes the operational risk: installing packages and running generated code in the sandbox does not change the host environment. It does not remove the need to provide task files—the agent uploads local files it needs. The workspace can also hold detailed agent-skill definitions, keeping tool information and execution results that need no LLM judgment out of the prompt. section 8.4.3 section 8.6
