Retrieve images from a DICOM server
In practice, images often live in a server, not in a folder. Here you direct the agent to use the server's web interface (a REST API) to list and download studies, with three rules: read-only, credentials never shown, and nothing leaves the machine. Then you check that what arrived agrees with what you expected.
Before you start: A project with a .env file for credentials and .env in .gitignore (Use a secret safely), and a DICOM server you are allowed to read from. The example uses a free local server that you start yourself. This step is optional.
Background
A PACS (picture archiving and communication system) stores medical images and serves them over network protocols. Orthanc is a free, open-source DICOM server that is also widely used for research and teaching. Besides the standard DICOM network protocol, it offers a REST API: ordinary web requests such as GET /studies return lists as JSON, and GET /instances/<id>/file returns the original DICOM file.
Reading from a server is a different risk from reading a folder (Inputs):
- Read-only. A
GETrequest cannot change the server. Requests that create, modify or delete (POST,PUT,DELETE) can. Tell the agent to useGETonly, and check. - Credentials. The server asks for a username and password. They belong in
.env, never in a prompt, the transcript or Git (Secrets). - Where the data goes. Retrieved images can contain patient information (Privacy). A real hospital server should be reached only from approved machines, with approval for what you do. The example server accepts connections from this computer only.
Counts also deserve a check. A server de-duplicates by unique image ID and rejects files it cannot parse, so the number of images in a server can be smaller than the number of files that were sent to it.
General methodology
State the rules before the task, and ask for a reconciliation, not just a download:
A DICOM server (Orthanc) is running at <url>. Use it read-only: GET requests only, nothing may be created, changed or deleted. The credentials are in .env as <USER_VAR> and <PASSWORD_VAR>; do not open, print or log them, and refuse any server that is not <local>. Write <scripts/fetch.py> using only the standard library that (1) prints the server's counts of patients, studies, series and instances, (2) downloads every instance to <data/server/> (skipping files already there), and (3) writes an index with the identifiers I will need. Then compare the counts with the <N> files I have in <folder> and explain every difference.
Workshop example · Imaging: chest radiographs
Start from: the committed project with .env set up, plus a local Orthanc server loaded with the kit's images (see below) (how to restore)
Produces: scripts/orthanc_fetch.py, data/orthanc/ (downloaded DICOM files and index.csv)
Prompt
An Orthanc DICOM server is running at http://localhost:8042. Use it read-only: GET requests only, nothing may be created, changed or deleted. The credentials are in .env as ORTHANC_USER and ORTHANC_PASSWORD; do not open, print or log them, and refuse any server that is not localhost. Write scripts/orthanc_fetch.py using only the standard library that (1) prints the server's counts of patients, studies, series and instances, (2) downloads every instance to data/orthanc/<SOPInstanceUID>.dcm, skipping files already there, and (3) writes data/orthanc/index.csv with the file name, patient ID, study date, modality and view position. Then compare the counts with the 283 files in images/ and explain every difference.
Files used: images/*.dcm (already in your project) and a local Orthanc server.
Start the server (once). If you used the quickstart installer, the files under scenarios/imaging/ named below are in the -tools folder next to your project folder (for example ~/workshop-imaging-tools/). Orthanc runs on Linux, macOS and Windows. Use any one of these. The configuration in scenarios/imaging/extras/orthanc/orthanc.json enables a password, allows connections from this computer only, and turns off scripting.
# Option A: a single downloaded program (Linux x86-64; no installation or administrator rights)
curl -L -o Orthanc https://orthanc.uclouvain.be/downloads/linux-standard-base/orthanc/1.12.4/Orthanc && chmod +x Orthanc
./Orthanc scenarios/imaging/extras/orthanc/orthanc.json
# Option B: Docker (any system); the port is published on localhost only
docker run --rm -p 127.0.0.1:8042:8042 -e ORTHANC__AUTHENTICATION_ENABLED=true \
-e ORTHANC__REGISTERED_USERS='{"workshop": "workshop-demo-only"}' orthancteam/orthanc
On Windows or macOS you can instead install Orthanc from orthanc-server.com and copy the settings from orthanc.json into its configuration. Option A is the one tested while preparing this material (Orthanc 1.12.4 on Linux); the Docker and installer routes are not.
Then load the kit's images with the loader script, and put the demo credentials in .env (the values are in orthanc.json; they protect nothing but this local demo):
python3 scenarios/imaging/extras/orthanc/load_kit.py ~/workshop-imaging/images
printf 'ORTHANC_USER=workshop\nORTHANC_PASSWORD=workshop-demo-only\n' >> ~/workshop-imaging/.env
The loader should report stored 275, already stored 6, rejected 2. Open http://localhost:8042/ in a browser (user workshop) to see Orthanc's own explorer.
Reference result. The server reports 255 patients, 275 studies, 275 series, 275 instances (about 72 MB). The reconciliation with the 283 files in images/:
| Difference | Count | Why |
|---|---|---|
| Files not in the server | 8 | 2 are truncated files that Orthanc rejects, and 6 are exact duplicates that share an image ID, which it stores once |
| Patients vs studies | 255 vs 275 | 20 patients have a second (follow-up) study. Patient ID variants (upper case, a prefix, a leading space) also create separate "patients"; the same patient written two ways is counted twice |
This matches what the profile found in the files, and the downloaded files are byte-for-byte identical to the originals (compare a checksum of a few). A good agent says which of the differences it verified and which it inferred.
Check the rules. Search the script for POST, PUT and DELETE (there should be none), confirm .env does not appear in git status, and point the script at a different address to see that it refuses. A reference script is scenarios/imaging/reference/orthanc_fetch.py.
Clean-up. Stop Orthanc with Ctrl+C. Its database is the orthanc-db folder next to where you started it; delete it when you are done.
Verification criteria
- GET only. The script contains no other request type; the agent can show you where it checks this.
- No secret exposure. Credentials are not in the script, the output or the transcript, and
git statusdoes not list.env. - Local only. The script refuses a server address that is not the approved one.
- Counts reconciled. Each difference between what you expected and what arrived has an explanation you can verify.
- Bytes match. A downloaded file is identical to the original (compare a checksum of one pair).
Common pitfalls
| Symptom | Underlying cause | Resolution |
|---|---|---|
401 Unauthorized |
The credentials were not loaded, or are wrong | Check that .env has the variable names the script reads (without printing the values) |
| The agent proposes uploading or deleting something | The task was described loosely | Restate the read-only rule; refuse any non-GET request |
| Fewer images than files | The server de-duplicates and rejects unreadable files | Account for each difference before you trust the count |
| More "patients" than expected | The server identifies patients by the ID string; variants of one ID become separate patients | This is a data-quality finding, not a server error |
Concepts behind this
- Inputs. Language models process information as text. Selecting appropriate ingestion pathways and source formats preserves data structure and prevents extraction errors. Go deeper →
- Secrets. Credentials must never enter prompts, session logs, or version control. Use isolated environment variables and enforce immediate revocation protocols if exposed. Go deeper →
- Privacy and data handling. Data read by an agent is transmitted to the model provider as context. Determining whether data is permitted to leave your infrastructure must precede deciding what tasks to delegate. Go deeper →
Builds on: Use a secret safely