Add Microsoft Foundry (azure-ai-projects v2) Python instructions 🤖🤖🤖

[passadis]

Pull Request Checklist

• I have read and followed the CONTRIBUTING.md guidelines.
• I have read and followed the Guidance for submissions involving paid services.
• My contribution adds a new instruction, prompt, agent, skill, workflow, or canvas extension file in the correct directory.
• The file follows the required naming convention.
• The content is clearly structured and follows the example format.
• I have tested my instructions, prompt, agent, skill, workflow, or canvas extension with GitHub Copilot.
• I have run npm start and verified that README.md is up to date.
• I am targeting the main branch for this pull request.

---

Description

Adds instructions/microsoft-foundry.instructions.md — guidance for building agents with the Microsoft Foundry SDK (azure-ai-projects v2) in Python.

Why it adds uplift beyond default model behavior: azure-ai-projects was substantially reshaped in v2. Default Copilot output (trained on 1.x / the old azure-ai-agents thread-run-message API) generates code that no longer works — e.g. create_agent / threads.create / runs.create_and_process_run / messages.list. This file encodes the current, correct pattern: versioned agents via agents.create_version(... PromptAgentDefinition ...), interaction through the OpenAI-compatible client (get_openai_client → Responses + Conversations), tool attachment in the definition, the client-side FunctionTool loop, allow_preview semantics, and version-based canary rollout. Every snippet is derived from the official v2 SDK samples.

---

Type of Contribution

• New instruction file.
• New prompt file.
• New agent file.
• New plugin.
• New skill file.
• New agentic workflow.
• New canvas extension.
• Update to existing instruction, prompt, agent, plugin, skill, workflow, or canvas extension.
• Other (please specify):

---

Additional Notes

This file is grounded in a repeatedly observed real-world failure mode: in Copilot-assisted Foundry projects, Copilot defaults to the deprecated thread/run/message API, fails the first attempts, and only recovers after re-checking Microsoft Learn / the Microsoft Docs MCP server and re-coding against v2. These instructions front-load that correction so working v2 code is produced on the first pass. Verified against the official azure-ai-projects>=2.0.0 samples; ran npm start and confirmed the README tables are up to date.

🤖 This PR was prepared with AI-agent assistance (disclosed per repo convention via the title marker).

---

By submitting this pull request, I confirm that my contribution abides by the Code of Conduct and will be licensed under the MIT License.

[github-actions]

🔒 PR Risk Scan Results

Scanned 1 changed file(s).

Severity	Count
🔴 High	0
🟠 Medium	1
ℹ️ Info	0

