Azure-Samples / Azure-Samples/foundry-hosted-agents-workshop

[Feature] Add a per-step preflight callout to every step (02-09)

Open Beginner friendly
#6 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.