Environment setup reference · access, authorization, and cleanup

Ten steps from the beginning · Lab checklist · Troubleshooting

Use this reference for your own steps 02 provisioning, 03 Agent setup, and 10 cleanup. Follow the hands-on guide in order and open only the linked sections you need. Notes are optional; keep short ones only in 07, 09, and 10 (see where the lab keeps its records).

Command shortcuts: Codespaces · CLI sign-in · Quick provisioning · Policies/Agent · Evaluation IDs · Reevaluation · Group deletion/verification. Run commands from your selected lab folder's terminal; do not repeat completed work.

To read inside unchanged commands, open 02 creation code/portal, 03 retrieval code/portal, Agent configuration, 09 submission/lookup, and 10 cleanup scope. Source panels are read-only, not instructions to run another program or duplicate creation in the portal.

Prepare your dedicated lab environment

Verify CLI, SDK, and portal identities separately and use the same personal identity throughout. Never use another person's tokens, sign-in session, configuration, or ownership records. Run creation, ID lookup, v2 creation, reevaluation, and cleanup yourself.

Every participant uses their own dedicated environment and Agent. Do not have several people create the same Agent's v2 or submit the same paid job. The same example environment name on separate computers still produces Microsoft Azure resource names with unique suffixes.

Access and spending authorization are required starting conditions. Obtain an approved scope through organizational procedures if needed. This is not an alternative path where someone else performs the remaining exercises.

Default Agent names are lab-en-iq for English and lab-ko-iq for Korean. If the environment name changes, use the actual name returned by the CLI in every later step.

The program reads language and record settings

The default lab requires no environment-variable commands. bootstrap setup --environment lab-en saves English in the plan; lab-ko saves Korean. Names such as lab-en-02 and lab-ko-02 are supported too. Subsequent commands read LAB_LANGUAGE and LAB_ARTIFACTS_DIR from the generated .env through --config. Relative record paths resolve beside the configuration file.

If an older .env lacks language, it is inferred from the lab-en/lab-ko rule in LAB_PREFIX without rewriting the file or plan hash. Only legacy custom names outside that rule and separate tools with no selected configuration keep their existing environment-variable/default behavior. Those variables are not additional setup for the default lab.

Existing records are never moved or merged automatically. If earlier work used shared artifacts/ or another location, first compare the original configuration with the project, prefix, and language in workspace.json. Do not launch paid work against a different record folder or edit the original .env/manifest to bypass ownership checks.

Verify model roles and actual deployments

Numbers are requested ARM capacity units, not a universal TPM conversion. These defaults require availability checks; they are not a deployment guarantee for every subscription. Inspect deployment names, model names, versions, and readiness in Microsoft Foundry Models + endpoints/Build → Models. .env contains actual deployment names rather than product names.

The embedding model must match the index contract. The policy index uses 3072-dimensional text-embedding-3-large vectors, and embedding_supported_model in preflight checks the deployed model. An environment created with the former default text-embedding-3-small reports BLOCKED. Do not edit its plan or deployment; plan a new environment name instead.

Distinguish additional monitoring resources. Application Insights can automatically add a default Failure Anomalies alert and Smart Detection action group. Bootstrap checks read-only that the alert targets only the owned Application Insights component and that the linked action group uses only the default role receivers. It does not adopt resources by name or modify/delete a shared action group in another resource group. If those links are not yet observable during provisioning, inspect the same bootstrap status again; do not edit the manifest or delete the alert to bypass the check.

Set TPM before starting model calls

The step-02 recommendations require 100,000 TPM per Agent, Judge, and shared Optimizer/planner deployment, and 10,000 TPM for embeddings. This assumes sequential jobs in one environment; quota pools remain model/SKU/region-specific. Sum per-model allocations across simultaneous dedicated environments. Count the Optimizer/planner deployment shared within one environment only once.