Severity	Rule	File	Line	Match
🟠	unpinned-version-indicator	instructions/microsoft-foundry.instructions.md	14	``- Install: pip install "azure-ai-projects>=2.3.0" (async also needs `pip install aiohttp`). Use 2.3.0+ — the documented flow below relies on APIs added across the 2.x line (```

This is an automated soft-gate report. Findings indicate review targets and do not block merge by themselves.

[Copilot]

Pull request overview

Adds Python instructions for Microsoft Foundry’s azure-ai-projects v2 SDK and publishes them in the instruction catalog.

Changes:

• Documents versioned agents, conversations, tools, and lifecycle guidance.
• Adds the instruction to the generated documentation index.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
instructions/microsoft-foundry.instructions.md	Adds Microsoft Foundry Python SDK guidance and examples.
docs/README.instructions.md	Registers the new instruction.

Suppressed comments (4)

instructions/microsoft-foundry.instructions.md:55

• create_version does not point the agent endpoint at the new version. The official basic sample calls agents.update_details with an AgentEndpointConfig selecting the created version before opening the agent-scoped OpenAI client; without that, a new agent lacks usable routing and an existing agent can keep routing to older versions. Configure the endpoint first, and preserve/restore its prior configuration for a temporary sample.

    with project_client.get_openai_client(agent_name=agent_name) as openai_client:

instructions/microsoft-foundry.instructions.md:15

• az login is only needed when DefaultAzureCredential uses the Azure CLI credential during local development; it is neither required nor appropriate for managed/workload identity deployments. Qualify this instruction so generated production guidance does not depend on an interactive CLI login.

- Entra ID is the **only** supported auth. Use `azure.identity.DefaultAzureCredential`; run `az login` first. There is **no** API-key auth and **no** `from_connection_string()` on the client.

instructions/microsoft-foundry.instructions.md:91

• previous_response_id is not cheaper than a Conversation: prior input tokens are still processed and billed on subsequent Responses calls. It changes how state is managed, not token cost, so the cost claim is misleading.

For simple stateless follow-ups you can instead chain with `previous_response_id=response.id` on `responses.create` — cheaper than a full conversation when you only need to reference the prior turn.

instructions/microsoft-foundry.instructions.md:172

• logging_enable=True enables full transport traffic logging, including request/response bodies, and header sanitization is skipped in that mode unless a filtered handler is installed. Describing this only as a DEBUG-level switch can cause generated diagnostics to expose bearer tokens and prompt/user data. Prefer the SDK's filtered console-logging path and explicitly warn that payloads may still be sensitive.

- Enable request/response logging with `logging_enable=True` **and** logger level `DEBUG` (redacted unless level is DEBUG); or set `AZURE_AI_PROJECTS_CONSOLE_LOGGING=true`.

[passadis]

All five points were valid and are addressed in 6b97243:

Point	Fix
Version floor too low (L14)	Raised to >=2.3.0; noted which APIs need 2.1/2.2
Missing endpoint routing (L55)	Added explicit update_details + AgentEndpointConfig version-selection step to the basic example
az login vs. prod auth (L15)	Qualified — local dev uses CLI credential; Azure uses managed/workload identity
previous_response_id cost claim (L91)	Reworded as a state-management choice, not a token-cost saving
Logging security (L172)	Expanded to warn that body logging can leak tokens/prompts; prefer the filtered console path

Also verified via an A/B test in VS Code: with the file off, Copilot emits the deprecated create_agent/threads/runs API; with it on, it emits the correct v2 create_version + PromptAgentDefinition + Responses flow.

[passadis]

Verification: A/B tested in VS Code (instructions on vs. off)

I verified the uplift with an A/B test in VS Code using an identical prompt — "Create an Azure AI Foundry agent that answers general questions using the azure-ai-projects SDK, then send it a message and print the reply." — with the instruction file toggled on and off (fresh chat + window reload between runs).

❌ Instructions OFF — Copilot generates the deprecated pre-v2 azure-ai-agents thread/run API, which no longer exists in azure-ai-projects v2 and fails with AttributeError/404s against a real v2 project:

agent = agents_client.create_agent(model=..., name=..., instructions=...)
thread = agents_client.threads.create()
agents_client.messages.create(thread_id=thread.id, role="user", content="...")
run = agents_client.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
messages = agents_client.messages.list(thread_id=thread.id, order="asc")  # reply via message.text_messages[-1].text.value

✅ Instructions ON — Copilot generates the correct v2 pattern: versioned agents via create_version + PromptAgentDefinition, interaction through the OpenAI-compatible client (responses.create), and response.output_text for the reply (plus delete_version cleanup from the file's lifecycle notes):

version = project_client.agents.create_version(
    agent_name=agent_name,
    definition=PromptAgentDefinition(model=model, instructions="..."),
)
with project_client.get_openai_client(agent_name=agent_name) as openai_client:
    response = openai_client.responses.create(input="...")
    print(response.output_text)

The updated instructions don’t just rename methods — they force Copilot to abandon the old threads/runs mental model and operate fully in the Responses API paradigm. That’s exactly why the file’s field notes describe the “fail on first attempts → re‑ground → re‑code” cycle: the model was still reasoning in v1 patterns. By front‑loading the correct framing, you get v2‑style output immediately, without the usual correction loop.

Happy to attach full files-outputs !

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (1)

instructions/microsoft-foundry.instructions.md:204

• Remove this unmatched closing fence. All preceding Python blocks are already closed, so this creates a stray empty code block at the end of the rendered instruction.

</details>

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.