[BREAKING] Python: Foundry Hosted Agent V2 protocol upgrade (#6811)

* Upgrade to FHA protocol v2 + toolbox integration * Scope checkpoints and approval storage by user id * Add toolbox skills integration * Fix formatting * Add httpx lower and upper bound * Update foundry-hosting package version * Remove custom http client * Revert "Remove custom http client" This reverts commit 60f1d5aa52. * Remove custom http client * correct fail fast exceptino wording
2026-06-30 10:13:08 -07:00
parent 09fbccfb20
commit 7f3a2aec38
11 changed files with 5244 additions and 4652 deletions
@@ -13,11 +13,11 @@ template:
  kind: hosted
  protocols:
    - protocol: responses
-      version: 1.0.0
+      version: 2.0.0
  environment_variables:
    - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
      value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
 resources:
  - kind: model
    id: gpt-4.1-mini
-    name: AZURE_AI_MODEL_DEPLOYMENT_NAME
+    name: AZURE_AI_MODEL_DEPLOYMENT_NAME
@@ -3,10 +3,10 @@ kind: hosted
 name: agent-framework-agent-basic-responses
 protocols:
  - protocol: responses
-    version: 1.0.0
+    version: 2.0.0
 resources:
-  cpu: '0.25'
-  memory: '0.5Gi'
+  cpu: "0.25"
+  memory: "0.5Gi"
 environment_variables:
  - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
-    value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
+    value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
@@ -0,0 +1,6 @@
+agent.manifest.yaml
+agent.yaml
+.env.example
+.env
+toolbox.yaml
+./scripts
@@ -2,113 +2,46 @@

 import asyncio
 import os
-from collections.abc import Callable
-from urllib.parse import urlsplit

-import httpx
-from agent_framework import Agent, MCPStreamableHTTPTool
+from agent_framework import Agent
 from agent_framework.foundry import FoundryChatClient
-from agent_framework_foundry_hosting import ResponsesHostServer
-from azure.identity import DefaultAzureCredential, get_bearer_token_provider
+from agent_framework_foundry_hosting import FoundryToolbox, ResponsesHostServer
+from azure.identity import DefaultAzureCredential
 from dotenv import load_dotenv

 # Load environment variables from .env file
 load_dotenv()


-def resolve_toolbox_endpoint() -> str:
-    """Resolve the toolbox MCP endpoint URL.
-
-    Prefers the explicit ``TOOLBOX_ENDPOINT`` env var (set in ``agent.yaml`` or
-    ``agent.manifest.yaml`` and via ``azd env set TOOLBOX_ENDPOINT`` after the toolbox
-    is created); falls back to constructing the URL from ``FOUNDRY_PROJECT_ENDPOINT``
-    and ``TOOLBOX_NAME``.
-    """
-    if (endpoint := os.environ.get("TOOLBOX_ENDPOINT")) is not None:
-        if not endpoint:
-            raise ValueError("TOOLBOX_ENDPOINT is set but empty")
-        return endpoint
-    try:
-        project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/")
-        toolbox_name = os.environ["TOOLBOX_NAME"]
-    except KeyError as e:
-        raise ValueError(
-            "Either set TOOLBOX_ENDPOINT, or set both FOUNDRY_PROJECT_ENDPOINT "
-            "and TOOLBOX_NAME to build the toolbox MCP endpoint."
-        ) from e
-    return f"{project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1"
-
-
-def _toolbox_name_from_endpoint(endpoint: str) -> str:
-    """Extract the toolbox name from a toolbox MCP endpoint URL.
-
-    Handles both the versioned (``.../toolboxes/<name>/versions/<n>/mcp``) and
-    unversioned (``.../toolboxes/<name>/mcp``) endpoint shapes that Foundry
-    produces. Falls back to ``"toolbox"`` when the path has no ``toolboxes``
-    segment.
-    """
-    segments = urlsplit(endpoint).path.split("/")
-    if "toolboxes" in segments:
-        idx = segments.index("toolboxes")
-        if idx + 1 < len(segments) and segments[idx + 1]:
-            return segments[idx + 1]
-    return "toolbox"
-
-
-class ToolboxAuth(httpx.Auth):
-    """Injects a fresh bearer token on every request."""
-
-    def __init__(self, token_provider: Callable[[], str]):
-        self._get_token = token_provider
-
-    def auth_flow(self, request: httpx.Request):
-        request.headers["Authorization"] = f"Bearer {self._get_token()}"
-        yield request
-
-
 async def main():
    credential = DefaultAzureCredential()

-    # Create the toolbox
-    token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")
+    # FoundryToolbox resolves the toolbox endpoint from the environment
+    # (TOOLBOX_ENDPOINT, or FOUNDRY_PROJECT_ENDPOINT + TOOLBOX_NAME), authenticates
+    # every request with the credential, and transparently forwards the platform
+    # per-request call-id to the toolbox. The hosting server enters the agent, which
+    # connects the toolbox on first use and closes it at shutdown.
+    toolbox = FoundryToolbox(credential)

-    # Resolve the endpoint once and derive a friendly tool name from it. When
-    # ``TOOLBOX_NAME`` isn't set, extract the toolbox name from the URL path so
-    # the tool's local name matches the upstream toolbox.
-    toolbox_endpoint = resolve_toolbox_endpoint()
-    toolbox_name = os.environ.get("TOOLBOX_NAME") or _toolbox_name_from_endpoint(toolbox_endpoint)
+    # Create the chat client
+    client = FoundryChatClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+        credential=credential,
+    )

-    async with httpx.AsyncClient(
-        auth=ToolboxAuth(token_provider),
-        headers={"Foundry-Features": "Toolboxes=V1Preview"},
-        timeout=120.0,
-    ) as http_client:
-        toolbox = MCPStreamableHTTPTool(
-            name=toolbox_name,
-            url=toolbox_endpoint,
-            http_client=http_client,
-            load_prompts=False,
-        )
+    agent = Agent(
+        client=client,
+        instructions="You are a friendly assistant. Keep your answers brief.",
+        tools=toolbox,
+        # History will be managed by the hosting infrastructure, thus there
+        # is no need to store history by the service. Learn more at:
+        # https://developers.openai.com/api/reference/resources/responses/methods/create
+        default_options={"store": False},
+    )

-        # Create the chat client
-        client = FoundryChatClient(
-            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
-            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
-            credential=credential,
-        )
-
-        agent = Agent(
-            client=client,
-            instructions="You are a friendly assistant. Keep your answers brief.",
-            tools=toolbox,
-            # History will be managed by the hosting infrastructure, thus there
-            # is no need to store history by the service. Learn more at:
-            # https://developers.openai.com/api/reference/resources/responses/methods/create
-            default_options={"store": False},
-        )
-
-        server = ResponsesHostServer(agent)
-        await server.run_async()
+    server = ResponsesHostServer(agent)
+    await server.run_async()


 if __name__ == "__main__":