/microsoft-foundry

Scaffold Workflow

Use this workflow to make a Python agent optimizable before running Agent Optimizer in Foundry.

Step 1: Resolve Target and Goal

Stay inside the selected agent root. Confirm the project is Python using requirements.txt, pyproject.toml, setup.py, or Python entrypoints.

Identify 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.

Step 2: Inventory Safe Targets

Scan 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.

Classify 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.

Use Python Patterns to map evaluator/dataset goals to the smallest useful baseline.

Step 3: Scaffold Baseline Files

Create the required .agent_configs/baseline/ folder in the agent's service source directory (beside the entry point):

.agent_configs/
  baseline/
    metadata.yaml
    instructions.md
    tools.json
    skills/<skill-name>/SKILL.md

metadata.yaml points to selected baseline files:

model: <existing-chat-model-deployment-name>
temperature: 0.7
instruction_file: instructions.md
skill_dir: skills
tool_file: tools.json

Write 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.

Choose a model value that already exists as a model deployment in the target Foundry project.

Do not use code-level defaults as the optimization baseline.

Step 4: Install and Wire SDK

Add azure-ai-agentserver-optimization to the target agent project's dependency file:

azure-ai-agentserver-optimization

Wire the agent with no default parameters:

from azure.ai.agentserver.optimization import load_config

config = load_config()

Map resolved values:

• Instructions -> config.compose_instructions()
• Model -> config.model
• Skills -> config.skills_dir with load_skills_from_dir(...) only when the runtime has a safe skill/tool mechanism
• Function tool definitions -> config.apply_tool_descriptions(tools) when tool metadata can be patched safely

Do not add optimization runtime env vars to the agent's environmentVariables in azure.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.

Step 5: Verify and Stop

Run Python syntax checks, SDK import smoke test, baseline config smoke test with no-arg load_config(), workspace diagnostics, and cheap relevant project tests.

End with a review checkpoint. Summarize changed files, optimization targets, evaluator goals, global side effects, and verification. Do not deploy automatically.

After user review, continue with Optimize Workflow.