|
| 1 | +# azure-ai-agentserver-optimization |
| 2 | + |
| 3 | +Optimization config loader for Azure AI Hosted Agents. |
| 4 | + |
| 5 | +Provides a single `load_config()` call that resolves optimization parameters (instructions, model, temperature, skills, tool definitions) from multiple sources with graceful fallback — your agent works unchanged when not running under optimization. |
| 6 | + |
| 7 | +## Installation |
| 8 | + |
| 9 | +```bash |
| 10 | +pip install azure-ai-agentserver-optimization |
| 11 | +``` |
| 12 | + |
| 13 | +## Quick Start |
| 14 | + |
| 15 | +```python |
| 16 | +from azure.ai.agentserver.optimization import load_config |
| 17 | + |
| 18 | +config = load_config(default_instructions="You are a helpful assistant.") |
| 19 | + |
| 20 | +# Use config in your agent |
| 21 | +print(config.instructions) # optimized or default |
| 22 | +print(config.model) # optimized or default |
| 23 | +print(config.temperature) # optimized or default |
| 24 | +print(config.skills) # learned skills (empty list if none) |
| 25 | +print(config.tool_descriptions) # optimized tool descriptions (empty dict if none) |
| 26 | +print(config.source) # "api:candidate:abc", "env:OPTIMIZATION_CONFIG", "local:...", or "defaults" |
| 27 | +``` |
| 28 | + |
| 29 | +## Resolution Order |
| 30 | + |
| 31 | +`load_config()` resolves from four sources in order — first match wins: |
| 32 | + |
| 33 | +| Priority | Source | Env vars required | Description | |
| 34 | +|----------|--------|-------------------|-------------| |
| 35 | +| 1 | **Inline JSON** | `OPTIMIZATION_CONFIG` | Full config as a JSON string. Used by temporary agent versions during evaluation. | |
| 36 | +| 2 | **Resolver API** | `OPTIMIZATION_CANDIDATE_ID`, `OPTIMIZATION_JOB_ID`, `OPTIMIZATION_RESOLVE_ENDPOINT` | Fetches the candidate config from the remote optimization service and persists it to the local directory. | |
| 37 | +| 3 | **Local directory** | `OPTIMIZATION_LOCAL_DIR` (optional, defaults to `.agent_configs/`) | Reads from `<local_dir>/<candidate_id>/` or `baseline/` as fallback. | |
| 38 | +| 4 | **Defaults** | *(none)* | Returns the caller-supplied defaults unchanged — the agent works normally. | |
| 39 | + |
| 40 | +Any unexpected error is caught and logged — `load_config()` always returns a valid `OptimizationConfig`. |
| 41 | + |
| 42 | +## Environment Variables |
| 43 | + |
| 44 | +| Variable | Description | |
| 45 | +|----------|-------------| |
| 46 | +| `OPTIMIZATION_CONFIG` | Inline JSON config (Priority 1). | |
| 47 | +| `OPTIMIZATION_CANDIDATE_ID` | Candidate ID for resolver API or local folder lookup. | |
| 48 | +| `OPTIMIZATION_JOB_ID` | Job ID for the resolver API. | |
| 49 | +| `OPTIMIZATION_RESOLVE_ENDPOINT` | Base URL of the optimization service. | |
| 50 | +| `OPTIMIZATION_LOCAL_DIR` | Path to the local config directory (default: `.agent_configs/`). | |
| 51 | +| `MODEL_DEPLOYMENT_NAME` | Fallback model name when no model is resolved or specified. | |
| 52 | + |
| 53 | +## Local Directory Layout |
| 54 | + |
| 55 | +When using the local directory (Priority 3) or after the resolver API persists a candidate (Priority 2), the directory uses the following structure: |
| 56 | + |
| 57 | +``` |
| 58 | +.agent_configs/ |
| 59 | +├── baseline/ # fallback candidate |
| 60 | +│ ├── metadata.yaml # model, temperature, file pointers |
| 61 | +│ ├── instructions.md # system prompt |
| 62 | +│ ├── tools.json # tool descriptions (dict or OpenAI list format) |
| 63 | +│ └── skills/ # learned skills |
| 64 | +│ └── <skill_name>/ |
| 65 | +│ └── SKILL.md |
| 66 | +└── <candidate_id>/ # same layout as baseline/ |
| 67 | + ├── metadata.yaml |
| 68 | + ├── instructions.md |
| 69 | + ├── tools.json |
| 70 | + └── skills/ |
| 71 | + └── <skill_name>/ |
| 72 | + └── SKILL.md |
| 73 | +``` |
| 74 | + |
| 75 | +## Tool Description Formats |
| 76 | + |
| 77 | +`tools.json` and the inline JSON config support three formats: |
| 78 | + |
| 79 | +**Dict format** (`tool_descriptions`): |
| 80 | +```json |
| 81 | +{ |
| 82 | + "lookup_policy": { |
| 83 | + "description": "Look up the company travel policy.", |
| 84 | + "parameters": {"dept": "Department name"} |
| 85 | + } |
| 86 | +} |
| 87 | +``` |
| 88 | + |
| 89 | +**Legacy camelCase** (`toolDescriptions`) — same structure, different key. `tool_descriptions` takes priority when both are present. |
| 90 | + |
| 91 | +**OpenAI function-calling list** (`tools`): |
| 92 | +```json |
| 93 | +[ |
| 94 | + { |
| 95 | + "type": "function", |
| 96 | + "function": { |
| 97 | + "name": "lookup_policy", |
| 98 | + "description": "Look up the company travel policy.", |
| 99 | + "parameters": { |
| 100 | + "type": "object", |
| 101 | + "properties": { |
| 102 | + "dept": {"type": "string", "description": "Department name"} |
| 103 | + } |
| 104 | + } |
| 105 | + } |
| 106 | + } |
| 107 | +] |
| 108 | +``` |
| 109 | + |
| 110 | +## OptimizationConfig Properties |
| 111 | + |
| 112 | +| Property | Type | Description | |
| 113 | +|----------|------|-------------| |
| 114 | +| `instructions` | `str` | System prompt (optimized or default). | |
| 115 | +| `model` | `str \| None` | Model deployment name. | |
| 116 | +| `temperature` | `float \| None` | Sampling temperature. | |
| 117 | +| `skills` | `list[Skill]` | Learned skills. | |
| 118 | +| `skills_dir` | `str \| None` | Path to skills directory. | |
| 119 | +| `tool_descriptions` | `dict[str, ToolDescription]` | Optimized tool descriptions. | |
| 120 | +| `source` | `str` | Where the config was loaded from. | |
| 121 | +| `candidate_id` | `str \| None` | Candidate ID (when resolved via API). | |
| 122 | +| `job_id` | `str \| None` | Job ID (when resolved via API). | |
| 123 | +| `has_skills` | `bool` | Whether skills are available. | |
| 124 | +| `has_tool_descriptions` | `bool` | Whether tool descriptions are available. | |
| 125 | + |
| 126 | +## Contributing |
| 127 | + |
| 128 | +This project welcomes contributions and suggestions. See [CONTRIBUTING.md](https://github.com/Azure/azure-sdk-for-python/blob/main/CONTRIBUTING.md) for details. |
0 commit comments