1# Python FAOS (Foundry Agent Optimization Service) Optimization Patterns
2 
3These patterns are framework-neutral. Use them to expose Python agent behavior knobs to FAOS while preserving the app's current runtime.
4 
5## Base Contract
6 
7Use this when there is one clear instructions/model surface.
8 
9```python
10import os
11 
12from agent_optimization import load_config
13 
14SYSTEM_PROMPT = """You are a helpful assistant."""
15 
16config = load_config(
17    default_instructions=SYSTEM_PROMPT,
18    default_model=os.getenv("MODEL_DEPLOYMENT_NAME", "gpt-4.1"),
19    default_skills_dir="skills",
20)
21```
22 
23Then map the resolved values into the existing framework:
24 
25```python
26instructions = config.compose_instructions()
27model = config.model or os.getenv("MODEL_DEPLOYMENT_NAME", "gpt-4.1")
28```
29 
30Only apply temperature if the framework supports it:
31 
32```python
33options = {}
34if config.temperature is not None:
35    options["temperature"] = config.temperature
36```
37 
38## Multi-Agent Named Targets
39 
40When a Python app has multiple agents, use names that match the architecture rather than one generic `config`.
41 
42```python
43orchestrator_config = load_config(
44    default_instructions=ORCHESTRATOR_PROMPT,
45    default_model=os.getenv("ORCHESTRATOR_MODEL_DEPLOYMENT_NAME", os.getenv("MODEL_DEPLOYMENT_NAME", "gpt-4.1")),
46    default_skills_dir="skills/orchestrator",
47)
48 
49tool_agent_config = load_config(
50    default_instructions=TOOL_AGENT_PROMPT,
51    default_model=os.getenv("TOOL_AGENT_MODEL_DEPLOYMENT_NAME", os.getenv("MODEL_DEPLOYMENT_NAME", "gpt-4.1")),
52    default_skills_dir="skills/tool-agent",
53)
54```
55 
56Use the evaluator objective to choose which named target to add first. For example, `intent_resolution` usually points to `orchestrator_config`, while `builtin.tool_call_accuracy` often points to `tool_agent_config`.
57 
58## Microsoft Agent Framework
59 
60Keep the current hosting adapter and agent construction. Replace only the selected knobs.
61 
62```python
63agent = Agent(
64    client=client,
65    instructions=config.compose_instructions(),
66    tools=existing_tools,
67    default_options=default_options,
68)
69```
70 
71For model selection:
72 
73```python
74client = FoundryChatClient(
75    project_endpoint=project_endpoint,
76    model=config.model or os.getenv("MODEL_DEPLOYMENT_NAME", "gpt-4.1"),
77    credential=credential,
78)
79```
80 
81If the model client is shared by multiple agents, flag this as a global side effect in the review summary.
82 
83## FastAPI or Custom Responses Runtime
84 
85Keep the existing HTTP contract. Use config values where the model call is created.
86 
87```python
88instructions = body.get("instructions", config.compose_instructions())
89model = body.get("model", config.model or os.getenv("MODEL_DEPLOYMENT_NAME", "gpt-4.1"))
90```
91 
92When the app already supports request-level overrides, preserve them and use FAOS config as the default.
93 
94## LangGraph or Workflow Runtimes
95 
96Do not rewrite the graph. Identify node-level prompts and model clients.
97 
98- Router/planner nodes are good targets for `intent_resolution`.
99- Tool nodes are good targets for `builtin.tool_call_accuracy`.
100- Final synthesis nodes are good targets for `relevance`, style, and task adherence.
101 
102Prefer node-specific config names:
103 
104```python
105router_config = load_config(
106    default_instructions=ROUTER_PROMPT,
107    default_model=default_model,
108)
109```
110 
111## Optional Skill Support
112 
113`default_skills_dir="skills"` records the default skill location. It does not automatically make the runtime load files or expose skill tools.
114 
115Add file-based skill support only when the target framework has a safe tool-calling or plugin mechanism. If adding it, use progressive disclosure:
116 
1171. Startup prompt contains skill name and description only
1182. Model calls a tool such as `load_skill` to load full skill instructions
1193. Model calls a file-reading tool only for deep skill assets when needed
120 
121Do not append every `SKILL.md` body into every agent prompt by default, especially in multi-agent architectures.
122 
123## Dependency Guidance
124 
125Add dependencies only when needed:
126 
127```text
128python-dotenv>=1.0.0
129azure-identity>=1.19.0
130```
131 
132Use `python-dotenv` when local `.env` support exists. Use `azure-identity` when the local resolver uses Entra tokens.
133 
134## Environment Variables
135 
136The canonical local `agent_optimization` package uses these optimization variables:
137 
138| Variable | Purpose |
139| -------- | ------- |
140| `AGENT_OPTIMIZATION_CONFIG` | Inline JSON config from the optimization service |
141| `OPTIMIZATION_CONFIG` | Non-reserved inline JSON fallback |
142| `AGENT_OPTIMIZATION_CANDIDATE_ID` | Candidate identifier to resolve from a service |
143| `AGENT_OPTIMIZATION_RESOLVE_ENDPOINT` | Resolver API base URL |
144| `AGENT_OPTIMIZATION_SKILLS_DIR` | Download location for candidate skill files |
145 
146Do not add all of these to `agent.yaml` by default. For hosted agent vNext, do not place `AGENT_*` variables in the user-authored deployment payload because they are platform-reserved there. Use the optimization service/runtime injection path or local development environment for `AGENT_OPTIMIZATION_*`, and use `OPTIMIZATION_CONFIG` only when an inline non-reserved fallback is explicitly needed.
147 
148Do not generate `FAOS_OPTIMIZATION_*` aliases in the base package unless the user explicitly requests a compatibility adapter. The reference package and FAOS contract use `AGENT_OPTIMIZATION_*` plus `OPTIMIZATION_CONFIG`.
149 
150## Canonical Local Package
151 
152When the target repository does not already provide an optimization package, add this split-file package rather than a single-file loader:
153 
154```text
155agent_optimization/
156    __init__.py
157    _config.py
158    _resolver.py
159```
160 
161`__init__.py` should only re-export the public API:
162 
163```python
164"""Agent optimization config loader for hosted agents."""
165 
166from agent_optimization._config import OptimizationConfig, Skill, load_config
167 
168__all__ = ["OptimizationConfig", "Skill", "load_config"]
169__version__ = "0.1.0"
170```
171 
172`_config.py` owns `Skill`, `OptimizationConfig`, `load_config`, default fallback behavior, inline config parsing, and candidate config handoff.
173 
174`_resolver.py` owns candidate resolution, using `{endpoint}/candidates/{candidate_id}/config` for resolved config, optional skill-file download from the candidate manifest, and `DefaultAzureCredential` with the `https://ml.azure.com/.default` scope.
175 
176## Verification Checklist
177 
178- Changed Python files compile
179- `from agent_optimization import load_config` succeeds from the agent root
180- `load_config(default_instructions="x", default_model="m")` returns defaults when no optimization env vars are set
181- Existing entrypoint, hosting adapter, and protocol remain unchanged
182- Multi-agent targets are named and documented
183- Evaluator objective influenced the target selection or was explicitly unavailable
184- User is asked to review before deployment
185