diff --git a/python/samples/02-agents/tools/README.md b/python/samples/02-agents/tools/README.md index a15f85f56c9..c2ffd1e3c46 100644 --- a/python/samples/02-agents/tools/README.md +++ b/python/samples/02-agents/tools/README.md @@ -1,5 +1,8 @@ # Tools +[Container Apps Dynamic Sessions](./container_apps_dynamic_sessions.py) shows a +function tool that executes Python in a cloud session with per-run session ownership. + Samples that show how to define, configure, and control function tools for an agent — from basic declarations to approvals, invocation limits, session injection, and dynamic (progressive) tool exposure. @@ -88,3 +91,6 @@ take effect on the **next iteration** of the function-calling loop. > CodeAct setup in > [`../context_providers/code_act/`](../context_providers/code_act/), which adds > dynamic tool / capability management. + +The Dynamic Sessions tool returns only execution status and output to the model; +session identifiers and HTTP request URLs remain application-owned. diff --git a/python/samples/02-agents/tools/container_apps_dynamic_sessions.py b/python/samples/02-agents/tools/container_apps_dynamic_sessions.py new file mode 100644 index 00000000000..38600bd50e3 --- /dev/null +++ b/python/samples/02-agents/tools/container_apps_dynamic_sessions.py @@ -0,0 +1,100 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Run agent-generated Python in an Azure Container Apps Dynamic Sessions pool. + +Prerequisites: +- Install agent-framework-foundry, azure-identity, and httpx; sign in with az login. +- Set FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL for your model deployment. +- Set POOL_MANAGEMENT_ENDPOINT to the Python code-interpreter pool's management + endpoint (az containerapp sessionpool show --query properties.poolManagementEndpoint). +- Give the signed-in identity Azure ContainerApps Session Executor on the pool, + and permission to invoke the Foundry model. + +Each program run generates a fresh session identifier, reused for its tool calls. +The identifier is owned by the application, never selected by the model. In a +multi-user host, create a separate agent/tool/session binding for each authorized +conversation. Pool cooldown controls cleanup after the last use; this sample does +not provision or delete Azure resources. Model and session-pool usage incur costs. + +The tool sends code to the configured cloud sandbox; it does not execute code on +this machine. Configure the pool's network access for your workload and do not +pass application credentials or confidential data into generated code. + +REST contract: +https://learn.microsoft.com/rest/api/data-plane/containerapps/code-execution/execute +""" + +import asyncio +import os +from typing import Annotated, Any +from urllib.parse import urlsplit +from uuid import uuid4 + +import httpx +from agent_framework import Agent, tool +from agent_framework.foundry import FoundryChatClient +from azure.identity.aio import AzureCliCredential +from dotenv import load_dotenv + +load_dotenv() + + +async def main() -> None: + pool_endpoint = os.environ["POOL_MANAGEMENT_ENDPOINT"].rstrip("/") + endpoint = urlsplit(pool_endpoint) + if ( + endpoint.scheme != "https" + or not endpoint.netloc + or "?" in pool_endpoint + or "#" in pool_endpoint + or endpoint.username is not None + ): + raise ValueError("POOL_MANAGEMENT_ENDPOINT must be a trusted HTTPS pool URL without credentials or a query.") + session_id = str(uuid4()) + + async with AzureCliCredential() as credential, httpx.AsyncClient(timeout=70, follow_redirects=False) as http_client: + + @tool + async def execute_python( + code: Annotated[str, "Python code to execute in the remote session."], + ) -> dict[str, Any]: + """Run Python in the conversation's cloud sandbox and return its output and execution status.""" + token = await credential.get_token("https://dynamicsessions.io/.default") + try: + response = await http_client.post( + f"{pool_endpoint}/executions", + params={"api-version": "2025-10-02-preview", "identifier": session_id}, + headers={"Authorization": f"Bearer {token.token}"}, + json={ + "codeInputType": "Inline", + "executionType": "Synchronous", + "code": code, + "timeoutInSeconds": 30, + "outputStreamsMaxLength": 4096, + }, + ) + response.raise_for_status() + except httpx.HTTPStatusError as exc: + # HTTPX errors include the request URL, which contains the session identifier. + raise RuntimeError(f"Session execution failed (HTTP {exc.response.status_code}).") from None + except httpx.RequestError: + raise RuntimeError("Session execution request failed.") from None + execution = response.json() + # Session and operation identifiers belong to the application, not the model. + return {"status": execution.get("status"), "result": execution.get("result")} + + async with Agent( + client=FoundryChatClient( + project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"], + model=os.environ["FOUNDRY_MODEL"], + credential=credential, + ), + instructions="Use execute_python for calculations. Check its status and errors before reporting a result.", + tools=[execute_python], + ) as agent: + result = await agent.run("Use Python to calculate the total of 19.95, 42.50, and 8.75, then add 8% tax.") + print(result.text) + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/tests/samples/tools/test_dynamic_sessions.py b/python/tests/samples/tools/test_dynamic_sessions.py new file mode 100644 index 00000000000..4907b74a5c6 --- /dev/null +++ b/python/tests/samples/tools/test_dynamic_sessions.py @@ -0,0 +1,54 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Exercise the sample tool without Azure credentials or a model invocation.""" + +import ast +import traceback +from pathlib import Path +from types import SimpleNamespace +from typing import Annotated, Any +from unittest.mock import AsyncMock + +import httpx +import pytest + + +@pytest.mark.parametrize("outcome", ["success", "http_error", "transport_error"]) +async def test_session_identifier_is_not_exposed(outcome): + sample = Path(__file__).parents[3] / "samples/02-agents/tools/container_apps_dynamic_sessions.py" + tree = ast.parse(sample.read_text()) + function = next( + node for node in ast.walk(tree) if isinstance(node, ast.AsyncFunctionDef) and node.name == "execute_python" + ) + function.decorator_list = [] + session_id = "private-session-id" + request = httpx.Request("POST", f"https://pool.example/executions?identifier={session_id}") + output = {"stdout": "63", "stderr": "", "executionResult": None} + response = httpx.Response( + 403 if outcome == "http_error" else 200, + json={"identifier": session_id, "id": "private-operation-id", "status": "Succeeded", "result": output}, + request=request, + ) + client = SimpleNamespace(post=AsyncMock(return_value=response)) + if outcome == "transport_error": + client.post.side_effect = httpx.ConnectError(str(request.url), request=request) + namespace = { + "Annotated": Annotated, + "Any": Any, + "httpx": httpx, + "credential": SimpleNamespace(get_token=AsyncMock(return_value=SimpleNamespace(token="token"))), + "http_client": client, + "pool_endpoint": "https://pool.example", + "session_id": session_id, + } + exec(compile(ast.Module(body=[function], type_ignores=[]), str(sample), "exec"), namespace) + if outcome == "success": + assert await namespace["execute_python"]("print(63)") == {"status": "Succeeded", "result": output} + else: + with pytest.raises(RuntimeError) as caught: + await namespace["execute_python"]("print(63)") + rendered = "".join(traceback.format_exception(caught.value)) + assert session_id not in rendered + assert "https://pool.example" not in rendered + assert "403" in str(caught.value) if outcome == "http_error" else "request failed" in str(caught.value) + assert client.post.call_args.kwargs["params"]["identifier"] == session_id