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

.github/.linkspector.yml

@@ -8,7 +8,7 @@ ignorePatterns:
   - pattern: "./blob"
   - pattern: "./issues"
   - pattern: "./discussions"
-  - pattern: "./pulls"
+  - pattern: "./pull"
   - pattern: "https:\/\/platform.openai.com"
   - pattern: "http:\/\/localhost"
   - pattern: "http:\/\/127.0.0.1"

python/AGENTS.md

@@ -21,6 +21,21 @@ When making changes to a package, check if the following need updates:
 - The package's `AGENTS.md` file (adding/removing/renaming public APIs, architecture changes, import path changes)
 - The agent skills in `.github/skills/` if conventions, commands, or workflows change
 
+At the end of every run, re-read `AGENTS.md` and the relevant skill files and
+update any guidance that the conversation revealed to be out of date,
+incomplete, or misleading (renamed files, changed commands, new conventions
+the user confirmed, etc.). **Before adding a new principle or rule, ask the
+user whether they want it captured as a durable principle** — do not invent
+team norms from a single conversation without explicit confirmation.
+
+## Terminology
+
+- **Avoid "GA" for Agent Framework code.** Reserve *GA* for hosted services
+  (e.g. "the Foundry service is GA"). For Agent Framework packages, features,
+  and APIs use **"released"** or **"stable"** depending on context — these
+  match the feature-lifecycle stages documented in the
+  `python-feature-lifecycle` skill.
+
 ## Pull Request Description Guidance
 
 When preparing a PR description:

python/packages/core/agent_framework/_feature_stage.py

@@ -58,6 +58,7 @@ class ExperimentalFeature(str, Enum):
     FUNCTIONAL_WORKFLOWS = "FUNCTIONAL_WORKFLOWS"
     HARNESS = "HARNESS"
     SKILLS = "SKILLS"
+    TO_PROMPT_AGENT = "TO_PROMPT_AGENT"
 
 
 class ReleaseCandidateFeature(str, Enum):

python/packages/core/agent_framework/foundry/__init__.py

@@ -41,6 +41,7 @@
     "RawFoundryEmbeddingClient": ("agent_framework_foundry", "agent-framework-foundry"),
     "evaluate_foundry_target": ("agent_framework_foundry", "agent-framework-foundry"),
     "evaluate_traces": ("agent_framework_foundry", "agent-framework-foundry"),
+    "to_prompt_agent": ("agent_framework_foundry", "agent-framework-foundry"),
 }
 
 

python/packages/core/agent_framework/foundry/__init__.pyi

