/microsoft-foundry

Python Agent Optimizer in Foundry Patterns

Use the Azure SDK optimization package and a local baseline folder. The baseline is file-based; call load_config() without code-level fallback parameters.

Install and Import

Add azure-ai-agentserver-optimization to requirements.txt or the project dependency file:

azure-ai-agentserver-optimization

Import from the SDK namespace:

from azure.ai.agentserver.optimization import load_config

Baseline Folder

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

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

Example metadata.yaml:

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

instructions.md contains the selected baseline system/developer instructions. Include only skill folders relevant to the optimization goal.

Choose a model value that already exists as a model deployment in the target Foundry project. Do not assume gpt-4o is available.

Tools File

Use OpenAI function-calling tool objects under top-level tools. Currently, only function tool definition optimization is supported:

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "lookup_policy",
        "description": "Look up the company travel policy.",
        "parameters": {
          "type": "object",
          "properties": {
            "dept": {
              "type": "string",
              "description": "Department name"
            }
          }
        }
      }
    }
  ]
}

Runtime Wiring

Call load_config() with no defaults:

config = load_config()
instructions = config.compose_instructions()
model = config.model

For Microsoft Agent Framework:

client = FoundryChatClient(
    project_endpoint=project_endpoint,
    model=config.model,
    credential=credential,
)

agent = Agent(
    client=client,
    instructions=config.compose_instructions(),
    tools=tools,
)

Patch optimized function tool definitions through the public helper. It updates matching function docs, descriptions, and parameter descriptions:

config.apply_tool_descriptions(tools)

Load skills on demand when the runtime has a safe skill/tool mechanism:

from pathlib import Path
from azure.ai.agentserver.optimization import load_skills_from_dir

skills = load_skills_from_dir(Path(config.skills_dir)) if config.skills_dir else []

Target Selection

Use evaluator and dataset goals to decide what belongs in the baseline:

For multi-agent apps, scaffold the target role's instructions and related skills/tools. Do not merge unrelated role prompts into one baseline.

Runtime Config

The SDK reads optimization context from supported runtime sources. Keep .agent_configs/baseline/ present so default load_config() startup has a local baseline. Use load_config(config_dir="my_configs") only for non-default local config directories, and load_config(required=False) only when the app can intentionally run without optimization config.

Verification Checklist

• Dependency file includes azure-ai-agentserver-optimization
• from azure.ai.agentserver.optimization import load_config succeeds
• .agent_configs/baseline/metadata.yaml exists and points to existing files
• load_config() is called without defaults unless using an intentional config_dir or required=False
• Changed Python files compile and preserve the hosting adapter/protocol
• User is asked to review before deployment