Skip to content

Tutorial · Clinical

This guided tutorial provides a structured, linear path through the workshop on a clinical operations example: you direct a coding agent to clean multi-site clinic data, analyze a follow-up call pilot, and write up the result. By sequencing conceptual background alongside practical exercises, it ensures you have the necessary context immediately before each hands-on task, with direct links back to the reference pages.

You can complete it in one session or across several. Work from each stage is preserved as a restorable checkpoint, so you can pause, resume, or skip forward at any point (Setup).

This is a synthetic example; nothing here is a finding about a real population.

Learning outcomes

By completing this tutorial, you will produce:

  • A configured local agent environment with safe data-handling and credential practices.
  • A reproducible data cleaning pipeline with an explicit audit trail of cleaning decisions.
  • A statistical analysis featuring crude and adjusted estimates, independently reviewed by a second agent.
  • A verified bibliography, an executive abstract with citations, and an interactive reporting dashboard.
  • A reusable command-line tool and agent skill tracked in Git, alongside a bulk classification workflow using an external API.

Prerequisites

  • A computer with terminal access where you can install tools (or where an agent CLI is already configured). The initial step walks through setup.
  • A dedicated working directory for workshop files.
  • For the advanced section only: an active API key with a modest usage budget.
  • Review the concept page first, then proceed to the demo exercise. Concept summaries are intentionally concise, providing the methodological grounding before you run commands.
  • Work through the benchmark dataset before using your own data. The provided scenario includes known answers, making it straightforward to evaluate whether the agent's calculations are accurate before applying the patterns to novel data.
  • Adapt to your schedule. Optional detours and advanced exercises are clearly labelled. If you have limited time, focus on the core "Full step" exercises listed in the demo track.

Contents

1. Get started

Step Type What it covers
Setup Setup Restore the data kit and any starting point you need.

2. Meet your agent

Step Type What it covers
Agent vs. chat Concept 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.
Orient the agent in a folder Demo Direct the agent to audit local project files, establishing environmental grounding and identifying files requiring specialized parsers.
What code makes possible Concept Coding agents use executable code as a universal interface for research tasks, making text-based source formats and programmatic scripts far more reliable than manual GUI interactions.
Harnesses and models Concept 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.

3. Work safely

Step Type What it covers
Privacy and data handling Concept 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.
Environment Concept Computational research requires isolated execution environments to prevent dependency conflicts and guarantee that findings can be reproduced on other systems.
Prepare your environment Demo Direct the agent to audit local dependencies, initialize an isolated project virtual environment, and document lockfile-pinned setup procedures.

4. Understand the inputs

Step Type What it covers
Inputs Concept Language models process information as text. Selecting appropriate ingestion pathways and source formats preserves data structure and prevents extraction errors.
Read and summarize text files Demo Direct the agent to inspect and synthesize project-local text files, validating source provenance and avoiding copy-paste truncation.
Read spreadsheets, documents, and PDFs Demo Ingest XLSX, DOCX, and PDF containers, auditing structural extraction compromises such as merged cells, table boundaries, and OCR artifacts.
A first answer from raw data Demo Generate an initial exploratory estimate from uncleaned data, requiring explicit definitions and denominators to establish an uncleaned baseline.

5. Clean the data

Step Type What it covers
Scoping work Concept Scope requests to sizes that can be independently verified. Require structured plans before executing complex multi-step pipelines.
Verification Concept Language models can be confidently incorrect. Require empirical evidence, verify mathematical invariants, and use clean-context peer review to audit findings.
Profile the data and find problems Demo Generate a systematic data-quality audit documenting anomalies, null patterns, and unit mismatches without modifying source files.
Steering Concept Balance supervisory approval modes with task risk, intervene early when execution drifts, and codify recurring corrections into standing rules.
Plan the cleaning and make the judgement calls Demo Formulate an explicit data cleaning protocol separating deterministic syntactic repairs from substantive domain decisions before modifying data.
Clean the data with a script, and show the flow Demo Implement approved cleaning rules in a non-destructive script that produces cleaned datasets and a reconciled record-flow table.
Memory Concept Language models do not retain memory across sessions. Preserving knowledge requires externalizing guidelines, documentation, and tools into persistent files.
Make the agent remember with AGENTS.md Demo Persist critical project rules and analytical conventions in AGENTS.md, ensuring new sessions maintain project memory without redundant steering.

6. Research analysis

Step Type What it covers
Context Concept Context represents the model's active working memory. Because every turn re-transmits the complete conversation, long sessions increase latency, cost, and attention drift.
Build a study cohort with a flow table Demo Translate formal study eligibility criteria into a reproducible cohort dataset, accompanied by an attrition flow diagram reconciling excluded populations.
Analyze an exposure and outcome, crude and adjusted Demo Conduct crude and multivariable adjusted statistical comparisons, evaluating how controlling for baseline confounders alters estimated effect sizes.
Review the analysis with a fresh second agent Demo Commission an independent peer review of scripts and findings using a secondary agent session with a clean context window.
Before-and-after comparison with a comparison group Demo Execute a quasi-experimental difference-in-differences analysis comparing intervention and control sites to account for secular temporal trends.

7. Write it up

Step Type What it covers
Outputs Concept Request text-based source files and compile them to presentation formats. Source files are inspectable, version-controlled, and reproducible.
Find references from a bibliographic database Demo Build a verified BibTeX bibliography via programmatic API retrieval (PubMed E-utilities), establishing a reproducible search log and eliminating hallucinated citations.
Build references from links you provide Demo Construct an auditable BibTeX bibliography from researcher-curated URLs, using DOI content negotiation and PMID lookups while barring model speculation.
Write a research abstract as LaTeX, with citations Demo Author a structured scientific abstract in LaTeX from empirical results files and a verified bibliography, compiling a publication PDF and tracing numerical claims to their source.
Build a dashboard as a single web page Demo Compile an interactive, self-contained HTML research dashboard displaying aggregated metrics and audit counts without external runtime dependencies.
Export to Word and Excel for collaborators Demo Convert plain-text source files into DOCX and XLSX deliverables for external collaborators, auditing formatting trade-offs and preserving master text sources.

8. Make it repeatable

Step Type What it covers
Tools Concept Turning interactive prompts into parameterized scripts creates deterministic, testable tools that run identically on every execution.
Turn the analysis into a tool and a skill Demo Package proven analytical pipelines into tested, parameterized command-line tools and modular agent skills for persistent reproducibility.
Version control Concept Version control provides an immutable audit trail and safety net, allowing researchers to inspect every line changed by an agent and roll back errors instantly.
Review and commit what the agent produced Demo Audit repository state, configure .gitignore to exclude raw data and secrets, and record an immutable Git commit snapshot.
Costs Concept Language model pricing is determined by token volume. Because conversation history re-transmits on every turn, session length compounds costs quadratically.
Check usage and compact the conversation Demo Monitor cumulative token consumption, synthesize session decisions into a persistent summary file, and initialize a clean working context.

Advanced

Step Type What it covers
Secrets Concept Credentials must never enter prompts, session logs, or version control. Use isolated environment variables and enforce immediate revocation protocols if exposed.
Sandboxing and isolation Concept Coding agents execute commands with your user permissions. Enforcing appropriate isolation boundaries protects local files and prevents indirect injection attacks.
Use a secret safely Demo Configure API credentials securely via restricted .env environment files and .gitignore, preventing secret leakage into transcripts and version control.
Classify many records with a language-model API Demo Execute batch record classification via programmatic API calls with dry-run estimation, incremental state checkpointing, and validation against a benchmark sample.

Track navigation