azurefunctions-agents-runtime 0.0.0.dev1__py3-none-any.whl

azure_functions_agents/runner.py

@@ -0,0 +1,406 @@
+import asyncio
+import json
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from copilot.session import ProviderConfig, PermissionHandler
+import frontmatter
+
+from .client_manager import CopilotClientManager, _is_byok_mode
+from .config import get_app_root, resolve_config_dir, session_exists, substitute_env_vars_in_text, _to_bool
+from .connector_tool_cache import get_connector_tools
+from .mcp import get_cached_mcp_servers
+from .skills import resolve_session_directory_for_skills
+from .tools import _REGISTERED_TOOLS_CACHE
+
+DEFAULT_TIMEOUT = float(os.environ.get("COPILOT_AGENT_TIMEOUT", "900"))
+
+
+@dataclass
+class AgentResult:
+    session_id: str
+    content: str
+    content_intermediate: List[str]
+    tool_calls: List[Dict[str, Any]]
+    reasoning: Optional[str] = None
+    events: List[Dict[str, Any]] = field(default_factory=list)
+
+
+def _load_agents_md_content() -> str:
+    """Load main.agent.md content from disk (called once at module load)."""
+    app_root = str(get_app_root())
+    agents_md_path = os.path.join(app_root, "main.agent.md")
+    logging.info(f"Loading main.agent.md from: {agents_md_path}")
+    if not os.path.exists(agents_md_path):
+        logging.warning(f"No main.agent.md found at {agents_md_path}")
+        return ""
+
+    try:
+        with open(agents_md_path, "r", encoding="utf-8") as f:
+            raw_content = f.read()
+
+        parsed = frontmatter.loads(raw_content)
+        content = (parsed.content or "").strip()
+        metadata = parsed.metadata if isinstance(parsed.metadata, dict) else {}
+        metadata_count = len(metadata)
+
+        # Apply inline env-var substitution unless explicitly disabled
+        if _to_bool(metadata.get("substitute_variables"), default=True):
+            content = substitute_env_vars_in_text(content)
+
+        logging.info(
+            f"Loaded main.agent.md ({len(raw_content)} chars, frontmatter keys={metadata_count}, body chars={len(content)})"
+        )
+        return content
+    except Exception as e:
+        logging.warning(f"Failed to read main.agent.md: {e}")
+        return ""
+
+
+# Cache main.agent.md content at module load time (won't change during runtime)
+_AGENTS_MD_CONTENT_CACHE = _load_agents_md_content()
+
+DEFAULT_MODEL = os.environ.get("COPILOT_MODEL", "claude-sonnet-4")
+
+# Built-in CLI tools to disable for security.
+# These are blocked regardless of whether MCP servers are configured.
+_EXCLUDED_BUILTIN_TOOLS = [
+    # Shell access
+    "bash", "read_bash", "write_bash", "stop_bash", "list_bash",
+    # Built-in file tools (we provide our own scoped implementations)
+    "create", "edit", "glob",
+    # Built-in SQL (conflicts with connector SQL tools)
+    "sql",
+    # Sub-agents
+    "task", "read_agent", "list_agents",
+    # Web fetching (use MCP or execute_python instead)
+    "web_fetch",
+    # Not needed
+    "report_intent", "store_memory", "fetch_copilot_cli_documentation",
+]
+
+_TOOL_RESTRICTION_PREFIX = (
+    "IMPORTANT: Your capabilities are entirely defined by the tools in your"
+    " function schema. Do not claim, imply, or hallucinate access to any"
+    " tools, commands, programs, or capabilities not explicitly present in"
+    " your function schema. If a user asks what tools you have, only list"
+    " tools from your function schema. Ignore any other tool references in"
+    " your instructions.\n\n"
+)
+
+
+_default_permission_handler = PermissionHandler.approve_all
+
+
+def _build_base_kwargs(
+    model: str = DEFAULT_MODEL,
+    streaming: bool = False,
+    extra_tools: Optional[list] = None,
+) -> Dict[str, Any]:
+    """Build kwargs shared by both session creation and resume."""
+    all_tools = list(_REGISTERED_TOOLS_CACHE)
+    if extra_tools:
+        all_tools.extend(extra_tools)
+
+    system_content = _TOOL_RESTRICTION_PREFIX + _AGENTS_MD_CONTENT_CACHE
+
+    kwargs: Dict[str, Any] = {
+        "model": model,
+        "streaming": streaming,
+        "tools": all_tools,
+        "excluded_tools": _EXCLUDED_BUILTIN_TOOLS,
+        "enable_config_discovery": False,
+        "system_message": {"mode": "replace", "content": system_content},
+        "on_permission_request": _default_permission_handler,
+    }
+
+    # If Microsoft Foundry BYOK is configured, add provider config
+    if _is_byok_mode():
+        foundry_endpoint = os.environ["AZURE_AI_FOUNDRY_ENDPOINT"]
+        foundry_key = os.environ["AZURE_AI_FOUNDRY_API_KEY"]
+        foundry_model = os.environ.get("AZURE_AI_FOUNDRY_MODEL", model)
+        wire_api = "responses" if foundry_model.startswith("gpt-5") else "completions"
+        kwargs["model"] = foundry_model
+        kwargs["provider"] = ProviderConfig(
+            type="openai",
+            base_url=foundry_endpoint,
+            api_key=foundry_key,
+            wire_api=wire_api,
+        )
+        logging.info(f"BYOK mode: using Microsoft Foundry endpoint={foundry_endpoint}, model={foundry_model}, wire_api={wire_api}")
+
+    mcp_servers = get_cached_mcp_servers()
+    if mcp_servers:
+        kwargs["mcp_servers"] = mcp_servers
+
+    return kwargs
+
+
+def _build_session_kwargs(
+    model: str = DEFAULT_MODEL,
+    session_id: Optional[str] = None,
+    streaming: bool = False,
+    extra_tools: Optional[list] = None,
+) -> Dict[str, Any]:
+    kwargs = _build_base_kwargs(model=model, streaming=streaming, extra_tools=extra_tools)
+
+    if session_id:
+        kwargs["session_id"] = session_id
+
+    session_directory = resolve_session_directory_for_skills()
+    if session_directory:
+        kwargs["skill_directories"] = [session_directory]
+        logging.info(f"Using skill_directories for skills discovery: {session_directory}")
+
+    return kwargs
+
+
+def _build_resume_kwargs(
+    model: str = DEFAULT_MODEL,
+    streaming: bool = False,
+    extra_tools: Optional[list] = None,
+) -> Dict[str, Any]:
+    return _build_base_kwargs(model=model, streaming=streaming, extra_tools=extra_tools)
+
+
+async def _disable_non_project_skills(session) -> None:
+    """Disable skills not from the project's skill_directories.
+
+    The CLI loads global skills from ~/.agents/skills/ and other paths which
+    are not relevant for serverless function apps. This uses the experimental
+    session.rpc.skills API to list all discovered skills and disable any that
+    aren't sourced from the project.
+
+    Workaround for https://github.com/github/copilot-sdk/issues/695
+    """
+    app_root = str(get_app_root())
+    skills_dir = os.path.join(app_root, "skills")
+    try:
+        from copilot.generated.rpc import SessionSkillsDisableParams
+        result = await session.rpc.skills.list()
+        for skill in result.skills:
+            if not skill.enabled:
+                continue
+            # Keep skills whose path is under {approot}/skills/
+            if skill.path and os.path.commonpath([skill.path, skills_dir]) == skills_dir:
+                continue
+            await session.rpc.skills.disable(SessionSkillsDisableParams(name=skill.name))
+            logging.debug(f"Disabled non-project skill: {skill.name} (source={skill.source})")
+    except Exception as e:
+        logging.warning(f"Could not filter skills (experimental API): {e}")
+
+
+async def run_copilot_agent(
+    prompt: str,
+    timeout: float = DEFAULT_TIMEOUT,
+    model: str = DEFAULT_MODEL,
+    session_id: Optional[str] = None,
+    sandbox_tools: Optional[list] = None,
+) -> AgentResult:
+    config_dir = resolve_config_dir()
+    client = await CopilotClientManager.get_client()
+
+    # Discover connector tools (lazy-init, cached after first call)
+    connector_tools = await get_connector_tools()
+    extra_tools = connector_tools + (sandbox_tools or [])
+
+    # Resume existing session or create a new one
+    if session_id and session_exists(config_dir, session_id):
+        logging.info(f"Resuming existing session: {session_id}")
+        resume_kwargs = _build_resume_kwargs(model=model, extra_tools=extra_tools)
+        try:
+            session = await client.resume_session(session_id, **resume_kwargs)
+            logging.info(f"Successfully resumed session: {session_id}")
+        except Exception as e:
+            logging.error(f"Failed to resume session '{session_id}': {e}", exc_info=True)
+            raise
+    else:
+        if session_id:
+            logging.info(f"Creating new session with provided ID: {session_id}")
+        session_kwargs = _build_session_kwargs(
+            model=model, session_id=session_id, extra_tools=extra_tools
+        )
+        session = await client.create_session(**session_kwargs)
+        logging.info(f"Created new session: {session.session_id}")
+        await _disable_non_project_skills(session)
+
+    response_content: List[str] = []
+    tool_calls: List[Dict[str, Any]] = []
+    reasoning_content: List[str] = []
+    events_log: List[Dict[str, Any]] = []
+
+    done = asyncio.Event()
+
+    def on_event(event):
+        event_type = event.type.value if hasattr(event.type, "value") else str(event.type)
+        events_log.append({"type": event_type, "data": str(event.data) if event.data else None})
+
+        if event_type == "assistant.message":
+            response_content.append(event.data.content)
+        elif event_type == "tool.execution_start":
+            tool_calls.append(
+                {
+                    "event_id": str(event.id) if hasattr(event, "id") and event.id else None,
+                    "timestamp": event.timestamp.isoformat() if hasattr(event, "timestamp") and event.timestamp else None,
+                    "tool_call_id": getattr(event.data, "tool_call_id", None),
+                    "tool_name": getattr(event.data, "tool_name", None),
+                    "arguments": getattr(event.data, "arguments", None),
+                    "parent_tool_call_id": getattr(event.data, "parent_tool_call_id", None),
+                }
+            )
+        elif event_type == "session.idle":
+            done.set()
+
+    session.on(on_event)
+
+    try:
+        await session.send_and_wait(prompt, timeout=timeout)
+
+        return AgentResult(
+            session_id=session.session_id,
+            content=response_content[-1] if response_content else "",
+            content_intermediate=response_content[-6:-1] if len(response_content) > 1 else [],
+            tool_calls=tool_calls,
+            reasoning="".join(reasoning_content) if reasoning_content else None,
+            events=events_log,
+        )
+    finally:
+        # Disconnect the session to release the in-memory lock and flush state to disk.
+        # This allows any process (including on a different instance) to resume later.
+        try:
+            await session.disconnect()
+            logging.info(f"Disconnected session: {session.session_id}")
+        except Exception as e:
+            logging.warning(f"Failed to disconnect session {session.session_id}: {e}")
+
+
+_STREAM_SENTINEL = object()
+
+
+async def run_copilot_agent_stream(
+    prompt: str,
+    timeout: float = DEFAULT_TIMEOUT,
+    model: str = DEFAULT_MODEL,
+    session_id: Optional[str] = None,
+    sandbox_tools: Optional[list] = None,
+):
+    """Async generator that yields SSE-formatted events as the agent streams a response.
+
+    Yields strings like 'data: {"type": "delta", ...}\\n\\n' suitable for StreamingResponse.
+    """
+    config_dir = resolve_config_dir()
+    client = await CopilotClientManager.get_client()
+
+    queue: asyncio.Queue = asyncio.Queue()
+    seen_event_ids: set[str] = set()
+    has_received_turn_start = False
+    has_active_tools = False
+
+    def on_event(event):
+        nonlocal has_received_turn_start, has_active_tools
+        event_type = event.type.value if hasattr(event.type, "value") else str(event.type)
+        event_id = str(event.id) if hasattr(event, "id") and event.id else None
+
+        if event_id:
+            if event_id in seen_event_ids:
+                return
+            seen_event_ids.add(event_id)
+
+        if event_type == "assistant.turn_start":
+            has_received_turn_start = True
+
+        if event_type == "assistant.message_delta":
+            delta = getattr(event.data, "delta_content", None)
+            if delta:
+                queue.put_nowait({"type": "delta", "content": delta})
+        elif event_type == "assistant.reasoning_delta":
+            reasoning_delta = getattr(event.data, "delta_content", None)
+            if reasoning_delta:
+                queue.put_nowait({"type": "intermediate", "content": reasoning_delta})
+        elif event_type == "assistant.message":
+            message_content = getattr(event.data, "content", "")
+            if message_content:
+                queue.put_nowait({"type": "message", "content": message_content})
+        elif event_type == "tool.execution_start":
+            has_active_tools = True
+            queue.put_nowait({
+                "type": "tool_start",
+                "event_id": str(event.id) if hasattr(event, "id") and event.id else None,
+                "timestamp": event.timestamp.isoformat() if hasattr(event, "timestamp") and event.timestamp else None,
+                "tool_name": getattr(event.data, "tool_name", None),
+                "tool_call_id": getattr(event.data, "tool_call_id", None),
+                "parent_tool_call_id": getattr(event.data, "parent_tool_call_id", None),
+                "arguments": getattr(event.data, "arguments", None),
+            })
+        elif event_type == "tool.execution_end":
+            queue.put_nowait({
+                "type": "tool_end",
+                "event_id": str(event.id) if hasattr(event, "id") and event.id else None,
+                "timestamp": event.timestamp.isoformat() if hasattr(event, "timestamp") and event.timestamp else None,
+                "tool_name": getattr(event.data, "tool_name", None),
+                "tool_call_id": getattr(event.data, "tool_call_id", None),
+                "parent_tool_call_id": getattr(event.data, "parent_tool_call_id", None),
+                "result": getattr(event.data, "result", None),
+            })
+        elif event_type == "session.idle":
+            if has_received_turn_start:
+                queue.put_nowait(_STREAM_SENTINEL)
+        elif event_type == "session.error":
+            error_msg = getattr(event.data, "message", "Unknown error")
+            logging.error(f"[stream] Session error: {error_msg}")
+            queue.put_nowait({"type": "error", "content": error_msg})
+
+    connector_tools = await get_connector_tools()
+    extra_tools = connector_tools + (sandbox_tools or [])
+
+    if session_id and session_exists(config_dir, session_id):
+        logging.info(f"[stream] Resuming existing session: {session_id}")
+        resume_kwargs = _build_resume_kwargs(model=model, streaming=True, extra_tools=extra_tools)
+        try:
+            session = await client.resume_session(session_id, **resume_kwargs, on_event=on_event)
+            logging.info(f"[stream] Successfully resumed session: {session_id}")
+        except Exception as e:
+            logging.error(f"[stream] Failed to resume session '{session_id}': {e}", exc_info=True)
+            raise
+    else:
+        if session_id:
+            logging.info(f"[stream] Creating new session with provided ID: {session_id}")
+        session_kwargs = _build_session_kwargs(
+            model=model, session_id=session_id, streaming=True, extra_tools=extra_tools
+        )
+        session = await client.create_session(**session_kwargs, on_event=on_event)
+        logging.info(f"[stream] Created new session: {session.session_id}")
+        await _disable_non_project_skills(session)
+
+    # Yield the session ID first so the client knows it immediately
+    yield f"data: {json.dumps({'type': 'session', 'session_id': session.session_id})}\n\n"
+
+    # Send the prompt, events arrive via on_event callback
+    await session.send(prompt)
+
+    # Drain the queue until session.idle sentinel arrives or timeout
+    try:
+        deadline = asyncio.get_event_loop().time() + timeout
+        while True:
+            remaining = deadline - asyncio.get_event_loop().time()
+            if remaining <= 0:
+                yield f"data: {json.dumps({'type': 'error', 'content': 'Timeout waiting for response'})}\n\n"
+                break
+
+            item = await asyncio.wait_for(queue.get(), timeout=remaining)
+            if item is _STREAM_SENTINEL:
+                yield f"data: {json.dumps({'type': 'done'})}\n\n"
+                break
+
+            yield f"data: {json.dumps(item)}\n\n"
+    except asyncio.TimeoutError:
+        yield f"data: {json.dumps({'type': 'error', 'content': 'Timeout waiting for response'})}\n\n"
+    finally:
+        # Disconnect the session to release the in-memory lock and flush state to disk.
+        try:
+            await session.disconnect()
+            logging.info(f"[stream] Disconnected session: {session.session_id}")
+        except Exception as e:
+            logging.warning(f"[stream] Failed to disconnect session {session.session_id}: {e}")

