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 
136Supported 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. Add only the variables required for the user's intended optimization path.
147 
148## Verification Checklist
149 
150- Changed Python files compile
151- `from agent_optimization import load_config` succeeds from the agent root
152- `load_config(default_instructions="x", default_model="m")` returns defaults when no optimization env vars are set
153- Existing entrypoint, hosting adapter, and protocol remain unchanged
154- Multi-agent targets are named and documented
155- Evaluator objective influenced the target selection or was explicitly unavailable
156- User is asked to review before deployment
157