141 lines
4.0 KiB
Markdown
141 lines
4.0 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
azure-ai-agentserver-optimization
|
|
```
|
|
|
|
Import from the SDK namespace:
|
|
|
|
```python
|
|
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):
|
|
|
|
```text
|
|
<agent-root>/
|
|
main.py
|
|
.agent_configs/
|
|
baseline/
|
|
metadata.yaml
|
|
instructions.md
|
|
tools.json
|
|
skills/<skill-name>/SKILL.md
|
|
```
|
|
|
|
Example `metadata.yaml`:
|
|
|
|
```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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```python
|
|
config = load_config()
|
|
instructions = config.compose_instructions()
|
|
model = config.model
|
|
```
|
|
|
|
For Microsoft Agent Framework:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
config.apply_tool_descriptions(tools)
|
|
```
|
|
|
|
Load skills on demand when the runtime has a safe skill/tool mechanism:
|
|
|
|
```python
|
|
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:
|
|
|
|
| Signal | Prefer |
|
|
| ------ | ------ |
|
|
| `relevance`, `task_adherence` | primary instructions and model |
|
|
| `intent_resolution` | router/orchestrator instructions |
|
|
| `builtin.tool_call_accuracy` | tool-calling instructions and OpenAI function tool definitions |
|
|
| safety/groundedness | safety, retrieval, citation, or answer-synthesis instructions |
|
|
|
|
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
|