1. New dedicated environment: Check generative capacity 100 and embedding capacity 10 in the updated bootstrap plan, then authorize and provision that exact plan. Existing plans do not change automatically. For an unprovisioned lower-capacity plan, prepare a new environment name and authorization rather than editing the hashed plan.
2. Inspect actual deployments: Read Tokens per Minute Rate Limit under Microsoft Foundry Build → Models → Deployments → deployment name → Details. Distinguish capacity displayed in thousands of tokens from the final TPM value. Changing only the portal's Edit setting for this bootstrap environment causes plan drift. If insufficient, inspect the plan, actual limit, and authorization; prepare a newly authorized dedicated environment with sufficient capacity when needed. Never edit hashes or approvals to bypass checks.
3. Verify the setting: With that environment's .env and language-specific artifacts path, run the read-only check below. Inspect each *_tpm entry's observed, expected, and reason.

Run in your terminal · Shared terminal

python -m lab --config .lab/lab-en/.env preflight

Continue to step-03 smoke/retrieval and later evaluation/Optimizer only after overall status: PASS and all five TPM checks pass. The checker reads the actual deployment's rateLimits entry with key: token. If the CLI omits labels, it reads raw ARM metadata for that same deployment instead of guessing TPM from request counts or sku.capacity. Unverifiable limits are BLOCKED.

TPM accounting uses estimates rather than average billed tokens; RPM and short-window burst limits also apply. Allow more headroom for longer inputs/maximum outputs, shared users, and overlapping evaluation/optimization. These recommended minimums do not guarantee a 429-free run. See official rate-limit guidance.

Use the real response check in 03 to verify Agent and knowledge_base_retrieve calls. Optimizer has a separate supported-model list; Agent/Judge availability does not establish generator support.

Prepare an executable Agent

01's Codespaces path prepares Python 3.12 within the supported 3.11–3.14 range, Git, Azure CLI, and the virtual environment. Only the local-computer path needs OS-specific installation and new-terminal version checks. Sign in, then run quick provisioning; language and record location are set automatically too. Do not treat fake IDs in .env.example as a live environment.

Use prompts/en/baseline.txt for English and prompts/baseline.txt for Korean. Never weaken the baseline to manufacture improvement. After policy upload and retrieval verification succeed, create a policy-connected v1:

Run in your terminal · Shared terminal

python -m lab --config .lab/lab-en/.env native-agent --version 1 --confirm

native-agent uses ensure_fixed_release to allow only 1 and 2, comparing local workspace ownership with remote metadata. It reuses matching configurations, rejects a different v2, and never creates v3. It also retains a model-deployment snapshot and rejects drift. Receipts agents/native-v1.json, agents/native-v2.json, and agents/native-model.json belong to that environment's artifacts folder.

native_response_format() projects the common schema into the supported strict-generation subset. Citation uniqueness and needs_human/route consistency still require post-generation checks. Valid JSON does not establish policy correctness.

Creating v2 is not completing evaluation. Create one v2 from the complete instructions reviewed in 08, run the same managed evaluation in 09, then decide whether to accept it. Use only released v1/v2; separate draft-… experiments are outside this lab. Do not publish the created v2 to production.

Run in your terminal · Shared terminal

python -m lab --config .lab/lab-en/.env native-agent --version 2 --prompt .lab/lab-en/candidate.txt --confirm

Do not use portal Promote in this lab; create v2 with 09's CLI. Promoting first can conflict with the CLI's local/remote ownership checks. V1/v2 are complete Agent versions; the same Agent, model, tools, and output settings must differ only in instructions.

Retrieve IDs with 06's complete lookup command, including the .env path and exact evaluation name. The reevaluation helper copies the baseline data source and checks the remote contract. Do not replace the remote definition with a stale local JUDGE_DEPLOYMENT.

Freeze the comparison conditions

Catalog evaluator versions are not proof that the private service rubric is fully pinned. Preserve the actual definition, settings and this limitation. A passing gate on reused dev12 does not guarantee future scores, independent generalization or production approval.

The required comparison uses Compare runs in Microsoft Foundry in 09. scripts/compare_foundry_eval.py is an optional standalone tool, not another command required in this path. When using it separately, its --language ko/--language en option selects report language and default dev12; match any explicit dataset to that language.

Check evaluation response mappings

Select the two evaluators and Judge in 05 and preserve automatic mappings. The following table supports missing-field or mismatch checks; a normal wizard flow does not require guessing SDK fields and entering them manually.

