1# Python Agent Optimizer in Foundry Patterns
2 
3Use the Azure SDK optimization package and a local baseline folder. The baseline is file-based; call `load_config()` without code-level fallback parameters.
4 
5## Install and Import
6 
7Add `azure-ai-agentserver-optimization` to `requirements.txt` or the project dependency file:
8 
9```text
10azure-ai-agentserver-optimization
11```
12 
13Import from the SDK namespace:
14 
15```python
16from azure.ai.agentserver.optimization import load_config
17```
18 
19## Baseline Folder
20 
21Create `.agent_configs/baseline/` beside `agent.yaml`:
22 
23```text
24<agent-root>/
25  agent.yaml
26  .agent_configs/
27    baseline/
28      metadata.yaml
29      instructions.md
30      tools.json
31      skills/<skill-name>/SKILL.md
32```
33 
34Example `metadata.yaml`:
35 
36```yaml
37model: <existing-chat-model-deployment-name>
38temperature: 0.7
39instruction_file: instructions.md
40skill_dir: skills
41tool_file: tools.json
42```
43 
44`instructions.md` contains the selected baseline system/developer instructions. Include only skill folders relevant to the optimization goal.
45 
46Choose a `model` value that already exists as a model deployment in the target Foundry project. Do not assume `gpt-4o` is available.
47 
48## Tools File
49 
50Use OpenAI function-calling tool objects under top-level `tools`. Currently, only function tool definition optimization is supported:
51 
52```json
53{
54  "tools": [
55    {
56      "type": "function",
57      "function": {
58        "name": "lookup_policy",
59        "description": "Look up the company travel policy.",
60        "parameters": {
61          "type": "object",
62          "properties": {
63            "dept": {
64              "type": "string",
65              "description": "Department name"
66            }
67          }
68        }
69      }
70    }
71  ]
72}
73```
74 
75## Runtime Wiring
76 
77Call `load_config()` with no defaults:
78 
79```python
80config = load_config()
81instructions = config.compose_instructions()
82model = config.model
83```
84 
85For Microsoft Agent Framework:
86 
87```python
88client = FoundryChatClient(
89    project_endpoint=project_endpoint,
90    model=config.model,
91    credential=credential,
92)
93 
94agent = Agent(
95    client=client,
96    instructions=config.compose_instructions(),
97    tools=tools,
98)
99```
100 
101Patch optimized function tool definitions through the public helper. It updates matching function docs, descriptions, and parameter descriptions:
102 
103```python
104config.apply_tool_descriptions(tools)
105```
106 
107Load skills on demand when the runtime has a safe skill/tool mechanism:
108 
109```python
110from pathlib import Path
111from azure.ai.agentserver.optimization import load_skills_from_dir
112 
113skills = load_skills_from_dir(Path(config.skills_dir)) if config.skills_dir else []
114```
115 
116## Target Selection
117 
118Use evaluator and dataset goals to decide what belongs in the baseline:
119 
120| Signal | Prefer |
121| ------ | ------ |
122| `relevance`, `task_adherence` | primary instructions and model |
123| `intent_resolution` | router/orchestrator instructions |
124| `builtin.tool_call_accuracy` | tool-calling instructions and OpenAI function tool definitions |
125| safety/groundedness | safety, retrieval, citation, or answer-synthesis instructions |
126 
127For multi-agent apps, scaffold the target role's instructions and related skills/tools. Do not merge unrelated role prompts into one baseline.
128 
129## Runtime Config
130 
131The 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.
132 
133## Verification Checklist
134 
135- Dependency file includes `azure-ai-agentserver-optimization`
136- `from azure.ai.agentserver.optimization import load_config` succeeds
137- `.agent_configs/baseline/metadata.yaml` exists and points to existing files
138- `load_config()` is called without defaults unless using an intentional `config_dir` or `required=False`
139- Changed Python files compile and preserve the hosting adapter/protocol
140- User is asked to review before deployment
141