Azure-Samples / Azure-Samples/foundry-hosted-agents-workshop
[Feature] Add a per-step preflight callout to every step (02-09)
- Dominant language
- Python
- Stars
- 7
- Forks
- 7
- Avg merge
- 2h 59m
- Merged PRs (30d)
- 3
Description
## Problem or opportunity
`scripts/preflight.py` already supports **per-step validation** via `--step N`, with checks tailored to each step's requirements (e.g. step 3 verifies `MCP_SERVER_LABEL` / `MCP_SERVER_URL`, step 5 verifies `AZURE_AI_SEARCH_ENDPOINT` / `AZURE_AI_SEARCH_INDEX_NAME`).
However, only **Step 0** (`docs/steps/00-intro.md`) and **Step 1** (`docs/steps/01-basic.md`) actually instruct learners to run preflight. Steps **02–09** never mention it. As a result, learners can start a step with missing or misconfigured `.env` values and only discover the problem via cryptic runtime errors mid-step, rather than catching it up front.
## Proposed improvement
Add a "Before you start" preflight callout to each of steps **02–09**, matching the pattern already used at the top of `docs/steps/01-basic.md`:
> **Before you start:** ... If `python scripts/preflight.py --step N` is green, you're ready.
Details:
- Use the correct `--step N` value for each step's doc.
- Mirror the existing dual-command guidance (activated `.venv` vs. `uv run`) already used elsewhere in the docs.
- Keep wording consistent with the Step 1 callout so the experience is uniform across steps.
Affected files:
- `docs/steps/02-tools.md`
- `docs/steps/03-mcp.md`
- `docs/steps/04-toolbox.md`
- `docs/steps/05-rag.md`
- `docs/steps/06-skills.md`
- `docs/steps/07-multi-agent.md`
- `docs/steps/08-workflow.md`
- `docs/steps/09-memory.md`
## Alternatives considered
- Only recommending preflight generically (no per-step callout) — rejected: less actionable and doesn't leverage the existing `--step` checks.
- Expanding preflight's per-step checks — out of scope here; this issue is purely about surfacing the existing capability in the docs.
---
_Migrated from pmalarme/foundry-workshop-template#57._
Contributor guide
Research direction
Start with the existing preflight callout at the top of docs/steps/01-basic.md, then review docs/steps/02-tools.md through docs/steps/09-memory.md. Add the matching dual-command guidance with the correct --step N value to each file, and verify that every step tells learners how to confirm they are ready using scripts/preflight.py.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 85/100