1# Scaffold Workflow
2 
3Use this workflow to make a Python agent optimizable before running Agent Optimizer in Foundry.
4 
5## Step 1: Resolve Target and Goal
6 
7Stay inside the selected agent root. Confirm the project is Python using `requirements.txt`, `pyproject.toml`, `setup.py`, or Python entrypoints.
8 
9Identify the optimization goal from user input, selected `evaluationSuites[]`, `.foundry/evaluators/*`, recent result summaries, datasets, or code/test comments. If the goal is unclear, proceed conservatively and explain that evaluator-specific targeting improves optimization quality.
10 
11## Step 2: Inventory Safe Targets
12 
13Scan for instructions, model selection, skill folders, function tool definitions, topology, and hosting entrypoint. Record file path, symbol/name, role, current value, and whether it is safe to expose through the optimizer.
14 
15Classify topology as single-agent, orchestrator/supervisor, specialist tool-agent, peer multi-agent, or unknown runtime. Do not collapse role-specific prompts into one global prompt. Ask before editing when multiple scopes are plausible.
16 
17Use [Python Patterns](python-patterns.md#target-selection) to map evaluator/dataset goals to the smallest useful baseline.
18 
19## Step 3: Scaffold Baseline Files
20 
21Create the required `.agent_configs/baseline/` folder beside `agent.yaml`:
22 
23```text
24.agent_configs/
25  baseline/
26    metadata.yaml
27    instructions.md
28    tools.json
29    skills/<skill-name>/SKILL.md
30```
31 
32`metadata.yaml` points to selected baseline files:
33 
34```yaml
35model: <existing-chat-model-deployment-name>
36temperature: 0.7
37instruction_file: instructions.md
38skill_dir: skills
39tool_file: tools.json
40```
41 
42Write the selected baseline prompt to `instructions.md`. Include only relevant skills under `skills/`. Use `tools.json` only for OpenAI function-calling tool definitions; see [Python Patterns](python-patterns.md#tools-file).
43 
44Choose a `model` value that already exists as a model deployment in the target Foundry project.
45 
46Do not use code-level defaults as the optimization baseline.
47 
48## Step 4: Install and Wire SDK
49 
50Add `azure-ai-agentserver-optimization` to the target agent project's dependency file:
51 
52```text
53azure-ai-agentserver-optimization
54```
55 
56Wire the agent with no default parameters:
57 
58```python
59from azure.ai.agentserver.optimization import load_config
60 
61config = load_config()
62```
63 
64Map resolved values:
65 
66- Instructions -> `config.compose_instructions()`
67- Model -> `config.model`
68- Skills -> `config.skills_dir` with `load_skills_from_dir(...)` only when the runtime has a safe skill/tool mechanism
69- Function tool definitions -> `config.apply_tool_descriptions(tools)` when tool metadata can be patched safely
70 
71Do not add optimization runtime env vars to `agent.yaml`. The default local config path is `.agent_configs/`; use `load_config(config_dir="...")` only when the scaffold intentionally uses a non-default local config directory.
72 
73## Step 5: Verify and Stop
74 
75Run Python syntax checks, SDK import smoke test, baseline config smoke test with no-arg `load_config()`, workspace diagnostics, and cheap relevant project tests.
76 
77End with a review checkpoint. Summarize changed files, optimization targets, evaluator goals, global side effects, and verification. Do not deploy automatically.
78 
79After user review, continue with [Optimize Workflow](optimize-workflow.md).
80