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

azure_functions_agents/arm.py

@@ -0,0 +1,95 @@
+import asyncio
+
+import aiohttp
+from azure.identity import DefaultAzureCredential
+
+ARM_BASE = "https://management.azure.com"
+DEFAULT_API_VERSION = "2016-06-01"
+
+
+class ArmClient:
+    def __init__(self):
+        self._credential = DefaultAzureCredential()
+        self._session: aiohttp.ClientSession | None = None
+
+    async def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+    async def _get_token(self) -> str:
+        token = await asyncio.to_thread(
+            self._credential.get_token, "https://management.azure.com/.default"
+        )
+        return token.token
+
+    async def get(self, path: str, *, api_version: str = DEFAULT_API_VERSION, params: dict | None = None) -> dict:
+        session = await self._ensure_session()
+        url = f"{ARM_BASE}{path}"
+        query = {"api-version": api_version}
+        if params:
+            query.update(params)
+        headers = {"Authorization": f"Bearer {await self._get_token()}"}
+        async with session.get(url, headers=headers, params=query) as resp:
+            resp.raise_for_status()
+            return await resp.json()
+
+    async def post(self, path: str, body: dict | None = None, *, api_version: str = DEFAULT_API_VERSION) -> dict:
+        session = await self._ensure_session()
+        url = f"{ARM_BASE}{path}"
+        query = {"api-version": api_version}
+        headers = {"Authorization": f"Bearer {await self._get_token()}"}
+        async with session.post(url, headers=headers, params=query, json=body) as resp:
+            resp.raise_for_status()
+            return await resp.json()
+
+    async def close(self):
+        if self._session and not self._session.closed:
+            await self._session.close()
+        self._credential.close()
+
+
+class DataPlaneClient:
+    """HTTP client for connector data plane invocation (V2 / AI Gateway).
+
+    Uses ``https://apihub.azure.com/.default`` token scope instead of
+    the ARM management plane scope.
+    """
+
+    def __init__(self):
+        self._credential = DefaultAzureCredential()
+        self._session: aiohttp.ClientSession | None = None
+
+    async def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+    async def _get_token(self) -> str:
+        token = await asyncio.to_thread(
+            self._credential.get_token, "https://apihub.azure.com/.default"
+        )
+        return token.token
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        body: dict | None = None,
+        params: dict | None = None,
+    ) -> dict:
+        session = await self._ensure_session()
+        headers = {"Authorization": f"Bearer {await self._get_token()}"}
+        async with session.request(
+            method, url, headers=headers, params=params, json=body
+        ) as resp:
+            resp.raise_for_status()
+            if resp.content_length == 0:
+                return {}
+            return await resp.json()
+
+    async def close(self):
+        if self._session and not self._session.closed:
+            await self._session.close()
+        self._credential.close()

azure_functions_agents/client_manager.py

@@ -0,0 +1,84 @@
+import asyncio
+import logging
+import os
+from typing import Optional
+
+from copilot import CopilotClient, SubprocessConfig
+
+from .config import get_app_root, resolve_config_dir
+
+
+def _is_byok_mode() -> bool:
+    """Check if BYO key (Microsoft Foundry) environment variables are configured."""
+    return bool(
+        os.environ.get("AZURE_AI_FOUNDRY_ENDPOINT")
+        and os.environ.get("AZURE_AI_FOUNDRY_API_KEY")
+    )
+
+
+class CopilotClientManager:
+    """
+    Singleton manager for the CopilotClient.
+    """
+
+    _instance: Optional["CopilotClientManager"] = None
+    _client: Optional[CopilotClient] = None
+    _lock: asyncio.Lock = None
+    _started: bool = False
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._lock = asyncio.Lock()
+        return cls._instance
+
+    @classmethod
+    async def get_client(cls) -> CopilotClient:
+        manager = cls()
+        async with manager._lock:
+            if manager._client is None or not manager._started:
+                app_root = str(get_app_root())
+                config_dir = resolve_config_dir()
+
+                # Pass --config-dir as a CLI startup flag so the subprocess
+                # writes events.jsonl and can load sessions from the shared
+                # mount, enabling cross-instance session resume.
+                cli_args: list[str] = []
+                if config_dir:
+                    cli_args = ["--config-dir", config_dir]
+                    logging.info(f"CLI config-dir: {config_dir}")
+
+                if _is_byok_mode():
+                    logging.info("BYOK mode: using Microsoft Foundry (no GitHub token)")
+                    manager._client = CopilotClient(
+                        SubprocessConfig(cwd=app_root, cli_args=cli_args)
+                    )
+                else:
+                    github_token = os.environ.get("GITHUB_TOKEN")
+                    manager._client = CopilotClient(
+                        SubprocessConfig(
+                            github_token=github_token,
+                            cwd=app_root,
+                            cli_args=cli_args,
+                        )
+                    )
+
+                await manager._client.start()
+                manager._started = True
+                logging.info(f"CopilotClient singleton started (BYOK: {_is_byok_mode()})")
+        return manager._client
+
+    @classmethod
+    async def shutdown(cls):
+        manager = cls()
+        async with manager._lock:
+            if manager._client and manager._started:
+                await manager._client.stop()
+                manager._started = False
+                manager._client = None
+                logging.info("CopilotClient singleton stopped")
+
+    @classmethod
+    def is_running(cls) -> bool:
+        manager = cls()
+        return manager._started

