1# Optimize Workflow
2 
3Use this after azd setup and scaffold review are complete.
4 
5## 1. Prepare context
6 
71. Resolve the hosted agent with [azd Setup](azd-setup.md).
82. If SDK wiring or `.agent_configs/baseline/` is missing, run [Scaffold Workflow](scaffold.md) first.
93. If scaffolding changed files, stop and ask the user to review before optimization.
104. Ensure `eval.yaml` exists using [eval.yaml Guidance](eval-yaml.md), generate it with `azd ai agent eval generate`, or ask whether to use built-in optimize defaults.
115. Before setting `--optimize-model` or `options.optimization_model`, verify the project has an existing deployment from the allowed optimizer list: `GPT-5`, `GPT-5.1`, `GPT-5.2`, `GPT-5.4`, `GPT-5.5`, `DeepSeek-V4-Pro`, or `DeepSeek-V-3.2`.
12 
13When evaluation inputs are not already selected, generate them from a reviewed seed dataset or regenerate defaults:
14 
15```bash
16azd ai agent eval generate --dataset <path-to-jsonl>
17azd ai agent eval generate --reset-defaults
18```
19 
20## 2. Run optimize
21 
22Run from the azd project/agent root:
23 
24```bash
25azd ai agent optimize --optimize-model <allowed-optimizer-model-deployment-name>
26```
27 
28If multiple services are detected, let azd prompt or ask the user which service to use. If `eval.yaml` exists or was generated, use it when it matches the selected agent; otherwise ask before regenerating or ignoring it.
29 
30## 3. Monitor
31 
32Use these when the job is long-running or the user asks:
33 
34```bash
35azd ai agent optimize status <operation-id> --watch
36azd ai agent optimize list
37azd ai agent optimize cancel <operation-id>
38```
39 
40Capture the operation ID, portal URL, scores, and candidate IDs from output.
41 
42## 4. Apply locally
43 
44Recommend the best candidate, then ask before applying:
45 
46```bash
47azd ai agent optimize apply --candidate <candidate-id>
48```
49 
50After apply, show the source diff and summarize changed files, prompts, model/temperature, tools, and skills.
51 
52## 5. Deploy after review
53 
54In azd environments, prefer local apply plus:
55 
56```bash
57azd deploy
58```
59 
60Do not use `azd ai agent optimize deploy --candidate <candidate-id>` unless the user explicitly requests it. Local apply keeps optimized changes visible for source control review.
61