mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Python: feat(foundry): add to_prompt_agent / deploy_as_prompt_agent (experimental) (#5959)
* feat(foundry): add experimental to_prompt_agent converter Adds `to_prompt_agent(agent)`, an experimental converter (`ExperimentalFeature.TO_PROMPT_AGENT`) that turns an Agent Framework `Agent` into a Foundry `PromptAgentDefinition` ready to publish via `AIProjectClient.agents.create_version(...)`. Behaviour: * `agent.client` must be a `FoundryChatClient` (or subclass); otherwise `TypeError` is raised. The model deployment name is lifted from the bound client so the same Agent definition used for local runs can be published as a hosted prompt agent without restating the model. * Foundry SDK tool instances (from `FoundryChatClient.get_*_tool()`) are passed through unchanged. AF `FunctionTool`s (and `@tool`-decorated callables) are emitted as Foundry `FunctionTool` declarations. * Local AF MCP tools cannot be expressed in a `PromptAgentDefinition`; the converter raises `ValueError` and points at `FoundryChatClient.get_mcp_tool()` for hosted MCP servers. * The converter walks both `agent.default_options["tools"]` and `agent.mcp_tools` because `normalize_tools()` splits local MCP off into its own list. Re-exported through the `agent_framework.foundry` lazy-loading namespace (updates both `__init__.py` and the `__init__.pyi` type stub). Adds a portable-agent sample showing the same `Agent` driven through both `agent.run(...)` and `to_prompt_agent(agent)`, and a README section covering the new converter. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore(samples): remove snippet tags from portable agent sample Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore(samples): inline FoundryChatClient and enable prompt-agent publish Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore(samples): drop async credential context manager Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(foundry): trim README to_prompt_agent example to publish-only flow Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(foundry): note FoundryAgent runs @tool callables for deployed prompt agents Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(foundry): address review comments on to_prompt_agent converter * Construct `PromptAgentDefinition` `Tool` from a dict via `**tool_item` unpacking rather than the positional Mapping constructor \u2014 cleaner and matches the typical Pydantic / Azure SDK pattern. * Drop the redundant `isinstance(mcp_tool, MCPTool)` guard in `_convert_tools`; the parameter is already typed `Iterable[MCPTool]` so the second `raise` was unreachable. The remaining single `raise` fires for every entry as intended. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(foundry): match Agent.__init__ model resolution in to_prompt_agent * Read the model from `agent.default_options.get("model")` first, falling back to `agent.client.model`. This mirrors the order `Agent.__init__` uses (`_agents.py:740`) when assembling default_options, so the model the agent runs with is the same model the converter publishes \u2014 e.g. when the caller passes `default_options={"model": "..."}` to override the bound client. * Updated the missing-model error message to point at both the client and the default_options paths. * Added tests: * tool-only agent with no `instructions` produces a definition where `instructions` is `None` and is omitted from the dict payload (`Agent.__init__` strips None values from default_options before storing them). * `default_options['model']` wins over the bound client's model. * Fallback to client.model when default_options has no model. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat(foundry): add deploy_as_prompt_agent helper + samples Adds `deploy_as_prompt_agent(agent)`, a convenience wrapper around `to_prompt_agent` that reuses the bound FoundryChatClient's project client to call `project_client.agents.create_version(...)`. Defaults `agent_name` / `description` from `agent.name` / `agent.description` so the Agent stays the single source of truth. * Exposed from `agent_framework_foundry` and the lazy-loading `agent_framework.foundry` namespace (including the .pyi stub). * Marked experimental with the existing `ExperimentalFeature.TO_PROMPT_AGENT` tag. * Tests cover the happy path, name/description defaulting, explicit override, no-name error, metadata + description forwarding, extra kwargs passthrough, and the experimental metadata. Samples: * Renamed the existing sample to `creating_prompt_agents.py`, drops 'portable' wording, presents `deploy_as_prompt_agent` first as the recommended path and `to_prompt_agent` + `AIProjectClient` as the two-step alternative, and adds a cleanup step that deletes the published agent so re-runs stay idempotent. * New `using_prompt_agents.py` shows the end-to-end loop: deploy the agent, connect to it with `FoundryAgent` passing the same local `@tool` callable, run a query against the deployed prompt agent, then clean up. README updated to introduce `deploy_as_prompt_agent` as the recommended path and link to both runnable samples. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(foundry): restore missing-model ValueError in to_prompt_agent The check was accidentally dropped while reworking docstrings in the previous commit. Test `test_to_prompt_agent_rejects_missing_model` exercises this path and was failing on CI as a result. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * refactor(foundry): rename deploy_as_prompt_agent -> create_prompt_agent Renames the helper across the foundry package, core lazy-loader stubs, tests, README and samples. The new name better matches the action performed (a prompt-agent definition is created in Foundry) and is consistent with the surrounding ''create_*'' API surface. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * refactor(foundry): drop create_prompt_agent, enrich to_prompt_agent params Remove the create_prompt_agent helper and consolidate on to_prompt_agent. Expose every PromptAgentDefinition parameter that has either an Agent Framework equivalent (sourced from default_options) or no equivalent (accepted as a keyword argument). * default_options-sourced (with kwarg overrides): temperature, top_p, string tool_choice * kwarg-only Foundry knobs: reasoning, text, structured_inputs, rai_config, ToolChoiceParam tool_choice Precedence is always: explicit keyword > default_options entry > unset. Tests cover every path (defaults, default_options, kwargs, kwarg override). Samples and README rewritten around the enriched to_prompt_agent. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * refactor(foundry): single source of truth for prompt-agent options Stop duplicating the generation-parameter surface between FoundryChatOptions and to_prompt_agent. Translate every field with an Agent Framework equivalent (temperature, top_p, tool_choice, reasoning, response_format/text/verbosity) from agent.default_options via a new RawFoundryChatClient helper _prepare_prompt_agent_options. Only Foundry-specific fields with no AF equivalent — structured_inputs and rai_config — remain as keyword arguments on to_prompt_agent. - tool_choice is dropped when there are no tools (mirrors _prepare_options semantics and avoids polluting tool-less prompt agents with Agent.__init__'s 'auto' default). - response_format Pydantic models route through openai.lib._parsing._responses.type_to_text_format_param; dict shapes go through the existing _prepare_response_and_text_format helper. - default_options is not mutated; text dict is defensively copied. Tests, README, and creating_prompt_agents.py sample updated to reflect the new single-source model. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(foundry): consolidate prompt-agent sample Drop creating_prompt_agents.py (the publish-only variant) and rename using_prompt_agents.py to foundry_prompt_agents.py so the single sample covers the full convert -> publish -> connect -> run loop. Update the README link list accordingly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(foundry): run local Agent + deployed agent in same sample Add an agent.run() call against the local Agent before publishing, then run the deployed prompt agent on the same query. Expand the docstring with a compare-and-contrast covering runtime/latency, configurability, and persistence/sharing differences between the two execution paths. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * test(foundry): cover conflicting response_format + text.format in to_prompt_agent Exercises the ValueError path when a Pydantic response_format would overwrite an explicit text.format mapping with a different shape. Lifts _chat_client.py coverage from 89% to 90%. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * refactor(foundry): move _prepare_prompt_agent_options into _to_prompt_agent Lift the translation helper off RawFoundryChatClient and into the _to_prompt_agent module as a module-private function that takes the client as its first argument. The chat client no longer needs to carry a method whose only consumer is the prompt-agent converter, while still serving as the source of the request-path helper (_prepare_response_and_text_format) that the converter reuses for dict-shaped response_format values. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(python): codify GA terminology + post-run docs review Add two pieces of guidance to python/AGENTS.md: * Terminology - reserve 'GA' for hosted services; use 'released' or 'stable' for Agent Framework code/features to match the feature-lifecycle stages. * Maintaining Documentation - review AGENTS.md and skills at the end of every run and update any guidance the conversation made stale; before adding a new principle, ask the user to confirm it should be captured. Also pulls in a docstring fix in foundry_prompt_agents.py that swaps the stray 'GA' for 'released', applying the new terminology rule. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * address PR review: strict=True default, Tool._deserialize dispatch, sample cleanup safety - FunctionTool published as strict=True so the server-side schema validation matches what the local FoundryAgent(tools=[same_callable]) dispatcher enforces. AF FunctionTool has no 'strict' attribute, so the safer default is used uniformly instead of silently downgrading to a permissive contract. - _validate_mapping_tool now dispatches through ProjectsTool._deserialize so dict-shaped tools rehydrate to the concrete subclass (FunctionTool, WebSearchTool, ...) via the 'type' discriminator instead of returning a generic Tool. Added a test that asserts isinstance(WebSearchTool) and a new test for the function-typed dict path. - foundry_prompt_agents.py sample now wraps credential + project client in async with and the create_version / run flow in try/finally so a failure on connect or run still deletes the published prompt agent rather than leaving an orphaned, billable resource in the user's Foundry project. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(ci): correct linkspector ignorePattern typo (./pulls -> ./pull) GitHub PR URLs use the singular segment /pull/N (compare to /issues/N for issues). The existing './pulls' ignore pattern never matched anything as a result, so legitimately stale PR links (e.g. PRs deleted from forks) surface as linkspector failures on unrelated PRs. This is the same convention the './issues' rule above already follows. Fixes the markdown-link-check failure on a dangling link in dotnet/src/Microsoft.Agents.AI.DurableTask/CHANGELOG.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Eduard van Valkenburg
committed by
GitHub
Unverified
GitHub
parent
ae989b92e7
commit
d5c07f2623
@@ -0,0 +1,150 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
import asyncio
|
||||
import os
|
||||
from random import randint
|
||||
from typing import Annotated
|
||||
|
||||
from agent_framework import Agent, tool
|
||||
from agent_framework.foundry import FoundryAgent, FoundryChatClient, to_prompt_agent
|
||||
from azure.ai.projects.aio import AIProjectClient
|
||||
from azure.identity.aio import AzureCliCredential
|
||||
from dotenv import load_dotenv
|
||||
from pydantic import Field
|
||||
|
||||
load_dotenv()
|
||||
|
||||
"""
|
||||
Foundry Prompt Agent: Convert, Publish, Connect, and Run
|
||||
|
||||
This sample shows the end-to-end loop:
|
||||
|
||||
1. Build an ``Agent`` backed by ``FoundryChatClient`` with a local ``@tool``
|
||||
function and Foundry-hosted tools.
|
||||
2. Run the local ``Agent`` directly against the Foundry Responses API.
|
||||
3. Convert it with ``to_prompt_agent(agent)`` and publish via
|
||||
``AIProjectClient.agents.create_version(...)``.
|
||||
4. Connect to the deployed prompt agent with ``FoundryAgent`` and pass the
|
||||
*same* ``book_hotel`` callable through ``tools=`` so the server-side prompt
|
||||
agent and the client share a single tool definition.
|
||||
|
||||
The Foundry prompt agent only receives the ``book_hotel`` *declaration* (its
|
||||
JSON schema). When the deployed agent decides to call the tool, ``FoundryAgent``
|
||||
executes the local Python implementation by matching tool names — keeping the
|
||||
schema on the server and the implementation on the client in sync.
|
||||
|
||||
Local ``Agent`` vs deployed prompt agent — compare & contrast when calling
|
||||
``run`` on each:
|
||||
|
||||
* **Runtime / latency.** ``Agent.run`` issues a single ``responses.create``
|
||||
call against the Foundry Responses API. ``FoundryAgent.run`` against a
|
||||
published prompt agent goes through the Foundry Agents service, which
|
||||
resolves the stored ``PromptAgentDefinition`` (instructions, tools,
|
||||
generation parameters, RAI config) on every call before forwarding to the
|
||||
model. Expect a small per-call overhead on the deployed path in exchange
|
||||
for centrally managed configuration.
|
||||
* **Configurability.** With the local ``Agent``, model, instructions, tools,
|
||||
``default_options``, etc. live in your process — change them, restart, and
|
||||
the next ``run`` picks them up. With the deployed prompt agent, those same
|
||||
fields are versioned server-side: publishing a new version updates every
|
||||
consumer at once and you keep an audit trail of previous versions, but you
|
||||
must call ``create_version`` (or pin ``agent_version``) to roll changes
|
||||
out or back.
|
||||
* **Persistence / sharing.** A local ``Agent`` instance only exists for the
|
||||
lifetime of the process that created it; tools and instructions are not
|
||||
discoverable by anything else. A published prompt agent is a first-class
|
||||
Foundry resource — other services, other languages, and the Foundry portal
|
||||
can all bind to it by ``agent_name`` (+ optional ``agent_version``) and get
|
||||
the same behaviour. Local ``@tool`` callables stay on the client; only
|
||||
their JSON schema is persisted, so the implementation must be supplied
|
||||
again at connection time via ``FoundryAgent(tools=[...])``.
|
||||
|
||||
``to_prompt_agent`` is experimental
|
||||
(``ExperimentalFeature.TO_PROMPT_AGENT``) and may change before being released.
|
||||
"""
|
||||
|
||||
|
||||
@tool
|
||||
def book_hotel(
|
||||
city: Annotated[str, Field(description="The city to book the hotel in.")],
|
||||
nights: Annotated[int, Field(description="Number of nights to stay.")],
|
||||
) -> str:
|
||||
"""Book a hotel room for the given city and number of nights."""
|
||||
return f"Booked a hotel in {city} for {nights} nights. Confirmation #CTX-{randint(1000, 9999)}."
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
print("=== Foundry Prompt Agent: Convert, Publish, Connect, and Run ===\n")
|
||||
|
||||
project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
|
||||
model = os.environ["FOUNDRY_MODEL"]
|
||||
|
||||
# Use ``async with`` so the credential and project client are closed even if the
|
||||
# body below raises. The ``try/finally`` around ``delete`` further guarantees we
|
||||
# don't leave an orphaned prompt agent in the Foundry project after a failure.
|
||||
async with (
|
||||
AzureCliCredential() as credential,
|
||||
AIProjectClient(endpoint=project_endpoint, credential=credential) as project_client,
|
||||
):
|
||||
# 1) Define the Agent. `name` / `description` set here become the Foundry agent identity
|
||||
# on publish; `book_hotel` is the local implementation that backs the published declaration.
|
||||
agent = Agent(
|
||||
client=FoundryChatClient(
|
||||
project_endpoint=project_endpoint,
|
||||
model=model,
|
||||
credential=credential,
|
||||
),
|
||||
name="travel-agent",
|
||||
description="Helps Contoso employees book travel.",
|
||||
instructions="You are a helpful travel assistant. Use the booking tool when asked.",
|
||||
tools=[
|
||||
FoundryChatClient.get_web_search_tool(),
|
||||
book_hotel,
|
||||
],
|
||||
default_options={"reasoning": {"effort": "medium"}},
|
||||
)
|
||||
|
||||
query = "Book me a hotel in Seattle for 3 nights."
|
||||
|
||||
# 2) Run the local Agent. This calls the Foundry Responses API directly — instructions,
|
||||
# tools, and generation parameters live in this process only.
|
||||
print(f"User (local Agent): {query}")
|
||||
local_result = await agent.run(query)
|
||||
print(f"Local Agent: {local_result}\n")
|
||||
|
||||
# 3) Convert and publish. The version returned by Foundry includes the version label
|
||||
# we need when connecting back to that specific deployment.
|
||||
created = await project_client.agents.create_version(
|
||||
agent_name=agent.name,
|
||||
# note this line:
|
||||
definition=to_prompt_agent(agent),
|
||||
description=agent.description,
|
||||
)
|
||||
print(f"Published prompt agent: {created.name} v{created.version}\n")
|
||||
|
||||
try:
|
||||
# 4) Connect to the deployed prompt agent with FoundryAgent and pass the *same* callable
|
||||
# tool. FoundryAgent runs the local function when the server-side agent invokes the tool,
|
||||
# matching by name. Compared to step 2, instructions/tools/generation parameters now
|
||||
# come from the stored PromptAgentDefinition rather than this process.
|
||||
deployed = FoundryAgent(
|
||||
project_endpoint=project_endpoint,
|
||||
agent_name=created.name,
|
||||
agent_version=created.version,
|
||||
credential=credential,
|
||||
tools=[book_hotel],
|
||||
)
|
||||
|
||||
print(f"User (deployed agent): {query}")
|
||||
deployed_result = await deployed.run(query)
|
||||
print(f"Deployed Agent: {deployed_result}")
|
||||
finally:
|
||||
# 5) Cleanup: delete the deployed prompt agent (and all its versions) even if step 4
|
||||
# raised, so re-running the sample stays idempotent and we don't leak resources in
|
||||
# the Foundry project.
|
||||
await project_client.agents.delete(agent_name=created.name)
|
||||
print(f"\nDeleted prompt agent {created.name!r} and all its versions.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
Reference in New Issue
Block a user