1# Agent Optimizer in Foundry — Scaffold Python Agent
2 
3Prepare an existing Python hosted agent for Agent Optimizer in Foundry, then run optimization, apply the selected candidate locally, and deploy through azd after review.
4 
5## When to Use This Skill
6 
7USE FOR: make my Python agent optimizable with Agent Optimizer in Foundry, scaffold optimizer config, add `load_config`, prepare `.agent_configs`, configure eval.yaml, run azd ai agent optimize, apply optimizer candidate, deploy optimized agent.
8 
9DO NOT USE FOR: non-Python agents, prompt agents, running standalone batch evaluations, prompt optimization of an already deployed agent, or general Foundry deployment. For normal deployment, use [deploy](../deploy/deploy.md). For eval analysis loops, use [observe](../observe/observe.md).
10 
11## Quick Reference
12 
13| Property | Value |
14| -------- | ----- |
15| Phase | Scaffold, optimize, apply locally, deploy |
16| Supported language | Python |
17| Required runtime | azd project with hosted agent |
18| Required package | `azure-ai-agentserver-optimization` |
19| Required import | `from azure.ai.agentserver.optimization import load_config` |
20| Required baseline | `.agent_configs/baseline/` beside `agent.yaml` |
21| Supported targets | instruction, model, skill folder, function tool definitions |
22| azd setup | [azd Setup](references/azd-setup.md) |
23| Detailed scaffold steps | [Scaffold Workflow](references/scaffold.md) |
24| Python/file patterns | [Python Patterns](references/python-patterns.md) |
25| Eval config | [eval.yaml Guidance](references/eval-yaml.md) |
26| Optimize flow | [Optimize Workflow](references/optimize-workflow.md) |
27 
28## High-Level Lifecycle
29 
301. **Prepare azd:** Verify azd, login, and `azure.ai.agents` extension with [azd Setup](references/azd-setup.md).
312. **Scaffold:** Follow [Scaffold Workflow](references/scaffold.md) when SDK wiring or `.agent_configs/baseline/` is missing; stop for review if files changed.
323. **Configure eval:** Create or update `eval.yaml` using [eval.yaml Guidance](references/eval-yaml.md).
334. **Optimize:** Run and monitor `azd ai agent optimize` with [Optimize Workflow](references/optimize-workflow.md).
345. **Apply and deploy:** Apply the selected candidate locally, review the diff, then deploy with `azd deploy`.
35 
36## Workflow
37 
381. Resolve the target agent root and confirm it is a Python hosted agent.
392. Read [azd Setup](references/azd-setup.md), then [Scaffold Workflow](references/scaffold.md) if scaffolding is needed.
403. Read [eval.yaml Guidance](references/eval-yaml.md) and configure optimization inputs from known dataset/evaluator context.
414. Read [Optimize Workflow](references/optimize-workflow.md), run optimization, and ask before applying a candidate.
425. After local review and approval, deploy with `azd deploy`, then invoke via [invoke](../invoke/invoke.md).
43 
44## Guardrails
45 
46- Target hosted Python agents only.
47- Preserve existing frameworks, tools, hosting adapters, protocols, and entrypoints.
48- Do not use one global scaffold across multi-agent roles unless the architecture already has one global prompt/model or the user approves.
49- Keep edits scoped to the selected agent root.
50- Do not apply candidates or deploy automatically; stop for review first.
51- Prefer `azd ai agent optimize apply --candidate` plus `azd deploy` over direct optimize deploy so source changes are reviewable.
52