@@ -26,6 +26,7 @@ from agent_framework_foundry import (
     RawFoundryEmbeddingClient,
     evaluate_foundry_target,
     evaluate_traces,
+    to_prompt_agent,
 )
 from agent_framework_foundry_local import (
     FoundryLocalChatOptions,
@@ -58,4 +59,5 @@ __all__ = [
     "RawFoundryEmbeddingClient",
     "evaluate_foundry_target",
     "evaluate_traces",
+    "to_prompt_agent",
 ]

python/packages/foundry/README.md

@@ -106,3 +106,129 @@ Generally available factories: `get_code_interpreter_tool`,
 | `get_browser_automation_tool(connection_id)` | `BrowserAutomationPreviewTool` |
 | `get_bing_custom_search_tool(connection_id, instance_name, ...)` | `BingCustomSearchPreviewTool` |
 | `get_a2a_tool(base_url=..., project_connection_id=..., ...)` | `A2APreviewTool` |
+## Publishing an agent as a Foundry prompt agent
+
+> **Experimental — `ExperimentalFeature.TO_PROMPT_AGENT`.** `to_prompt_agent`
+> is a preview API and may change before reaching GA. The warning fires the
+> first time the `TO_PROMPT_AGENT` feature is exercised in a process and is
+> then deduplicated.
+
+`to_prompt_agent(agent)` converts an `Agent` whose chat client is a
+`FoundryChatClient` into a Foundry `PromptAgentDefinition` that can be
+published with `AIProjectClient.agents.create_version(...)`. The model is read
+from `default_options["model"]` first and falls back to the bound
+`FoundryChatClient.model` (matching `Agent.__init__`'s resolution order), so
+the same agent definition you run locally can be published as a hosted prompt
+agent without restating the model deployment name.
+
+Every generation parameter that has an Agent Framework equivalent is sourced
+from `agent.default_options` and translated into the matching Foundry shape by
+`_prepare_prompt_agent_options` (a module-private helper in
+`agent_framework_foundry._to_prompt_agent` that reuses the chat client's own
+request-path helpers):
+
+| `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` |
+
+This keeps the `Agent` as the single source of truth for everything it can
+already express. Only Foundry-specific fields with no Agent Framework
+equivalent are accepted as keyword arguments on `to_prompt_agent`:
+
+- `structured_inputs` — `dict[str, StructuredInputDefinition]`
+- `rai_config` — `RaiConfig`
+
+```python
+import asyncio
+import os
+
+from agent_framework import Agent
+from agent_framework.foundry import FoundryChatClient, to_prompt_agent
+from azure.ai.projects.aio import AIProjectClient
+from azure.identity.aio import AzureCliCredential
+
+
+async def main() -> None:
+    credential = AzureCliCredential()
+    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
+
+    agent = Agent(
+        client=FoundryChatClient(
+            project_endpoint=project_endpoint,
+            model="gpt-4o",
+            credential=credential,
+        ),
+        name="travel-agent",
+        description="Helps Contoso employees book travel.",
+        instructions="You are a helpful travel assistant.",
+        tools=[
+            FoundryChatClient.get_web_search_tool(),
+            FoundryChatClient.get_code_interpreter_tool(),
+        ],
+        # Generation parameters set on the Agent flow through automatically.
+        default_options={
+            "temperature": 0.3,
+            "top_p": 0.95,
+            "reasoning": {"effort": "medium"},
+        },
+    )
+
+    definition = to_prompt_agent(agent)
+
+    project_client = AIProjectClient(endpoint=project_endpoint, credential=credential)
+    created = await project_client.agents.create_version(
+        agent_name=agent.name,
+        definition=definition,
+        description=agent.description,
+    )
+    print(f"Published {created.name} v{created.version}")
+
+
+asyncio.run(main())
+```
+
+Behaviour:
+
+- `agent.client` must be a `FoundryChatClient` (or subclass) — otherwise the
+  converter raises `TypeError`.
+- The bound client must have a `model` set — otherwise the converter raises
+  `ValueError`.
+- Foundry SDK tool instances returned by `FoundryChatClient.get_*_tool()` are
+  passed through unchanged.
+- AF `FunctionTool` instances (and `@tool`-decorated callables) are emitted as
+  Foundry `FunctionTool` **declarations** — the prompt agent receives the
+  schema only, not the Python implementation. To execute the function when
+  invoking the deployed prompt agent, connect with `FoundryAgent` and pass the
+  same callable via `tools=`:
+
+  ```python
+  from agent_framework.foundry import FoundryAgent
+
+  deployed = FoundryAgent(
+      project_endpoint=project_endpoint,
+      agent_name="travel-agent",
+      credential=credential,
+      tools=[book_hotel],  # same @tool-decorated callable used at publish time
+  )
+  result = await deployed.run("Book me a hotel in Seattle for 3 nights.")
+  ```
+
+  `FoundryAgent` runs the function locally when the prompt agent calls it, so
+  the declaration on the server and the implementation on the client stay in
+  sync via the shared `@tool` definition.
+- Local Agent Framework MCP tools cannot be published as prompt-agent tools —
+  the converter raises `ValueError` and points at
+  `FoundryChatClient.get_mcp_tool(...)` for hosted MCP servers.
+
+See the runnable example under `samples/02-agents/providers/foundry/`:
+
+- [`foundry_prompt_agents.py`](../../samples/02-agents/providers/foundry/foundry_prompt_agents.py)
+  — publish with `to_prompt_agent`, then connect back with `FoundryAgent` and
+  execute the same local `@tool` callable that the deployed prompt agent
+  invokes by name.

python/packages/foundry/agent_framework_foundry/__init__.py

@@ -16,6 +16,7 @@
     evaluate_traces,
 )
 from ._memory_provider import FoundryMemoryProvider
+from ._to_prompt_agent import to_prompt_agent
 
 try:
     __version__ = importlib.metadata.version(__name__)
@@ -39,4 +40,5 @@
     "__version__",
     "evaluate_foundry_target",
     "evaluate_traces",
+    "to_prompt_agent",
 ]