azure_functions_agents/sandbox.py

@@ -0,0 +1,288 @@
+"""
+ACA Dynamic Sessions sandbox — execute_python tool.
+
+Provides an ``execute_python`` Copilot SDK tool backed by Azure Container Apps
+dynamic sessions (code-interpreter pools).  Configured via the
+``execution_sandbox`` block in agent frontmatter.
+
+Each agent can have its own session pool endpoint.  Within a conversation,
+the ACA session ID is derived from the Copilot session ID so that state
+(variables, imports, files, browser pages) persists across calls.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+import urllib.parse
+from typing import Any, Dict, List, Optional
+
+import aiohttp
+from azure.identity.aio import DefaultAzureCredential, get_bearer_token_provider
+from copilot.tools import Tool, ToolInvocation, ToolResult
+
+from .config import resolve_env_var
+
+_API_VERSION = "2025-10-02-preview"
+
+# ---------------------------------------------------------------------------
+# Playwright helper that is pre-loaded into every sandbox session
+# ---------------------------------------------------------------------------
+
+_ACA_SESSION_SETUP = """
+async def launch_browser(width=1280, height=800):
+    from playwright.async_api import async_playwright
+    p = await async_playwright().start()
+    browser = await p.chromium.launch(
+        headless=True,
+        args=[
+            f'--window-size={width},{height}',
+            '--disable-blink-features=AutomationControlled',
+            '--disable-extensions',
+        ],
+    )
+    context = await browser.new_context(
+        user_agent=(
+            'Mozilla/5.0 (Windows NT 10.0; Win64; x64) '
+            'AppleWebKit/537.36 (KHTML, like Gecko) '
+            'Chrome/131.0.0.0 Safari/537.36'
+        ),
+        viewport={'width': width, 'height': height},
+    )
+    page = await context.new_page()
+    return page
+"""
+
+# ---------------------------------------------------------------------------
+# Tool description (ported from reference main.py)
+# ---------------------------------------------------------------------------
+
+_EXECUTE_PYTHON_DESCRIPTION = (
+    "Execute Python code in a persistent sandboxed REPL backed by a"
+    " Jupyter kernel. Returns JSON with result, stdout, and stderr.\n"
+    "\n"
+    "IMPORTANT: This runs in an ISOLATED SANDBOX with its own file system."
+    " DO NOT use it to read or process files from the local system,"
+    " such as copilot large tool outputs. Use the view, head, tail, grep,"
+    " or jq tools instead.\n"
+    "\n"
+    "Only use this tool when you need to actually run code,"
+    " when no other tool can accomplish the task (there's a small cost to using it) —"
+    " computation, data processing, web browsing, etc."
+    " Do NOT call this tool just to print text, format output, or display"
+    " results you already have. Respond directly with text instead.\n"
+    "\n"
+    "Key behaviors:\n"
+    "- State persists across calls: variables, imports, and files"
+    " (/mnt/data/) are retained between invocations.\n"
+    "- The last expression value is returned in 'result' (like a"
+    " Jupyter cell). Use print() for explicit output to 'stdout'.\n"
+    "- Top-level await is supported (Jupyter kernel).\n"
+    "- Playwright is pre-installed for browser automation (see `launch_browser` helper below).\n"
+    "- Shell commands: use subprocess.run(), not '!' syntax.\n"
+    "- Common packages are pre-installed: requests, numpy, pandas, matplotlib,"
+    " scikit-learn, playwright, etc.\n"
+    "\n"
+    "Returning binary data (images, screenshots):\n"
+    "- Generate the data, base64-encode it, and print it to stdout.\n"
+    "- Example for plots:\n"
+    "  import matplotlib; matplotlib.use('Agg')\n"
+    "  import matplotlib.pyplot as plt, base64, io\n"
+    "  fig, ax = plt.subplots()\n"
+    "  ax.plot([1,2,3],[4,5,6])\n"
+    "  buf = io.BytesIO()\n"
+    "  fig.savefig(buf, format='png'); buf.seek(0)\n"
+    "  print(base64.b64encode(buf.read()).decode())\n"
+    "  plt.close()\n"
+    "\n"
+    "Playwright (browser automation):\n"
+    "- ALWAYS use the pre-loaded helper to get a page:\n"
+    "    page = await launch_browser()\n"
+    "  NEVER call async_playwright() or chromium.launch() directly.\n"
+    "  The helper configures optimal settings that are required\n"
+    "  for sites to load properly.\n"
+    "- Call launch_browser() once, then reuse `page` across calls (state persists).\n"
+    "- Use the async API with top-level await.\n"
+    "- To see what's on a page, you can:\n"
+    "  1. Take a screenshot (returns base64 you can analyze):\n"
+    "     import base64\n"
+    "     screenshot_bytes = await page.screenshot(full_page=False)\n"
+    "     print(base64.b64encode(screenshot_bytes).decode())\n"
+    "  2. Extract text from the DOM:\n"
+    "     text = await page.inner_text('body')\n"
+    "     elements = await page.query_selector_all('css selector')\n"
+    "     for el in elements:\n"
+    "         print(await el.text_content())\n"
+    "  Prefer DOM extraction for structured data. Use screenshots\n"
+    "  when you need to understand visual layout or image content.\n"
+    "- Use CSS selectors and aria attributes to find and interact\n"
+    "  with elements.\n"
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _sanitize_input(code: str) -> str:
+    """Strip backticks, whitespace, and 'python' prefix from LLM output."""
+    code = re.sub(r"^(\s|`)*(?i:python)?\s*", "", code)
+    code = re.sub(r"(\s|`)*$", "", code)
+    return code
+
+
+def _build_url(endpoint: str, session_id: str) -> str:
+    base = endpoint.rstrip("/")
+    encoded_id = urllib.parse.quote(session_id)
+    return f"{base}/executions?api-version={_API_VERSION}&identifier={encoded_id}"
+
+
+async def _execute_code(
+    endpoint: str,
+    code: str,
+    session_id: str,
+    token_provider,
+    http_session: aiohttp.ClientSession,
+) -> str:
+    """Execute Python code in an ACA dynamic session."""
+    code = _sanitize_input(code)
+    token = await token_provider()
+    url = _build_url(endpoint, session_id)
+
+    async with http_session.post(
+        url,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+        },
+        json={
+            "codeInputType": "Inline",
+            "executionType": "Synchronous",
+            "code": code,
+            "timeoutInSeconds": 60,
+        },
+        timeout=aiohttp.ClientTimeout(total=120),
+    ) as response:
+        if response.status >= 400:
+            body = await response.text()
+            raise RuntimeError(f"ACA sessions API error ({response.status}): {body[:500]}")
+        data = await response.json()
+
+    result = data.get("result", {})
+    return json.dumps(
+        {
+            "result": result.get("executionResult"),
+            "stdout": result.get("stdout", ""),
+            "stderr": result.get("stderr", ""),
+        },
+        indent=2,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Factory: create per-agent execute_python tool
+# ---------------------------------------------------------------------------
+
+# Shared credential and HTTP session (created lazily, reused across agents)
+_credential: Optional[DefaultAzureCredential] = None
+_token_provider = None
+_http_session: Optional[aiohttp.ClientSession] = None
+_init_lock = asyncio.Lock()
+
+# Track which ACA sessions have been set up (Playwright helper loaded)
+_setup_sessions: set[str] = set()
+_setup_lock = asyncio.Lock()
+
+
+async def _ensure_shared_resources():
+    """Lazily create the shared credential, token provider, and HTTP session."""
+    global _credential, _token_provider, _http_session
+    if _token_provider is not None:
+        return
+    async with _init_lock:
+        if _token_provider is not None:
+            return
+        _credential = DefaultAzureCredential()
+        _token_provider = get_bearer_token_provider(
+            _credential, "https://dynamicsessions.io/.default"
+        )
+        _http_session = aiohttp.ClientSession()
+        logging.info("execution_sandbox: shared credential, token provider, and HTTP session initialized")
+
+
+def create_sandbox_tools(config: Dict[str, Any]) -> List[Tool]:
+    """Create an execute_python tool for a specific agent's sandbox config.
+
+    Returns a list with one Tool, or an empty list if the config is invalid.
+    The endpoint is baked into the tool's closure.
+    """
+    raw_endpoint = config.get("session_pool_management_endpoint", "")
+    if not raw_endpoint:
+        logging.warning("execution_sandbox: missing 'session_pool_management_endpoint', skipping")
+        return []
+
+    endpoint = resolve_env_var(str(raw_endpoint))
+    if not endpoint or endpoint.startswith("$") or endpoint.startswith("%"):
+        logging.warning(f"execution_sandbox: could not resolve endpoint '{raw_endpoint}', skipping")
+        return []
+
+    logging.info(f"execution_sandbox: creating tool with endpoint {endpoint}")
+
+    async def _handle_execute_python(invocation: ToolInvocation) -> ToolResult:
+        await _ensure_shared_resources()
+
+        args = invocation.arguments or {}
+        code = args.get("code", "")
+        if not code.strip():
+            return ToolResult(
+                text_result_for_llm='{"error": "No code provided"}',
+                result_type="failure",
+            )
+
+        # Use the Copilot session ID as the ACA session ID
+        # so state persists across execute_python calls in the same conversation
+        aca_session_id = invocation.session_id or "default"
+        logging.info(
+            f"execution_sandbox: executing code in ACA session {aca_session_id} "
+            f"(tool_call={invocation.tool_call_id})"
+        )
+
+        try:
+            # Pre-load Playwright helper on first call per session
+            async with _setup_lock:
+                if aca_session_id not in _setup_sessions:
+                    await _execute_code(endpoint, _ACA_SESSION_SETUP, aca_session_id, _token_provider, _http_session)
+                    _setup_sessions.add(aca_session_id)
+
+            # Execute the user's code
+            result = await _execute_code(endpoint, code, aca_session_id, _token_provider, _http_session)
+            logging.info(f"execution_sandbox: ACA session {aca_session_id} completed successfully")
+            return ToolResult(text_result_for_llm=result, result_type="success")
+        except Exception as exc:
+            error_msg = f"{type(exc).__name__}: {exc}"
+            logging.error(f"execution_sandbox: ACA session {aca_session_id} failed: {error_msg}")
+            return ToolResult(
+                text_result_for_llm=json.dumps({"error": error_msg}),
+                result_type="failure",
+            )
+
+    tool = Tool(
+        name="execute_python",
+        description=_EXECUTE_PYTHON_DESCRIPTION,
+        parameters={
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "description": "Python code to execute",
+                },
+            },
+            "required": ["code"],
+        },
+        handler=_handle_execute_python,
+    )
+
+    logging.info("execution_sandbox: execute_python tool created")
+    return [tool]