azure_functions_agents/config.py

@@ -0,0 +1,191 @@
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Any, Optional
+
+
+# ---------------------------------------------------------------------------
+# Application root resolution
+# ---------------------------------------------------------------------------
+
+_app_root: Optional[Path] = None
+
+
+def set_app_root(path: Path) -> None:
+    """Explicitly set the application root directory.
+
+    Call this early (e.g. before ``create_function_app()``) so that all
+    agent, tool, skill, and MCP discovery uses the correct base path.
+    """
+    global _app_root
+    _app_root = Path(path).resolve()
+
+
+def get_app_root() -> Path:
+    """Return the root directory of the user's agent project.
+
+    This is the directory containing ``main.agent.md``, ``tools/``,
+    ``.vscode/mcp.json``, skills directories, etc.
+
+    Resolution order:
+
+    1. Value set via ``set_app_root()``
+    2. ``COPILOT_APP_ROOT`` environment variable
+    3. ``AzureWebJobsScriptRoot`` environment variable (set automatically
+       by the Azure Functions host, both locally via ``func start`` and
+       in Azure — points to the directory containing ``host.json``)
+    4. Current working directory (``Path.cwd()``)
+    """
+    if _app_root is not None:
+        return _app_root
+    explicit = os.environ.get("COPILOT_APP_ROOT")
+    if explicit:
+        return Path(explicit).resolve()
+    script_root = os.environ.get("AzureWebJobsScriptRoot")
+    if script_root:
+        return Path(script_root).resolve()
+    return Path.cwd().resolve()
+
+# Default session state directory used by the Copilot CLI
+_DEFAULT_CONFIG_DIR = os.path.expanduser("~/.copilot")
+_REMOTE_CONFIG_DIR = "/code-assistant-session"
+
+
+def resolve_config_dir() -> Optional[str]:
+    """
+    Resolve the config directory for session state persistence.
+
+    Priority:
+    1. CODE_ASSISTANT_CONFIG_PATH env var (explicit override)
+    2. CONTAINER_NAME env var is set → /code-assistant-session (remote/Azure Functions mode)
+    3. Neither set → None (SDK default ~/.copilot/ is used)
+    """
+    explicit_path = os.environ.get("CODE_ASSISTANT_CONFIG_PATH")
+    if explicit_path:
+        logging.info(f"Using CODE_ASSISTANT_CONFIG_PATH: {explicit_path}")
+        return explicit_path
+
+    container_name = os.environ.get("CONTAINER_NAME")
+    if container_name:
+        logging.info(f"Remote mode detected (CONTAINER_NAME={container_name}), using {_REMOTE_CONFIG_DIR}")
+        return _REMOTE_CONFIG_DIR
+
+    return None
+
+
+def session_exists(config_dir: Optional[str], session_id: str) -> bool:
+    """
+    Check if a session exists on disk by looking for its directory.
+
+    Session state is stored under {config_dir}/session-state/{sessionId}/.
+    Falls back to ~/.copilot/session-state/{sessionId}/ if config_dir is None.
+    """
+    base = config_dir if config_dir else _DEFAULT_CONFIG_DIR
+    session_path = os.path.join(base, "session-state", session_id)
+    exists = os.path.isdir(session_path)
+    logging.info(f"Session '{session_id}' exists at {session_path}: {exists}")
+    return exists
+
+
+# ---------------------------------------------------------------------------
+# Environment variable substitution for agent frontmatter values
+# ---------------------------------------------------------------------------
+
+_PERCENT_PATTERN = re.compile(r"^%([^%]+)%$")
+_DOLLAR_PATTERN = re.compile(r"^\$([A-Za-z_][A-Za-z0-9_]*)$")
+
+
+def resolve_env_var(value: str) -> str:
+    """Resolve a frontmatter value that is a single env-var reference.
+
+    Supported syntaxes (full-string match only — partial substitution
+    such as ``prefix$VAR`` is intentionally **not** supported):
+
+      - ``%VAR_NAME%`` — value is entirely ``%…%``
+      - ``$VAR_NAME``  — value is entirely ``$IDENT``
+
+    If the value does not match either pattern, or the referenced
+    environment variable is not set, the original string is returned
+    unchanged.
+
+    The following agent frontmatter fields are resolved through
+    this function (all represent external resource identifiers or
+    endpoints):
+
+      - ``trigger.*`` (all string values except ``type``)
+      - ``tools_from_connections[].connection_id``
+      - ``execution_sandbox.session_pool_management_endpoint``
+
+    Fields that should **not** use substitution (identifiers, literals,
+    or user-facing text): ``name``, ``description``, ``trigger.type``,
+    ``logger``.
+    """
+    stripped = value.strip()
+    m = _PERCENT_PATTERN.match(stripped) or _DOLLAR_PATTERN.match(stripped)
+    if m:
+        return os.environ.get(m.group(1), value)
+    return value
+
+
+# ---------------------------------------------------------------------------
+# Boolean coercion helper
+# ---------------------------------------------------------------------------
+
+
+def _to_bool(value: Any, default: bool = True) -> bool:
+    """Coerce a frontmatter value to bool."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in {"true", "1", "yes", "y"}:
+            return True
+        if lowered in {"false", "0", "no", "n"}:
+            return False
+    return default
+
+
+# ---------------------------------------------------------------------------
+# Inline environment variable substitution for agent markdown body text
+# ---------------------------------------------------------------------------
+
+_INLINE_DOLLAR_PATTERN = re.compile(r"\$([A-Za-z_][A-Za-z0-9_]*)")
+_INLINE_PERCENT_PATTERN = re.compile(r"%([A-Za-z_][A-Za-z0-9_]*)%")
+
+
+def substitute_env_vars_in_text(text: str) -> str:
+    """Perform inline environment variable substitution in free-form text.
+
+    Unlike :func:`resolve_env_var` (which requires the *entire* string to
+    be a single variable reference), this function replaces variable
+    references **inline** within arbitrary text.
+
+    Supported syntaxes:
+
+      - ``$VAR_NAME``  — e.g. ``send mail to $TO_EMAIL``
+      - ``%VAR_NAME%`` — e.g. ``post to the %TEAM_NAME% team``
+
+    If the referenced environment variable is not set, the original
+    reference is left unchanged (fail-open).
+
+    Text inside fenced code blocks (``````...``````) is left untouched
+    so that documentation examples are not accidentally altered.
+    """
+
+    def _dollar_replacer(m: re.Match) -> str:
+        return os.environ.get(m.group(1), m.group(0))
+
+    def _percent_replacer(m: re.Match) -> str:
+        return os.environ.get(m.group(1), m.group(0))
+
+    def _substitute(segment: str) -> str:
+        segment = _INLINE_DOLLAR_PATTERN.sub(_dollar_replacer, segment)
+        segment = _INLINE_PERCENT_PATTERN.sub(_percent_replacer, segment)
+        return segment
+
+    # Split on fenced code blocks (```); odd-indexed parts are code blocks
+    parts = text.split("```")
+    for i in range(0, len(parts), 2):
+        parts[i] = _substitute(parts[i])
+    return "```".join(parts)

azure_functions_agents/connector_tool_cache.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Dict, List
+
+from .arm import ArmClient, DataPlaneClient
+from .config import resolve_env_var
+from .connectors import load_connection, is_v2_connection
+from .connector_tools import generate_tools
+
+
+class _ConnectorToolCache:
+    """Lazy-init singleton cache for connector tools discovered from ARM API."""
+
+    def __init__(self):
+        self._tools: list | None = None
+        self._arm: ArmClient | None = None
+        self._data_plane: DataPlaneClient | None = None
+        self._lock = asyncio.Lock()
+        self._connection_specs: List[Dict[str, Any]] = []
+
+    def add_connection_specs(self, specs: List[Dict[str, Any]]) -> None:
+        """Append tools_from_connections specs from an agent file.
+
+        Deduplicates by resolved connection_id so the same connector
+        isn't loaded twice even if referenced from multiple agents.
+        """
+        if not specs:
+            return
+        existing_ids = {
+            resolve_env_var(str(s.get("connection_id", "")))
+            for s in self._connection_specs
+        }
+        for spec in specs:
+            cid = resolve_env_var(str(spec.get("connection_id", "")))
+            if cid and cid not in existing_ids:
+                self._connection_specs.append(spec)
+                existing_ids.add(cid)
+
+    async def get_tools(self) -> list:
+        """Return cached connector tools, discovering them on first call."""
+        if self._tools is not None:
+            return self._tools
+
+        async with self._lock:
+            # Double-check after acquiring lock
+            if self._tools is not None:
+                return self._tools
+
+            if not self._connection_specs:
+                self._tools = []
+                return self._tools
+
+            self._arm = ArmClient()
+            all_tools = []
+
+            # Check if any V2 connections need a data plane client
+            has_v2 = any(
+                is_v2_connection(resolve_env_var(str(s.get("connection_id", ""))))
+                for s in self._connection_specs
+            )
+            if has_v2:
+                self._data_plane = DataPlaneClient()
+
+            for spec in self._connection_specs:
+                raw_connection_id = spec.get("connection_id", "")
+                if not raw_connection_id:
+                    logging.warning("tools_from_connections entry missing 'connection_id', skipping")
+                    continue
+
+                connection_id = resolve_env_var(str(raw_connection_id))
+                if not connection_id or connection_id.startswith("%") or connection_id.startswith("$"):
+                    logging.warning(f"tools_from_connections: could not resolve connection_id '{raw_connection_id}', skipping")
+                    continue
+
+                try:
+                    v2 = is_v2_connection(connection_id)
+                    connection = await load_connection(
+                        self._arm, connection_id,
+                        data_plane_client=self._data_plane if v2 else None,
+                    )
+
+                    # Determine tool name prefix: explicit > connection name > api_name
+                    prefix = spec.get("prefix")
+                    if isinstance(prefix, str) and prefix.strip():
+                        prefix = prefix.strip()
+                    else:
+                        prefix = None  # generate_tools will use connection.name
+
+                    tools = generate_tools(
+                        self._arm, connection, prefix=prefix,
+                        data_plane_client=self._data_plane if v2 else None,
+                    )
+                    all_tools.extend(tools)
+                    version_label = "V2" if v2 else "V1"
+                    logging.info(
+                        f"Connector tools discovered ({version_label}): {connection.display_name} ({connection.api_name}): "
+                        f"{len(tools)} tools [{connection.status}]"
+                    )
+                    for tool in tools:
+                        logging.info(f"  - {tool.name}: {tool.description[:100]}")
+                except Exception as e:
+                    logging.warning(f"Failed to load connector tools for '{connection_id}': {e}")
+
+            self._tools = all_tools
+            return self._tools
+
+
+_cache = _ConnectorToolCache()
+
+
+def configure_connector_tools(tools_from_connections: List[Dict[str, Any]]) -> None:
+    """Add connector tool specs from an agent file to the global cache.
+
+    Can be called multiple times (once per agent file). Specs are
+    deduplicated by connection_id so the same connector isn't loaded twice.
+    """
+    _cache.add_connection_specs(tools_from_connections)
+
+
+async def get_connector_tools() -> list:
+    """Get cached connector tools (lazy-discovers on first call)."""
+    return await _cache.get_tools()