If a required field is Unassigned, confirm the target is Agent, not Dataset, and inspect the query column and actual generated response mapping. Before submission, inspect the wizard; afterward, inspect the saved remote definition. Never map the reference answer as the response or copy old UI bindings. Use the official portal guide and response-mapping explanation. Do not submit until resolved. The helper in 09 checks the remote contract too.

Complete the actual authorization file

Quick bootstrap setup creates the same approval file through guided inputs. If already created, this table is for inspection; do not recreate or edit the file unnecessarily. Fill it manually only for the individual-command path or different actually authorized limits.

Open .lab/lab-en/approval.example.json and Save As approval.json in the same folder. Set limits yourself only if you can authorize spending and changes; otherwise follow the organizational approval procedure. Keep actual authorization evidence private. Neither this worksheet nor the JSON file independently proves approval or a signature. Use double quotes for JSON strings, but not for numbers, true, false, or null.

Validate with 02's bootstrap preflight --config ... --approval ... and read approval_reason on failure. Authorization covers only the exact plan hash, models, and retention scope. It does not authorize another lab, an automatic retry, or deletion.

Enforcement boundary: Bootstrap checks authorization validity, provisioning scope, and its wait bound. JSON budget and call limits do not automatically cap all Microsoft Azure or Optimizer spending. Budget alerts are not cutoffs. Monitor actual usage yourself and cancel jobs or clean up within the authorized scope.

Verify permissions and provider registration

Follow the current Microsoft Foundry RBAC guidance. Foundry User/Owner/Account Owner/Project Manager may still appear under their former Azure AI User/Owner/Account Owner/Project Manager names.

Use Access control (IAM) → Check access to inspect active assignments and Scope. Older UI versions may use View my access. The actual subscription/access illustration in 01 demonstrates inspection of existing access, not adding roles.

Authorized bootstrap assigns runtime roles at the new resources' scopes. It does not add subscription-wide roles. After creation, distinguish your user identity from service managed identities and use 03's actual tool call to verify propagation and data-plane access.

A provider registration enables a service type in your subscription. Follow the official provider-registration instructions:

1. Open the Azure portal → Subscriptions → your subscription → Resource providers.
2. Search for Microsoft.CognitiveServices, Microsoft.Search, Microsoft.OperationalInsights, and Microsoft.Insights; confirm Registered for each.
3. Select a missing provider and Register only with your own /register/action permission and authorization. Do not register unrelated providers in bulk.
4. After registration/propagation, rerun the same preflight. If access is missing, obtain an approved execution scope before resuming. Bootstrap never auto-registers providers or expands permissions.

Allow registration/role propagation, then rerun the same preflight. For continuing 403, compare identity, role scope, and network access. Do not grant new subscription-wide Owner, disable network or organizational policies, or transfer tokens as a shortcut.

Costs and operational boundaries

Evaluation invokes the Agent and Judge; optimization makes additional internal calls. Search and monitoring can continue to incur charges after the lab page closes. Distinguish measured tokens, cost estimates, and actual billing; unknown billing is not zero.

In the Azure portal → Cost Management → Cost analysis, select the subscription, resource group, and date range. Configure authorized budget alerts where needed, but do not treat them as enforced caps. Keep the actual budget, end time, and deletion/retention plan somewhere you can find them again; the optional worksheet has a place for them.

Optional worksheet for actual values and completion evidence

This worksheet is optional; nothing in the lab reads it. If your organization or your own habits call for a fuller record, copy this table into your own notes (for example .lab/lab-en/notes.md), mark unexecuted items not run, and fill in actual values as each step completes. “The environment is ready” is not sufficient evidence.

Keep English and Korean source data and private lab records separate; do not relabel another language's results as a new execution.

Raw service files can contain account metadata, tokens or signed URLs. Keep those local; the synthetic evaluation results themselves are not secret. Publish only allowlisted fields, including failures, and exclude credentials—not inconvenient outcomes. Historical attempts stay in the private audit, not as additional current-version reports.

Verify deletion and retention

Use step 10 as the exit checklist. Provisioning approval is not deletion approval, and workshop documentation does not authorize deleting another person's resources.