Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions python/samples/02-agents/tools/README.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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.
100 changes: 100 additions & 0 deletions python/samples/02-agents/tools/container_apps_dynamic_sessions.py
Original file line number Diff line number Diff line change
@@ -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())
54 changes: 54 additions & 0 deletions python/tests/samples/tools/test_dynamic_sessions.py
Original file line number Diff line number Diff line change
@@ -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
Loading