Python: feat(foundry): add to_prompt_agent / deploy_as_prompt_agent (experimental)

[eavanvalkenburg]

Motivation and Context

Publishing an Agent Framework Agent as a Foundry prompt agent required hand-rolling a PromptAgentDefinition and calling AIProjectClient.agents.create_version(...) directly — duplicating instructions, tools, generation parameters, and the model deployment name that the local Agent already carries.

Description

Two experimental helpers in agent-framework-foundry close that gap. Both are gated by ExperimentalFeature.TO_PROMPT_AGENT.

to_prompt_agent(agent, *, structured_inputs=None, rai_config=None) -> PromptAgentDefinition

Converts an Agent whose chat client is a FoundryChatClient into a PromptAgentDefinition ready for AIProjectClient.agents.create_version(...). The Agent is the single source of truth: model, instructions, tools, and every generation parameter that has an Agent Framework equivalent are translated by a new RawFoundryChatClient._prepare_prompt_agent_options helper, reusing the same validate_tool_mode, _prepare_response_and_text_format, and openai.lib._parsing._responses.type_to_text_format_param paths as the regular request flow.

default_options key	PromptAgentDefinition field
temperature	temperature
top_p	top_p
tool_choice (dropped when no tools)	tool_choice (str / ToolChoiceFunction / ToolChoiceAllowed)
reasoning (dict or Reasoning)	reasoning
response_format (dict or BaseModel)	text.format
verbosity	text.verbosity
text	merged into text (defensively copied)

Only Foundry-specific fields with no Agent Framework equivalent (structured_inputs, rai_config) remain as keyword arguments. default_options is never mutated, and tool_choice is dropped when the definition has no tools — mirroring _prepare_options and avoiding Agent.__init__'s default "auto" polluting tool-less prompt agents.

deploy_as_prompt_agent(agent, *, structured_inputs=None, rai_config=None) -> Agent

Convenience wrapper that combines to_prompt_agent with project_client.agents.create_version(...). Reuses the agent's bound FoundryChatClient.project_client and propagates agent.name / agent.description so callers don't restate them.

Tooling

FoundryChatClient exposes get_web_search_tool(), get_code_interpreter_tool(), and get_mcp_tool() helpers so hosted Foundry tools can be passed straight through Agent(tools=[...]) and re-emitted unchanged in the published prompt agent. Local @tool callables are emitted as Foundry FunctionTool declarations (schema only) — the runtime implementation is supplied client-side via FoundryAgent(tools=[same_callable]). Local MCP tools cannot be published; the converter points callers at get_mcp_tool(...) instead.

Sample

samples/02-agents/providers/foundry/foundry_prompt_agents.py walks the full convert → publish → connect → run loop, running agent.run(query) on the local Agent and on the deployed prompt agent with the same query, and documents the runtime / configurability / persistence trade-offs between the two execution paths.

Contribution Checklist

• I have read the contribution guidelines
• I have provided a clear description of my changes
• My changes have been validated with our linters and tests
• I have added or updated relevant documentation

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds an experimental to_prompt_agent(agent) -> PromptAgentDefinition converter to make Agent Framework Foundry agents portable between local execution (agent.run) and publishing as a hosted Foundry prompt agent.

Changes:

• Introduces agent_framework_foundry._to_prompt_agent.to_prompt_agent with tool conversion rules (SDK tools pass-through, AF function tools -> declarations, local MCP rejected, dict tools rehydrated).
• Re-exports to_prompt_agent via agent_framework_foundry and agent_framework.foundry (incl. .pyi) and registers ExperimentalFeature.TO_PROMPT_AGENT.
• Adds unit tests, README guidance, and a portable-agent sample.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
python/samples/02-agents/providers/foundry/foundry_portable_agent.py	Adds an end-to-end sample running locally and publishing via to_prompt_agent.
python/packages/foundry/tests/foundry/test_to_prompt_agent.py	Adds coverage for client validation, model requirements, and tool conversion behaviors.
python/packages/foundry/agent_framework_foundry/_to_prompt_agent.py	Implements the converter and tool-shape conversion/validation logic.
python/packages/foundry/agent_framework_foundry/init.py	Re-exports to_prompt_agent from the package root.
python/packages/foundry/README.md	Documents how to publish an agent as a Foundry prompt agent (experimental).
python/packages/core/agent_framework/foundry/init.pyi	Exposes to_prompt_agent in the typed public surface.
python/packages/core/agent_framework/foundry/init.py	Adds lazy import mapping for to_prompt_agent.
python/packages/core/agent_framework/_feature_stage.py	Adds ExperimentalFeature.TO_PROMPT_AGENT.

[github-actions]

Automated Code Review

Reviewers: 4 | Confidence: 85%

✓ Correctness

The converter logic is sound: it correctly accesses agent.default_options["tools"] for non-MCP tools, agent.mcp_tools for local MCP tools, and agent.client.model for the deployment name. The isinstance checks in _convert_tools are ordered correctly (ProjectsTool before FunctionTool before Mapping). FunctionTool.parameters() is a valid method returning a dict (confirmed at _tools.py:782). The only remaining concern (already flagged in the prior review) is the ProjectsTool(dict(tool_item)) positional-dict construction on line 179, which works with the Azure SDK's autorest-generated _model_base.Model but is non-obvious and may break if the SDK changes its internal base class. No new correctness issues found beyond what was already flaged.

✓ Security Reliability

The converter module is well-structured with proper validation: client type checks, model presence validation, tool type discrimination with clear error messages, and explicit rejection of local MCP tools. No new security or reliability issues found beyond those already flagged in the existing review thread (ProjectsTool positional construction, unreachable mcp_tools branch, sample cosmetics).

✓ Test Coverage

Test coverage is generally thorough, covering the main success paths, error conditions, and the experimental decorator. The primary gap is the absence of a test for an Agent created without instructions (a common real-world scenario where agents are purely tool-based). The converter explicitly calls agent.default_options.get("instructions") which returns None in that case, and this path should be verified. Additionally, a test combining valid tools alongside a local MCP tool would strengthen coverage of the error path to ensure valid tools don't get lost before the MCP rejection fires.

✓ Design Approach

I found one design issue: the converter currently publishes the client’s base model instead of the agent’s effective model. In this repo, Agent(default_options={"model": ...}) is the authoritative override for local execution, so to_prompt_agent() can produce a prompt agent that runs on a different model than the same Agent uses locally.

---

Automated review by eavanvalkenburg's agents

[moonbox3]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_feature_stage.py	164	10	93%	105, 151, 206, 217, 237, 275, 286, 292, 323, 351
packages/foundry/agent_framework_foundry
_to_prompt_agent.py	102	2	98%	189, 224
TOTAL	36481	4315	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
7298	34 💤	0 ❌	0 🔥	1m 58s ⏱️