Orient the agent in a folder
When launched, a coding agent possesses no implicit knowledge of local project contents. The essential first step in any research workflow is establishing environmental grounding: directing the agent to inspect the active directory, inventory available datasets, and characterize file formats. This exercise provides your first tactile experience of tool-mediated agency in action, as you observe the agent actively choose how to navigate your directory rather than remaining confined to a single guessing path from pre-trained memory.
Before you start: An active agent running inside your project directory (Setup).
Background
An agent operates strictly within the working directory where its harness process was launched. It explores the workspace by executing standard operating system utilities (such as ls or directory walks) and reading the resulting stdout stream into working memory (Agent vs. chat). Ensuring the agent is initialized in the correct project root is critical for accurate file discovery.
This prompt serves as an immediate diagnostic test of the difference between chat and agents:
- Submitting "What files are in this folder?" to a standard chat window yields an apology or an invented guess, because a standalone model cannot touch your storage.
- Submitting the same prompt to an agent causes the harness to dispatch a shell command, read the console output, and report empirical reality.
General methodology
Instruct the agent to provide a structured directory inventory and identify files that cannot be parsed as plain text. This diagnostic step immediately reveals which datasets or documentation will require specialized libraries or conversion pipelines (Inputs).
What files are in this folder? Describe each in one line, and identify which ones cannot be parsed as plain text.
Workshop example · Clinical: clinic network
Start from: the data kit (scenarios/toy/kit/) copied into an empty folder (how to restore)
Produces: nothing new; this step only reads
Prompt
What files are in this folder? Describe each in one line, and tell me which ones you could not read as plain text.
What you should see. About eleven files. The text-based ones (clinic_notes.txt, data_dictionary.md, the CSVs, and
clinic_directory.html) are readable directly. The agent should flag clinic_targets.xlsx, pilot_protocol.docx,
patient_newsletter.pdf, and staffing.db as needing a reader or conversion. The next steps deal with each.
Verification criteria
- Verified command execution: Confirm that the agent ran an actual terminal command (e.g.,
ls -laorfind) rather than inferring file contents from the project directory name. - Empirical file inspection: Verify that the agent sampled file headers or metadata before generating descriptions.
- Format discrimination: Ensure the agent correctly flagged binary containers (such as
.xlsx,.docx, or.pdf) as requiring dedicated readers.
Common pitfalls
| Symptom | Underlying cause | Resolution |
|---|---|---|
| Describes non-existent files | Hallucination due to lack of tool execution | Prompt: "Which specific command did you execute to inspect this directory?" |
| Reports an empty directory | Agent was launched from an incorrect parent or child directory | Terminate the session, change into the intended project directory (cd ~/workshop-demo), and relaunch |
Next step: how code expands the agent's reach
Now that the agent can perceive your project directory, what can it actually do with these files? To understand how an agent manipulates data, generates figures, and compiles publications, the next concept explores how an agent uses code as a universal scientific instrument (What code makes possible).
Concepts behind this
- Agent vs. chat. A standard chat model answers from training memory. An agent interacts with a live computing environment to inspect files, execute code, and produce verifiable artifacts. Go deeper →
- Harnesses and models. An agent system separates the inference engine (the model), the orchestration software (the harness), and the execution target (the environment). Understanding this separation clarifies system capabilities and boundaries. Go deeper →