diff --git a/python/AGENTS.md b/python/AGENTS.md index f910919f95..80173560f7 100644 --- a/python/AGENTS.md +++ b/python/AGENTS.md @@ -93,3 +93,4 @@ python/ ### Experimental - [lab](packages/lab/AGENTS.md) - Experimental features +- [monty](packages/monty/AGENTS.md) - Monty-backed CodeAct integrations (alpha) diff --git a/python/PACKAGE_STATUS.md b/python/PACKAGE_STATUS.md index 2b9730a890..1f336f1cd8 100644 --- a/python/PACKAGE_STATUS.md +++ b/python/PACKAGE_STATUS.md @@ -37,6 +37,7 @@ Status is grouped into these buckets: | `agent-framework-hyperlight` | `python/packages/hyperlight` | `beta` | | `agent-framework-lab` | `python/packages/lab` | `beta` | | `agent-framework-mem0` | `python/packages/mem0` | `beta` | +| `agent-framework-monty` | `python/packages/monty` | `alpha` | | `agent-framework-ollama` | `python/packages/ollama` | `beta` | | `agent-framework-openai` | `python/packages/openai` | `released` | | `agent-framework-orchestrations` | `python/packages/orchestrations` | `beta` | diff --git a/python/packages/monty/AGENTS.md b/python/packages/monty/AGENTS.md new file mode 100644 index 0000000000..b8466af8c1 --- /dev/null +++ b/python/packages/monty/AGENTS.md @@ -0,0 +1,78 @@ +# Monty Package (agent-framework-monty) + +Monty-backed CodeAct integrations for the Microsoft Agent Framework. + +> [!NOTE] +> **Alpha package.** Not part of `agent-framework[all]` yet. Install explicitly +> with `pip install agent-framework-monty --pre`. + +## Core Classes + +- **`MontyCodeActProvider`** — `ContextProvider` that injects a run-scoped + `execute_code` tool plus dynamic CodeAct instructions. Mirrors the + `HyperlightCodeActProvider` API for the parts that apply to a non-sandboxed + Python interpreter. +- **`MontyExecuteCodeTool`** — `FunctionTool` that wraps the Monty interpreter. + Use directly for mixed-tool agents or manual static wiring. Mirrors + `HyperlightExecuteCodeTool`. + +## Public API + +```python +from agent_framework_monty import ( + FileMount, + FileMountInput, + MontyCodeActProvider, + MontyExecuteCodeTool, + MountMode, +) +``` + +`MontyCodeActProvider` and `MontyExecuteCodeTool` both accept: +- `tools` — host tool callables / `FunctionTool`s +- `approval_mode` — `"never_require"` (default) or `"always_require"` +- `workspace_root` — host directory auto-mounted at `/input` + (mirrors `HyperlightCodeActProvider.workspace_root`) +- `file_mounts` — sequence of `FileMountInput` (str shorthand, + `(host_path, mount_path)` tuple, or `FileMount`) +- `resource_limits` — Monty `ResourceLimits` TypedDict + +Tool-management methods on both classes: `add_tools`, `get_tools`, +`remove_tool`, `clear_tools`. Mount-management methods: `add_file_mounts`, +`get_file_mounts`, `remove_file_mount`, `clear_file_mounts`. + +`MontyExecuteCodeTool` additionally exposes: +- `build_instructions(*, tools_visible_to_model: bool) -> str` +- `create_run_tool() -> MontyExecuteCodeTool` +- `build_serializable_state() -> dict[str, Any]` +- `workspace_root`, `resource_limits` properties + +## Architecture + +- **`_types.py`** — `FileMount`, `FileMountInput`, `MountMode` (public). +- **`_provider.py`** — `MontyCodeActProvider` (thin wrapper around the tool). +- **`_execute_code_tool.py`** — `MontyExecuteCodeTool` plus tool / mount + normalization, approval helpers, dynamic `description`/`instructions` + builders, and the post-execution file-capture flow that surfaces files + written to `read-write` mounts as `Content.from_data` items. +- **`_monty_bridge.py`** — `InlineCodeBridge` and `generate_type_stubs`, + adapted from the reference Monty CodeAct repo. Pauses on `FunctionSnapshot` + to dispatch host calls, then resumes; supports direct typed tool calls, + the `call_tool` fallback, `asyncio.gather` fan-out, and forwards + ``mount`` / ``limits`` to `Monty(...).start(...)`. +- **`_instructions.py`** — dynamic instruction / tool-description builders + (include filesystem capability summaries when mounts are configured). + +## Not implemented (yet) + +| Capability | Monty primitive | Status | +|------------|-----------------|--------| +| Custom virtual filesystem | `OSAccess` subclass passed to `Monty(...).start(os=...)` | Not exposed. Strictly more general than file mounts; useful when you want a fully synthetic FS. | +| Outbound URL allow-list | No Monty primitive — expose `fetch_url` as a host tool with the allow-list check in your tool function. | Not exposed in this package; users add it as a regular tool. | + +## Out of scope (for now) + +- **Durable execution** — the reference Monty CodeAct repo also offers a + Durable-Functions-backed mode (`DurableCodeBridge`, `register_durable_codeact`, + `wait_for_external_event`, per-tool approval via external events). That is + intentionally not in this package yet. diff --git a/python/packages/monty/LICENSE b/python/packages/monty/LICENSE new file mode 100644 index 0000000000..9e841e7a26 --- /dev/null +++ b/python/packages/monty/LICENSE @@ -0,0 +1,21 @@ + MIT License + + Copyright (c) Microsoft Corporation. + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in all + copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE diff --git a/python/packages/monty/README.md b/python/packages/monty/README.md new file mode 100644 index 0000000000..83d1ae79d1 --- /dev/null +++ b/python/packages/monty/README.md @@ -0,0 +1,179 @@ +# agent-framework-monty + +Monty-backed CodeAct integrations for Microsoft Agent Framework. + +> [!WARNING] +> This package is in **alpha**. APIs may change without notice. It is not part of +> `agent-framework[all]` yet; install it explicitly with `--pre`. + +## Installation + +```bash +pip install agent-framework-monty --pre +``` + +The package depends on [`pydantic-monty`](https://github.com/pydantic/monty), a +Rust-based Python interpreter, so it runs on Linux, macOS, and Windows wherever +Monty wheels are published — no hypervisor or WASM backend required. + +## Quick start + +### Context provider (recommended) + +Use `MontyCodeActProvider` to automatically inject the `execute_code` tool and +CodeAct instructions into every agent run. Tools registered on the provider are +available inside the Monty interpreter as **typed async functions** (e.g. +`await compute(operation="add", a=1, b=2)`), and as a fallback through +`call_tool(...)`. + +```python +from agent_framework import Agent, tool +from agent_framework_monty import MontyCodeActProvider + + +@tool +def compute(operation: str, a: float, b: float) -> float: + """Perform a math operation.""" + ops = {"add": a + b, "subtract": a - b, "multiply": a * b, "divide": a / b} + return ops[operation] + + +codeact = MontyCodeActProvider( + tools=[compute], + approval_mode="never_require", +) + +agent = Agent( + client=client, + name="CodeActAgent", + instructions="You are a helpful assistant.", + context_providers=[codeact], +) + +result = await agent.run("Multiply 6 by 7 using execute_code.") +``` + +### Standalone tool + +Use `MontyExecuteCodeTool` directly when you want full control over how the +tool is added to the agent (e.g. when mixing sandbox tools with direct-only +tools on the same agent). + +```python +from agent_framework import Agent, tool +from agent_framework_monty import MontyExecuteCodeTool + + +@tool +def send_email(to: str, subject: str, body: str) -> str: + """Send an email (direct-only, not available inside the sandbox).""" + return f"Email sent to {to}" + + +execute_code = MontyExecuteCodeTool( + tools=[compute], + approval_mode="never_require", +) + +agent = Agent( + client=client, + name="MixedToolsAgent", + instructions="You are a helpful assistant.", + tools=[send_email, execute_code], +) +``` + +### Manual static wiring + +For fixed configurations where provider lifecycle overhead is unnecessary, +build the CodeAct instructions once and pass them to the agent at construction +time: + +```python +execute_code = MontyExecuteCodeTool( + tools=[compute], + approval_mode="never_require", +) + +codeact_instructions = execute_code.build_instructions(tools_visible_to_model=False) + +agent = Agent( + client=client, + name="StaticWiringAgent", + instructions=f"You are a helpful assistant.\n\n{codeact_instructions}", + tools=[execute_code], +) +``` + +### File mounts and resource limits + +Mount host directories into the sandbox and cap execution resources: + +```python +from agent_framework_monty import FileMount, MontyCodeActProvider + +codeact = MontyCodeActProvider( + tools=[compute], + workspace_root="/host/workspace", # auto-mounted at /input (read-write) + file_mounts=[ + "/host/data", # shorthand: same path on both sides + ("/host/models", "/sandbox/models"), # explicit (host, mount_path) + FileMount( # full control + host_path="/host/cache", + mount_path="/sandbox/cache", + mode="overlay", # "read-only" | "read-write" | "overlay" + write_bytes_limit=10 * 1024 * 1024, + ), + ], + resource_limits={ # Monty ResourceLimits TypedDict + "max_duration_secs": 5.0, + "max_memory": 64 * 1024 * 1024, + }, +) +``` + +- **`workspace_root`** mirrors the Hyperlight default: the directory is mounted + at `/input` in `read-write` mode. +- **`file_mounts`** accepts a string shorthand, a `(host_path, mount_path)` + tuple, or a `FileMount` named tuple (with optional `mode` and + `write_bytes_limit`). +- Files written by the sandbox to any **`read-write`** mount are scanned + after each `execute_code` call and returned as `Content.from_data(...)` + attachments (with a `path` annotation in `additional_properties`), + mirroring Hyperlight's `/output` flow. +- `overlay` mounts buffer writes in memory (nothing leaks to the host and + nothing is captured). `read-only` mounts reject writes. +- **`resource_limits`** is forwarded straight to Monty's + [`ResourceLimits`](https://github.com/pydantic/monty) TypedDict + (`max_allocations`, `max_duration_secs`, `max_memory`, `gc_interval`, + `max_recursion_depth`). + +## DSL inside `execute_code` + +The model generates Python code that runs inside Monty's Rust-based interpreter. +Available primitives: + +| Primitive | Behavior | +|-----------|----------| +| `await tool_name(**kwargs)` | Direct typed call to a registered host tool. Argument types are checked before execution. | +| `await call_tool("name", **kwargs)` | Generic fallback that dispatches by tool name. Not type-checked. | +| `asyncio.gather(...)` | Fans out concurrent tool calls. | +| `print(...)` | Captured and surfaced as text in the tool result. | + +## Notes + +- `MontyCodeActProvider` and `MontyExecuteCodeTool` mirror the API surface of + the `agent-framework-hyperlight` counterparts where the underlying runtime + supports it. +- Monty interprets a **subset** of Python (a Rust-based interpreter). Most + control flow, common stdlib modules (`sys`, `os`, `typing`, `asyncio`, `re`, + `datetime`, `json`), and async functions are supported, but exotic features + may not be available. OS-level access (filesystem, network, subprocess) is + rejected with `PermissionError` **by default**; mount host directories with + `workspace_root` / `file_mounts` to grant scoped filesystem access. +- Code is type-checked against tool signatures via + [ty](https://docs.astral.sh/ty/) before execution, so wrong argument types + surface as a clear error before any host tool runs. +- The alpha package is **not** part of `agent-framework[all]` yet, so it must + be installed explicitly. Once promoted to beta it will be reachable via the + lazy-loading namespace `agent_framework.monty`. diff --git a/python/packages/monty/agent_framework_monty/__init__.py b/python/packages/monty/agent_framework_monty/__init__.py new file mode 100644 index 0000000000..cbeef88e49 --- /dev/null +++ b/python/packages/monty/agent_framework_monty/__init__.py @@ -0,0 +1,23 @@ +# Copyright (c) Microsoft. All rights reserved. + +from __future__ import annotations + +import importlib.metadata + +from ._execute_code_tool import MontyExecuteCodeTool +from ._provider import MontyCodeActProvider +from ._types import FileMount, FileMountInput, MountMode + +try: + __version__ = importlib.metadata.version(__name__) +except importlib.metadata.PackageNotFoundError: + __version__ = "0.0.0" + +__all__ = [ + "FileMount", + "FileMountInput", + "MontyCodeActProvider", + "MontyExecuteCodeTool", + "MountMode", + "__version__", +] diff --git a/python/packages/monty/agent_framework_monty/_execute_code_tool.py b/python/packages/monty/agent_framework_monty/_execute_code_tool.py new file mode 100644 index 0000000000..4d5e957e4a --- /dev/null +++ b/python/packages/monty/agent_framework_monty/_execute_code_tool.py @@ -0,0 +1,558 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""``MontyExecuteCodeTool`` - a ``FunctionTool`` that runs Python in Monty. + +Mirrors the public API of ``HyperlightExecuteCodeTool`` for the subset that +applies to a pure-Python interpreter (no backends to choose from). By default +the Monty sandbox rejects OS / filesystem / network calls with +``PermissionError``; pass ``workspace_root`` or ``file_mounts`` to expose +scoped host directories, and the tool will capture any files written under +``read-write`` mounts as ``Content`` items in the response. +""" + +from __future__ import annotations + +import json +import mimetypes +from collections.abc import Callable, Iterator, Sequence +from copy import copy +from functools import partial +from pathlib import Path, PurePosixPath +from typing import Any, cast + +from agent_framework import Content, FunctionTool +from agent_framework._tools import ApprovalMode, normalize_tools + +from ._instructions import build_codeact_instructions, build_execute_code_description +from ._monty_bridge import InlineCodeBridge, generate_type_stubs +from ._types import FileMount, FileMountInput + +EXECUTE_CODE_TOOL_NAME = "execute_code" +EXECUTE_CODE_TOOL_DESCRIPTION = "Execute Python in a Monty interpreter." + +#: Virtual path that the optional ``workspace_root`` directory is mounted at, +#: matching the Hyperlight default. Use ``file_mounts`` for any other path. +WORKSPACE_MOUNT_PATH = "/input" + +#: Maximum bytes per captured output file. Files larger than this are skipped +#: and a ``Content.from_text`` warning is appended in their place. +MAX_CAPTURED_FILE_BYTES = 5 * 1024 * 1024 # 5 MiB + +EXECUTE_CODE_INPUT_SCHEMA: dict[str, Any] = { + "type": "object", + "title": "_ExecuteCodeInput", + "properties": { + "code": { + "type": "string", + "title": "Code", + "description": "Python code to execute in a Monty interpreter.", + }, + }, + "required": ["code"], +} + + +def _collect_tools(*tool_groups: Any) -> list[FunctionTool]: + """Merge tool groups, dropping any ``execute_code`` entries and deduping by name.""" + tools_by_name: dict[str, FunctionTool] = {} + + for tool_group in tool_groups: + normalized_group = normalize_tools(tool_group) + for tool_obj in normalized_group: + if not isinstance(tool_obj, FunctionTool): + continue + if tool_obj.name == EXECUTE_CODE_TOOL_NAME: + continue + tools_by_name.pop(tool_obj.name, None) + tools_by_name[tool_obj.name] = tool_obj + + return list(tools_by_name.values()) + + +def _resolve_execute_code_approval_mode( + *, + base_approval_mode: ApprovalMode, + tools: Sequence[FunctionTool], +) -> ApprovalMode: + if base_approval_mode == "always_require": + return "always_require" + if any(tool_obj.approval_mode == "always_require" for tool_obj in tools): + return "always_require" + return "never_require" + + +def _normalize_mount_path(mount_path: str) -> str: + """Normalize a virtual mount path to a clean POSIX absolute path.""" + raw = mount_path.strip().replace("\\", "/") + if not raw: + raise ValueError("mount_path must not be empty.") + pure = PurePosixPath(raw) + parts = [part for part in pure.parts if part not in {"", "/", "."}] + if any(part == ".." for part in parts): + raise ValueError("mount_path must not contain '..' segments.") + if not parts: + raise ValueError("mount_path must point to a concrete absolute path.") + return "/" + "/".join(parts) + + +def _resolve_existing_directory(value: str | Path) -> Path: + resolved = Path(value).expanduser().resolve(strict=True) + if not resolved.is_dir(): + raise ValueError(f"Path {value!r} must point to an existing directory.") + return resolved + + +def _is_file_mount_pair(value: Any) -> bool: + if not isinstance(value, tuple) or isinstance(value, FileMount): + return False + items = cast("tuple[object, ...]", value) + if len(items) != 2: + return False + host_path, mount_path = items + return isinstance(host_path, (str, Path)) and isinstance(mount_path, str) + + +def _normalize_file_mount(file_mount: FileMountInput) -> FileMount: + if isinstance(file_mount, FileMount): + host_path = file_mount.host_path + mount_path = file_mount.mount_path + mode = file_mount.mode + write_limit = file_mount.write_bytes_limit + elif isinstance(file_mount, str): + host_path = file_mount + mount_path = file_mount + mode = "overlay" + write_limit = None + else: + host_path, mount_path = file_mount + mode = "overlay" + write_limit = None + + return FileMount( + host_path=_resolve_existing_directory(host_path), + mount_path=_normalize_mount_path(mount_path), + mode=mode, + write_bytes_limit=write_limit, + ) + + +def _to_monty_mount(file_mount: FileMount) -> Any: + """Convert a public :class:`FileMount` to Monty's ``MountDir``. + + Imports lazily through the bridge's loader so missing-dependency errors + surface as the same actionable ``RuntimeError`` the rest of the package + raises, rather than a bare ``ImportError`` from a top-level import. + """ + from ._monty_bridge import load_monty # avoid top-level pydantic_monty import + + monty_module = load_monty() + return monty_module.MountDir( + virtual_path=file_mount.mount_path, + host_path=str(file_mount.host_path), + mode=file_mount.mode, + write_bytes_limit=file_mount.write_bytes_limit, + ) + + +def _make_tool_callback(tool_obj: FunctionTool) -> Callable[..., Any]: + """Return an async callable that invokes ``tool_obj`` with the bridge's kwargs. + + Returns the raw native value (no ``Content`` wrapping) so the Monty interpreter + receives real Python objects. ``FunctionTool.invoke`` accepts direct keyword + arguments and handles both sync and async underlying functions internally. + """ + return partial(copy(tool_obj).invoke, skip_parsing=True) + + +class MontyExecuteCodeTool(FunctionTool): + """Execute Python code inside a Monty interpreter. + + Tools registered on this object are available inside the interpreter as + typed async functions (e.g. ``await tool_name(...)``). Argument types are + validated by the [ty](https://docs.astral.sh/ty/) type checker before any + host tool runs. + + Optional filesystem access is exposed via: + + - ``workspace_root`` — auto-mounts a host directory at ``/input`` (matching + Hyperlight's default). + - ``file_mounts`` — extra :class:`FileMount` entries for fine-grained + control (mount path, read-only / read-write / overlay mode, write + byte caps). + + Files written by sandboxed code to any **read-write** mount are scanned + after execution and returned as ``Content.from_data`` items, mirroring + Hyperlight's ``/output`` flow. + + ``resource_limits`` is forwarded to Monty's ``ResourceLimits`` to cap CPU + time, memory, output size, recursion depth, and GC frequency. + + All mutators (``add_tools``, ``add_file_mounts`` etc.) must be called from + the same task/thread that owns the tool. Monty itself runs on the event + loop, so no internal locking is needed. + """ + + def __init__( + self, + *, + tools: FunctionTool | Callable[..., Any] | Sequence[FunctionTool | Callable[..., Any]] | None = None, + approval_mode: ApprovalMode | None = None, + workspace_root: str | Path | None = None, + file_mounts: FileMountInput | Sequence[FileMountInput] | None = None, + resource_limits: dict[str, Any] | None = None, + ) -> None: + super().__init__( + name=EXECUTE_CODE_TOOL_NAME, + description=EXECUTE_CODE_TOOL_DESCRIPTION, + approval_mode="never_require", + func=self._run_code, + input_model=EXECUTE_CODE_INPUT_SCHEMA, + ) + self._default_approval_mode: ApprovalMode = approval_mode or "never_require" + self._managed_tools: list[FunctionTool] = [] + self._workspace_root: Path | None = ( + _resolve_existing_directory(workspace_root) if workspace_root is not None else None + ) + self._file_mounts: dict[str, FileMount] = {} + self._resource_limits: dict[str, Any] | None = dict(resource_limits) if resource_limits else None + + if tools is not None: + self.add_tools(tools) + if file_mounts is not None: + self.add_file_mounts(file_mounts) + + self._refresh_approval_mode() + + @property + def description(self) -> str: + # During FunctionTool.__init__, ``_managed_tools`` is not yet set. + if not hasattr(self, "_managed_tools"): + return str(self.__dict__.get("description", EXECUTE_CODE_TOOL_DESCRIPTION)) + return build_execute_code_description( + tools=self._managed_tools, + mounts=self._effective_mounts(), + ) + + @description.setter + def description(self, value: str) -> None: + self.__dict__["description"] = value + + def add_tools( + self, + tools: FunctionTool | Callable[..., Any] | Sequence[FunctionTool | Callable[..., Any]], + ) -> None: + """Add Monty-side tools to this execute_code surface.""" + self._managed_tools = _collect_tools(self._managed_tools, tools) + self._refresh_approval_mode() + + def get_tools(self) -> list[FunctionTool]: + """Return the currently managed Monty tools.""" + return list(self._managed_tools) + + def remove_tool(self, name: str) -> None: + """Remove one managed Monty tool by name.""" + remaining_tools = [tool_obj for tool_obj in self._managed_tools if tool_obj.name != name] + if len(remaining_tools) == len(self._managed_tools): + raise KeyError(f"No managed tool named {name!r} is registered.") + self._managed_tools = remaining_tools + self._refresh_approval_mode() + + def clear_tools(self) -> None: + """Remove all managed Monty tools.""" + self._managed_tools = [] + self._refresh_approval_mode() + + def add_file_mounts(self, file_mounts: FileMountInput | Sequence[FileMountInput]) -> None: + """Add one or more file mounts. + + A single string mounts the same path on both sides. Use a + ``(host_path, mount_path)`` tuple or :class:`FileMount` when the paths + differ or when you need to set the mount mode / write limit. + """ + if isinstance(file_mounts, (str, FileMount)) or _is_file_mount_pair(file_mounts): + normalized = [_normalize_file_mount(cast("FileMountInput", file_mounts))] + else: + normalized = [_normalize_file_mount(item) for item in cast("Sequence[FileMountInput]", file_mounts)] + + for mount in normalized: + self._file_mounts[mount.mount_path] = mount + + def get_file_mounts(self) -> list[FileMount]: + """Return the configured file mounts (excluding ``workspace_root``).""" + return list(self._file_mounts.values()) + + def remove_file_mount(self, mount_path: str) -> None: + """Remove one file mount by its sandbox path.""" + normalized = _normalize_mount_path(mount_path) + if normalized not in self._file_mounts: + raise KeyError(f"No file mount exists for {mount_path!r}.") + del self._file_mounts[normalized] + + def clear_file_mounts(self) -> None: + """Remove all configured file mounts.""" + self._file_mounts.clear() + + @property + def workspace_root(self) -> Path | None: + """Return the configured workspace root, if any.""" + return self._workspace_root + + @property + def resource_limits(self) -> dict[str, Any] | None: + """Return the configured Monty :class:`pydantic_monty.ResourceLimits`, if any.""" + return dict(self._resource_limits) if self._resource_limits else None + + def build_instructions(self, *, tools_visible_to_model: bool) -> str: + """Build the current CodeAct instructions for this execute_code surface.""" + return build_codeact_instructions( + tools=list(self._managed_tools), + tools_visible_to_model=tools_visible_to_model, + mounts=self._effective_mounts(), + ) + + def create_run_tool(self) -> MontyExecuteCodeTool: + """Create a run-scoped snapshot of this execute_code surface.""" + return MontyExecuteCodeTool( + tools=self.get_tools(), + approval_mode=self._default_approval_mode, + workspace_root=self._workspace_root, + file_mounts=list(self._file_mounts.values()) or None, + resource_limits=self._resource_limits, + ) + + def build_serializable_state(self) -> dict[str, Any]: + """Return a JSON-serializable snapshot of the effective run state.""" + approval_mode = _resolve_execute_code_approval_mode( + base_approval_mode=self._default_approval_mode, + tools=self._managed_tools, + ) + mounts = self._effective_mounts() + return { + "runtime": "monty", + "approval_mode": approval_mode, + "tool_names": [tool_obj.name for tool_obj in self._managed_tools], + "workspace_root": str(self._workspace_root) if self._workspace_root is not None else None, + "file_mounts": [ + { + "host_path": str(mount.host_path), + "mount_path": mount.mount_path, + "mode": mount.mode, + "write_bytes_limit": mount.write_bytes_limit, + } + for mount in mounts + ], + "resource_limits": dict(self._resource_limits) if self._resource_limits else None, + } + + def to_dict(self, *, exclude: set[str] | None = None, exclude_none: bool = True) -> dict[str, Any]: + # Materialize the dynamic description so the dump captures the current tool list. + self.__dict__["description"] = self.description + return super().to_dict(exclude=exclude, exclude_none=exclude_none) + + def _refresh_approval_mode(self) -> None: + self.approval_mode = _resolve_execute_code_approval_mode( + base_approval_mode=self._default_approval_mode, + tools=self._managed_tools, + ) + + def _build_tool_map(self, tools: Sequence[FunctionTool]) -> dict[str, Callable[..., Any]]: + return {tool_obj.name: _make_tool_callback(tool_obj) for tool_obj in tools} + + def _build_type_stub_map(self, tools: Sequence[FunctionTool]) -> dict[str, Callable[..., Any]]: + """Return a name -> underlying-Python-callable map for type stub generation. + + The raw Python function attached to the ``FunctionTool`` carries the + author's actual ``Annotated`` parameter types, which are what we want + ``ty`` to validate against. Tools without an attached function (e.g. + ``declaration_only`` tools) are skipped. + """ + stub_map: dict[str, Callable[..., Any]] = {} + for tool_obj in tools: + func = getattr(tool_obj, "func", None) + if callable(func): + stub_map[tool_obj.name] = func + return stub_map + + def _effective_mounts(self) -> list[FileMount]: + """Combine ``workspace_root`` (if set) with the explicit ``file_mounts``.""" + mounts: list[FileMount] = [] + if self._workspace_root is not None and WORKSPACE_MOUNT_PATH not in self._file_mounts: + mounts.append( + FileMount( + host_path=self._workspace_root, + mount_path=WORKSPACE_MOUNT_PATH, + mode="read-write", + write_bytes_limit=None, + ) + ) + mounts.extend(self._file_mounts.values()) + return mounts + + async def _run_code(self, *, code: str) -> list[Content]: + tools = list(self._managed_tools) + mounts = self._effective_mounts() + + tool_map = self._build_tool_map(tools) + stub_map = self._build_type_stub_map(tools) + type_stubs = generate_type_stubs(stub_map) if stub_map else None + + # Snapshot mtimes of host files in read-write mounts so we can later + # identify which files the sandbox actually touched. + pre_state = _snapshot_writable_mounts(mounts) + + bridge = InlineCodeBridge( + tool_map, + type_stubs=type_stubs, + mounts=[_to_monty_mount(mount) for mount in mounts] or None, + resource_limits=self._resource_limits, + ) + + try: + result = await bridge.run(code) + except Exception as exc: + return [ + Content.from_error( + message="Execution error", + error_details=f"{type(exc).__name__}: {exc}", + ), + ] + + contents = _build_execution_contents(result=result) + contents.extend(_capture_written_files(mounts, pre_state)) + return contents + + +def _build_execution_contents(*, result: dict[str, Any]) -> list[Content]: + stdout = str(result.get("stdout") or "").replace("\r\n", "\n") + output_value = result.get("output") + truncated = bool(result.get("truncated")) + + outputs: list[Content] = [] + if stdout: + text = stdout + if truncated: + text = f"{text}\n\n[stdout truncated]" + outputs.append(Content.from_text(text)) + elif truncated: + outputs.append(Content.from_text("[stdout truncated]")) + + if output_value is not None: + try: + serialized_output = json.dumps(output_value, ensure_ascii=False) + except (TypeError, ValueError): + serialized_output = repr(output_value) + outputs.append(Content.from_text(serialized_output)) + + if not outputs: + outputs.append(Content.from_text("Code executed successfully without output.")) + + return outputs + + +def _iter_real_files(root: Path) -> Iterator[Path]: + """Walk ``root`` recursively, yielding only real (non-symlink) files. + + ``Path.rglob`` follows directory symlinks by default, which combined with + ``Path.is_file()`` / ``Path.read_bytes()`` (both follow symlinks) would let + an attacker who controls the workspace pre-place a symlink to a host file + or directory and have our post-execution capture surface it. Skipping every + symlink at both the directory and file level closes that escape. + """ + stack: list[Path] = [root] + while stack: + current = stack.pop() + try: + entries = list(current.iterdir()) + except OSError: + continue + for entry in entries: + try: + if entry.is_symlink(): + continue + if entry.is_dir(): + stack.append(entry) + elif entry.is_file(): + yield entry + except OSError: + continue + + +def _snapshot_writable_mounts(mounts: Sequence[FileMount]) -> dict[str, dict[str, tuple[int, int]]]: + """Capture (size, mtime_ns) for every real (non-symlink) host file under read-write mounts. + + Returns ``{mount_path: {relative_posix_path: (size, mtime_ns)}}``. Used by + :func:`_capture_written_files` to detect new or modified files after the run. + Read-only and overlay mounts are skipped because their writes do not + propagate to the host. Symlinks (file or directory) are deliberately skipped + so an attacker cannot escape the mount by pre-placing a symlink to a host + path outside the workspace. + """ + snapshot: dict[str, dict[str, tuple[int, int]]] = {} + for mount in mounts: + if mount.mode != "read-write": + continue + host_root = Path(mount.host_path) + per_mount: dict[str, tuple[int, int]] = {} + for entry in _iter_real_files(host_root): + try: + stat = entry.lstat() # lstat: never follow symlinks (defensive) + except OSError: + continue + relative = entry.relative_to(host_root).as_posix() + per_mount[relative] = (int(stat.st_size), int(stat.st_mtime_ns)) + snapshot[mount.mount_path] = per_mount + return snapshot + + +def _capture_written_files( + mounts: Sequence[FileMount], + pre_state: dict[str, dict[str, tuple[int, int]]], +) -> list[Content]: + """Return :class:`Content` items for files the sandbox wrote during the run. + + Mirrors Hyperlight's ``/output`` capture flow: any new or modified real + (non-symlink) file under a read-write mount is read back as binary and + surfaced as ``Content.from_data`` with a ``path`` annotation in + ``additional_properties``. Symlinks are skipped at both directory and file + level so a malicious workspace cannot trick us into capturing host files + outside the configured mount root. + """ + captured: list[Content] = [] + for mount in mounts: + if mount.mode != "read-write": + continue + host_root = Path(mount.host_path) + before = pre_state.get(mount.mount_path, {}) + for entry in sorted(_iter_real_files(host_root)): + try: + stat = entry.lstat() + except OSError: + continue + relative = entry.relative_to(host_root).as_posix() + current = (int(stat.st_size), int(stat.st_mtime_ns)) + if before.get(relative) == current: + continue # Unchanged. + sandbox_path = f"{mount.mount_path.rstrip('/')}/{relative}" + if stat.st_size > MAX_CAPTURED_FILE_BYTES: + captured.append( + Content.from_text( + f"[file {sandbox_path} omitted: {stat.st_size} bytes " + f"exceeds MAX_CAPTURED_FILE_BYTES={MAX_CAPTURED_FILE_BYTES}]" + ) + ) + continue + try: + # _iter_real_files already excluded symlinks at every level of + # the walk; reading the file here is safe. + data = entry.read_bytes() + except OSError: + continue + media_type = mimetypes.guess_type(entry.name)[0] or "application/octet-stream" + captured.append( + Content.from_data( + data=data, + media_type=media_type, + additional_properties={"path": sandbox_path}, + ) + ) + return captured diff --git a/python/packages/monty/agent_framework_monty/_instructions.py b/python/packages/monty/agent_framework_monty/_instructions.py new file mode 100644 index 0000000000..c560e356d3 --- /dev/null +++ b/python/packages/monty/agent_framework_monty/_instructions.py @@ -0,0 +1,125 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Dynamic CodeAct instructions and execute_code tool descriptions for Monty.""" + +from __future__ import annotations + +from collections.abc import Sequence + +from agent_framework import FunctionTool + +from ._types import FileMount + + +def _format_tool_summaries(tools: Sequence[FunctionTool]) -> str: + if not tools: + return "- No tools are currently registered." + + lines: list[str] = [] + for tool_obj in tools: + parameters = tool_obj.parameters().get("properties", {}) + parameter_names = [name for name in parameters if isinstance(name, str)] + parameter_summary = ", ".join(parameter_names) if parameter_names else "none" + description = str(tool_obj.description or "").strip() or "No description provided." + lines.append(f"- `{tool_obj.name}`: {description} Parameters: {parameter_summary}.") + return "\n".join(lines) + + +def _format_filesystem_capabilities(mounts: Sequence[FileMount]) -> str: + if not mounts: + return ( + "Filesystem access is unavailable. OS-level paths raise `PermissionError`. " + "If you need files, ask the agent operator to configure `workspace_root` or `file_mounts`." + ) + + lines = ["Filesystem access is enabled. Read and write paths via `pathlib.Path(...)` (or `os.path`)."] + lines.append("Configured mounts:") + for mount in mounts: + cap = "" + if mount.write_bytes_limit is not None: + cap = f", write cap {mount.write_bytes_limit} bytes" + lines.append(f"- `{mount.mount_path}` ({mount.mode}{cap})") + + writable = [mount for mount in mounts if mount.mode == "read-write"] + if writable: + writable_paths = ", ".join(f"`{m.mount_path}`" for m in writable) + lines.append( + f"Files written to {writable_paths} are returned to the caller as attached files; " + "use these paths for any output artifacts." + ) + + return "\n".join(lines) + + +def build_codeact_instructions( + *, + tools: Sequence[FunctionTool], + tools_visible_to_model: bool, + mounts: Sequence[FileMount] = (), +) -> str: + """Build dynamic CodeAct instructions for the effective Monty tool set.""" + tool_summaries = _format_tool_summaries(tools) + filesystem_text = _format_filesystem_capabilities(mounts) + + usage_note = ( + "Some tools may also appear directly, but prefer `execute_code` whenever you need to combine " + "Python control flow with sandbox tool calls." + if tools_visible_to_model + else "Provider-owned sandbox tools are not exposed separately; use `execute_code` when you need them." + ) + + return f"""You have one primary tool: `execute_code`. + +Inside `execute_code`, call registered tools directly as async functions: +`result = await tool_name(param=value)`. Always use `await` and keyword arguments. +Your code is type-checked against the tool signatures below before execution. +`await call_tool('name', **kwargs)` is also supported as a fallback but is not type-checked. + +For fan-out, use `asyncio.gather`: +`results = await asyncio.gather(tool_a(...), tool_b(...))`. + +Surface results to the caller via `print(...)` (captured and returned as text) +or by ending the code with an expression whose value is JSON-encodable - the +value of the final expression is returned alongside captured stdout. + +Filesystem capabilities: +{filesystem_text} + +Registered tools: +{tool_summaries} + +Prefer a single `execute_code` call per request when possible, combining +multiple tool calls with Python control flow. + +{usage_note} +""" + + +def build_execute_code_description( + *, + tools: Sequence[FunctionTool], + mounts: Sequence[FileMount] = (), +) -> str: + """Build the dynamic ``execute_code`` tool description for standalone usage.""" + tool_summaries = _format_tool_summaries(tools) + filesystem_text = _format_filesystem_capabilities(mounts) + + return f"""Execute Python code in a Monty interpreter. + +Inside the sandbox, call registered tools directly as typed async functions: +`result = await tool_name(param=value)`. Always use `await` and keyword arguments. +Code is type-checked against tool signatures before execution. +`await call_tool('name', **kwargs)` is also supported as a fallback. + +For fan-out, use `asyncio.gather`: +`results = await asyncio.gather(tool_a(...), tool_b(...))`. + +Filesystem capabilities: +{filesystem_text} + +Registered tools: +{tool_summaries} + +Surface results via `print(...)` (captured and returned as text) or by ending +with an expression whose value is JSON-encodable. +""" diff --git a/python/packages/monty/agent_framework_monty/_monty_bridge.py b/python/packages/monty/agent_framework_monty/_monty_bridge.py new file mode 100644 index 0000000000..1d9cd46c40 --- /dev/null +++ b/python/packages/monty/agent_framework_monty/_monty_bridge.py @@ -0,0 +1,327 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Inline (non-durable) Monty execution bridge and type-stub generation. + +Adapted from https://github.com/anthonychu/maf-codeact-monty-python. +""" + +from __future__ import annotations + +import asyncio +import inspect +import keyword +import types +import typing +from collections.abc import Callable, Sequence +from typing import Annotated, Any, cast, get_type_hints + +MAX_PRINT_OUTPUT_CHARS = 8192 + +# Prelude injected into all Monty code so `asyncio.gather` works for fan-out. +_CODEACT_PRELUDE = """\ +import asyncio +""" + + +def _ensure_json_value(value: Any) -> Any: + if value is None or isinstance(value, (str, bool, int)): + return value + if isinstance(value, float): + if value != value or value in (float("inf"), float("-inf")): + raise ValueError("Non-finite floating point values are not JSON-safe.") + return value + if isinstance(value, (list, tuple)): + items = cast("list[object] | tuple[object, ...]", value) + return [_ensure_json_value(item) for item in items] + if isinstance(value, dict): + as_dict = cast("dict[object, object]", value) + return {str(k): _ensure_json_value(v) for k, v in as_dict.items()} + raise ValueError(f"Value of type {type(value).__name__} is not JSON-safe.") + + +def _external_error(exc: Exception) -> dict[str, str]: + return {"exc_type": type(exc).__name__, "message": str(exc)} + + +def _parse_call_tool(args: tuple[Any, ...], kwargs: dict[str, Any]) -> tuple[str, dict[str, Any]]: + if not args: + raise ValueError("call_tool requires a tool name as the first argument.") + name = args[0] + if not isinstance(name, str) or not name: + raise ValueError("Tool name must be a non-empty string.") + if len(args) > 1: + raise ValueError( + "call_tool accepts only the tool name as a positional argument. Use keyword arguments for parameters." + ) + return name, dict(kwargs) + + +def _build_code(code: str) -> str: + return f"{_CODEACT_PRELUDE}\n{code}" + + +def _python_type_repr(annotation: Any) -> str: + """Convert a Python type annotation to its string representation for stubs.""" + if annotation is inspect.Parameter.empty: + return "Any" + if annotation is type(None): + # ``None`` in annotations represents ``NoneType``; emit it literally so + # ``ty`` can validate ``Optional[X]`` / ``Union[..., None]`` / ``-> None`` + # signatures correctly. + return "None" + origin = typing.get_origin(annotation) + if origin is Annotated: + args = typing.get_args(annotation) + return _python_type_repr(args[0]) if args else "Any" + if origin is not None: + args = typing.get_args(annotation) + # Normalize ``typing.Union[...]`` and PEP-604 ``X | Y`` to PEP-604 syntax so + # ``None`` is preserved across both forms. + if origin is typing.Union or origin is types.UnionType: + return " | ".join(_python_type_repr(a) for a in args) if args else "Any" + origin_name = getattr(origin, "__name__", None) + if origin_name is None: + origin_name = str(origin) + if origin_name.startswith(" str: + """Generate Python type stub declarations for tools + DSL primitives. + + Stubs are fed to Monty's ``type_check_stubs`` so ``ty`` can validate the + LLM-generated code against the actual tool signatures before any host + call runs. + + Tools whose ``name`` is not a valid Python identifier are skipped because + their name cannot be safely splatted into stub source. The model can still + reach them via the ``call_tool("weird name", ...)`` fallback at runtime, + but they will not get type-checked stubs. + """ + lines: list[str] = [ + "from typing import Any", + "", + "# DSL primitives", + "async def call_tool(name: str, **kwargs: Any) -> Any:", + " raise NotImplementedError()", + "", + "# Registered tools - call directly with typed arguments", + ] + + for name, func in sorted(tool_callables.items()): + if not name.isidentifier() or keyword.iskeyword(name): + # A non-identifier name (or a Python keyword) would inject invalid + # / dangerous syntax into the stub source. Skip stub generation; + # the tool stays reachable through ``call_tool(name, ...)``. + continue + try: + sig = inspect.signature(func) + hints = get_type_hints(func, include_extras=True) + except (ValueError, TypeError): + lines.append(f"async def {name}(**kwargs: Any) -> Any:") + lines.append(" raise NotImplementedError()") + lines.append("") + continue + + params: list[str] = [] + for param_name, param in sig.parameters.items(): + annotation = hints.get(param_name, inspect.Parameter.empty) + type_str = _python_type_repr(annotation) + if param.default is not inspect.Parameter.empty: + params.append(f"{param_name}: {type_str} = ...") + else: + params.append(f"{param_name}: {type_str}") + + return_annotation = hints.get("return", inspect.Parameter.empty) + return_str = _python_type_repr(return_annotation) + param_str = ", ".join(params) + lines.append(f"async def {name}({param_str}) -> {return_str}:") + lines.append(" raise NotImplementedError()") + lines.append("") + + return "\n".join(lines) + + +class _PrintCollector: + """Collect Monty stdout, capped at ``MAX_PRINT_OUTPUT_CHARS``.""" + + def __init__(self) -> None: + self.chunks: list[str] = [] + self.truncated: bool = False + self._size: int = 0 # running character count to avoid O(n) per append + + def __call__(self, stream: str, text: str) -> None: + if self.truncated: + return + remaining = MAX_PRINT_OUTPUT_CHARS - self._size + if remaining <= 0: + self.truncated = True + return + text_value = str(text) + if len(text_value) > remaining: + clipped = text_value[:remaining] + self.chunks.append(clipped) + self._size += len(clipped) + self.truncated = True + else: + self.chunks.append(text_value) + self._size += len(text_value) + + @property + def output(self) -> str: + return "".join(self.chunks) + + +def load_monty() -> Any: + """Import ``pydantic_monty`` lazily so unit tests can run without it. + + Returns the module so callers can read ``Monty``, ``MontyComplete``, + ``FunctionSnapshot``, ``FutureSnapshot``, ``NameLookupSnapshot`` from it. + """ + try: + import pydantic_monty # type: ignore[import-not-found] + except ImportError as exc: + raise RuntimeError( + "The `pydantic-monty` package is required to execute Monty CodeAct code. " + "Install it with `pip install pydantic-monty`." + ) from exc + return pydantic_monty + + +class InlineCodeBridge: + """Execute Monty code inline (non-durable). + + Supports both ``await call_tool('name', ...)`` and direct ``await name(...)`` + calls. When Monty yields a :class:`FutureSnapshot`, the bridge invokes the + registered host tools and resumes execution with the results. + """ + + def __init__( + self, + tool_map: dict[str, Callable[..., Any]], + *, + type_stubs: str | None = None, + mounts: Sequence[Any] | None = None, + resource_limits: dict[str, Any] | None = None, + ) -> None: + self.tool_map: dict[str, Callable[..., Any]] = dict(tool_map) + self.type_stubs: str | None = type_stubs + self._mounts = tuple(mounts) if mounts else () + self._resource_limits = resource_limits + self._pending_calls: dict[int, tuple[str, dict[str, Any]]] = {} + + async def run(self, code: str) -> dict[str, Any]: + if not isinstance(code, str) or not code.strip(): + raise ValueError("Code must be a non-empty string.") + + monty_module = load_monty() + Monty = monty_module.Monty + MontyComplete = monty_module.MontyComplete + FunctionSnapshot = monty_module.FunctionSnapshot + FutureSnapshot = monty_module.FutureSnapshot + NameLookupSnapshot = monty_module.NameLookupSnapshot + + printer = _PrintCollector() + monty = Monty( + _build_code(code), + script_name="codeact.py", + type_check=self.type_stubs is not None, + type_check_stubs=self.type_stubs, + ) + start_kwargs: dict[str, Any] = {"print_callback": printer} + if self._mounts: + start_kwargs["mount"] = list(self._mounts) + if self._resource_limits: + start_kwargs["limits"] = self._resource_limits + progress = monty.start(**start_kwargs) + + while True: + if isinstance(progress, MontyComplete): + return { + "output": _ensure_json_value(progress.output), + "stdout": printer.output, + "truncated": printer.truncated, + } + if isinstance(progress, FunctionSnapshot): + progress = self._handle_function(progress) + continue + if isinstance(progress, FutureSnapshot): + progress = await self._handle_future(progress) + continue + if isinstance(progress, NameLookupSnapshot): + raise RuntimeError(f"Name lookup not supported: {progress.variable_name!r}") + raise RuntimeError(f"Unsupported Monty progress type: {type(progress).__name__}") + + def _handle_function(self, snapshot: Any) -> Any: + if snapshot.is_os_function: + return snapshot.resume({ + "exc_type": "PermissionError", + "message": "OS and filesystem calls are not available.", + }) + + function_name = str(snapshot.function_name) + + if function_name in self.tool_map: + return self._schedule_direct_tool(snapshot, function_name) + if function_name == "call_tool": + return self._schedule_call_tool(snapshot) + + return snapshot.resume({ + "exc_type": "NameError", + "message": f"Function {function_name!r} is not available.", + }) + + def _schedule_direct_tool(self, snapshot: Any, name: str) -> Any: + # Positional args are rejected up-front by ``ty`` because the generated + # stubs declare every parameter as keyword-typed. Anything that slips + # through (e.g. tools with no signature inspection) is forwarded to the + # host tool as-is via kwargs only. + self._pending_calls[int(snapshot.call_id)] = (name, dict(snapshot.kwargs)) + return snapshot.resume({"future": ...}) + + def _schedule_call_tool(self, snapshot: Any) -> Any: + try: + name, kwargs = _parse_call_tool(snapshot.args, snapshot.kwargs) + if name not in self.tool_map: + allowed = ", ".join(sorted(self.tool_map.keys())) or "" + raise ValueError(f"Tool {name!r} is not registered. Available tools: {allowed}") + self._pending_calls[int(snapshot.call_id)] = (name, kwargs) + except Exception as exc: + return snapshot.resume(_external_error(exc)) + return snapshot.resume({"future": ...}) + + async def _handle_future(self, snapshot: Any) -> Any: + pending_call_ids = [int(cid) for cid in snapshot.pending_call_ids] + if not pending_call_ids: + return snapshot.resume({}) + + entries: list[tuple[int, tuple[str, dict[str, Any]]]] = [] + for cid in pending_call_ids: + if cid not in self._pending_calls: + raise RuntimeError(f"Unknown future call ID: {cid}") + entries.append((cid, self._pending_calls.pop(cid))) + + tasks = [self._invoke_tool(cid, name, kwargs) for cid, (name, kwargs) in entries] + results = await asyncio.gather(*tasks) + resume_results: dict[int, Any] = dict(results) + return snapshot.resume(resume_results) + + async def _invoke_tool(self, cid: int, name: str, kwargs: dict[str, Any]) -> tuple[int, Any]: + # Every entry in ``self.tool_map`` is produced by ``_make_tool_callback`` + # as ``partial(FunctionTool.invoke, skip_parsing=True)``. ``FunctionTool.invoke`` + # is always ``async def``, so a plain ``await`` is correct for every call and + # avoids relying on ``inspect.iscoroutinefunction(partial(...))``, which can + # return ``False`` for some ``partial`` shapes (cpython#98590) and would route + # the call through ``asyncio.to_thread`` with an unawaited coroutine return. + try: + result = await self.tool_map[name](**kwargs) + return cid, {"return_value": _ensure_json_value(result)} + except Exception as exc: + return cid, _external_error(exc) diff --git a/python/packages/monty/agent_framework_monty/_provider.py b/python/packages/monty/agent_framework_monty/_provider.py new file mode 100644 index 0000000000..abec2a33fa --- /dev/null +++ b/python/packages/monty/agent_framework_monty/_provider.py @@ -0,0 +1,95 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""``MontyCodeActProvider`` - context provider injecting Monty-backed CodeAct.""" + +from __future__ import annotations + +from collections.abc import Callable, Sequence +from pathlib import Path +from typing import Any + +from agent_framework import AgentSession, ContextProvider, FunctionTool, SessionContext +from agent_framework._tools import ApprovalMode + +from ._execute_code_tool import MontyExecuteCodeTool +from ._types import FileMount, FileMountInput + + +class MontyCodeActProvider(ContextProvider): + """Inject a Monty-backed CodeAct surface using provider-owned tools. + + Mirrors :class:`agent_framework_hyperlight.HyperlightCodeActProvider` for + the subset of capabilities that apply to the Monty interpreter: + ``tools``, ``approval_mode``, ``workspace_root``, ``file_mounts``, and + ``resource_limits`` (Monty-only). + """ + + DEFAULT_SOURCE_ID = "monty_codeact" + + def __init__( + self, + source_id: str = DEFAULT_SOURCE_ID, + *, + tools: FunctionTool | Callable[..., Any] | Sequence[FunctionTool | Callable[..., Any]] | None = None, + approval_mode: ApprovalMode | None = None, + workspace_root: str | Path | None = None, + file_mounts: FileMountInput | Sequence[FileMountInput] | None = None, + resource_limits: dict[str, Any] | None = None, + ) -> None: + super().__init__(source_id) + self._execute_code_tool = MontyExecuteCodeTool( + tools=tools, + approval_mode=approval_mode, + workspace_root=workspace_root, + file_mounts=file_mounts, + resource_limits=resource_limits, + ) + + def add_tools( + self, + tools: FunctionTool | Callable[..., Any] | Sequence[FunctionTool | Callable[..., Any]], + ) -> None: + """Add provider-owned Monty tools.""" + self._execute_code_tool.add_tools(tools) + + def get_tools(self) -> list[FunctionTool]: + """Return the provider-owned Monty tools.""" + return self._execute_code_tool.get_tools() + + def remove_tool(self, name: str) -> None: + """Remove one provider-owned Monty tool by name.""" + self._execute_code_tool.remove_tool(name) + + def clear_tools(self) -> None: + """Remove all provider-owned Monty tools.""" + self._execute_code_tool.clear_tools() + + def add_file_mounts(self, file_mounts: FileMountInput | Sequence[FileMountInput]) -> None: + """Add provider-managed file mounts.""" + self._execute_code_tool.add_file_mounts(file_mounts) + + def get_file_mounts(self) -> list[FileMount]: + """Return the provider-managed file mounts (excluding ``workspace_root``).""" + return self._execute_code_tool.get_file_mounts() + + def remove_file_mount(self, mount_path: str) -> None: + """Remove one provider-managed file mount by its sandbox path.""" + self._execute_code_tool.remove_file_mount(mount_path) + + def clear_file_mounts(self) -> None: + """Remove all provider-managed file mounts.""" + self._execute_code_tool.clear_file_mounts() + + async def before_run( + self, + *, + agent: Any, + session: AgentSession | None, + context: SessionContext, + state: dict[str, Any], + ) -> None: + """Inject CodeAct instructions and a run-scoped execute_code tool before each run.""" + run_tool = self._execute_code_tool.create_run_tool() + state[self.source_id] = run_tool.build_serializable_state() + context.extend_instructions(self.source_id, run_tool.build_instructions(tools_visible_to_model=False)) + context.extend_tools(self.source_id, [run_tool]) diff --git a/python/packages/monty/agent_framework_monty/_types.py b/python/packages/monty/agent_framework_monty/_types.py new file mode 100644 index 0000000000..2072c39f4e --- /dev/null +++ b/python/packages/monty/agent_framework_monty/_types.py @@ -0,0 +1,38 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Public types for ``agent-framework-monty``. + +Mirrors ``agent_framework_hyperlight._types`` where the Monty runtime exposes +an equivalent concept so users can move between the two providers with minimal +churn. +""" + +from __future__ import annotations + +from pathlib import Path +from typing import Literal, NamedTuple, TypeAlias + +#: Allowed Monty mount modes. ``overlay`` (the Monty default) buffers writes +#: in-memory and is therefore not visible to the host after execution. +#: ``read-only`` rejects writes. ``read-write`` writes through to the host +#: directory. +MountMode: TypeAlias = Literal["overlay", "read-only", "read-write"] + + +class FileMount(NamedTuple): + """Map a host directory into the Monty sandbox. + + Mirrors :class:`agent_framework_hyperlight.FileMount` with two extra + fields that surface Monty's underlying ``MountDir`` capabilities: + ``mode`` selects read-only / read-write / overlay semantics, and + ``write_bytes_limit`` caps the total bytes written through this mount. + """ + + host_path: str | Path + mount_path: str + mode: MountMode = "overlay" + write_bytes_limit: int | None = None + + +FileMountHostPath: TypeAlias = str | Path +FileMountInput: TypeAlias = str | tuple[FileMountHostPath, str] | FileMount diff --git a/python/packages/monty/agent_framework_monty/py.typed b/python/packages/monty/agent_framework_monty/py.typed new file mode 100644 index 0000000000..e69de29bb2 diff --git a/python/packages/monty/pyproject.toml b/python/packages/monty/pyproject.toml new file mode 100644 index 0000000000..802836913e --- /dev/null +++ b/python/packages/monty/pyproject.toml @@ -0,0 +1,107 @@ +[project] +name = "agent-framework-monty" +description = "Monty CodeAct integrations for Microsoft Agent Framework." +authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}] +readme = "README.md" +requires-python = ">=3.10" +version = "1.0.0a260518" +license-files = ["LICENSE"] +urls.homepage = "https://aka.ms/agent-framework" +urls.source = "https://github.com/microsoft/agent-framework/tree/main/python" +urls.release_notes = "https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true" +urls.issues = "https://github.com/microsoft/agent-framework/issues" +classifiers = [ + "License :: OSI Approved :: MIT License", + "Development Status :: 3 - Alpha", + "Intended Audience :: Developers", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", + "Typing :: Typed", +] +dependencies = [ + "agent-framework-core>=1.4.0,<2", + "pydantic-monty>=0,<0.1", +] + +[tool.uv] +prerelease = "if-necessary-or-explicit" +environments = [ + "sys_platform == 'darwin'", + "sys_platform == 'linux'", + "sys_platform == 'win32'" +] + +[tool.uv-dynamic-versioning] +fallback-version = "0.0.0" + +[tool.pytest.ini_options] +testpaths = 'tests' +addopts = "-ra -q -r fEX" +asyncio_mode = "auto" +asyncio_default_fixture_loop_scope = "function" +filterwarnings = [] +timeout = 120 +markers = [ + "integration: marks tests as integration tests that require external services", +] + +[tool.ruff] +extend = "../../pyproject.toml" + +[tool.ruff.lint.per-file-ignores] +"tests/**" = ["D", "INP", "TD", "ERA001", "RUF", "S"] + +[tool.coverage.run] +omit = [ + "**/__init__.py" +] + +[tool.pyright] +extends = "../../pyproject.toml" +include = ["agent_framework_monty"] +exclude = ['tests'] + +[tool.mypy] +plugins = ['pydantic.mypy'] +strict = true +python_version = "3.10" +ignore_missing_imports = true +disallow_untyped_defs = true +no_implicit_optional = true +check_untyped_defs = true +warn_return_any = true +show_error_codes = true +warn_unused_ignores = false +disallow_incomplete_defs = true +disallow_untyped_decorators = true + +[tool.bandit] +targets = ["agent_framework_monty"] +exclude_dirs = ["tests"] + +[tool.poe] +executor.type = "uv" +include = "../../shared_tasks.toml" + +[tool.poe.tasks.mypy] +help = "Run MyPy for this package." +cmd = "mypy --config-file $POE_ROOT/pyproject.toml agent_framework_monty" + +[tool.poe.tasks.test] +help = "Run the default unit test suite for this package." +cmd = 'pytest -m "not integration" --cov=agent_framework_monty --cov-report=term-missing:skip-covered tests' + +[tool.poe.tasks.test-integration] +help = "Run integration tests for this package (requires pydantic-monty)." +cmd = 'pytest -m "integration" tests' + +[tool.flit.module] +name = "agent_framework_monty" + +[build-system] +requires = ["flit-core >= 3.11,<4.0"] +build-backend = "flit_core.buildapi" diff --git a/python/packages/monty/tests/monty/test_monty_codeact.py b/python/packages/monty/tests/monty/test_monty_codeact.py new file mode 100644 index 0000000000..43c8e3acac --- /dev/null +++ b/python/packages/monty/tests/monty/test_monty_codeact.py @@ -0,0 +1,642 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Hermetic unit tests for ``agent_framework_monty``. + +These tests inject a fake Monty runtime via ``monkeypatch`` so they run without +the real ``pydantic-monty`` package doing any work. End-to-end tests against +the real runtime live in ``test_monty_codeact_integration.py``. +""" + +from __future__ import annotations + +import json +import sys +import types +from collections.abc import Iterable, Iterator +from dataclasses import dataclass, field +from pathlib import Path +from typing import Annotated, Any +from unittest.mock import MagicMock + +import pytest +from agent_framework import Content, FunctionTool, Message, tool +from agent_framework._sessions import SessionContext + +from agent_framework_monty import MontyCodeActProvider, MontyExecuteCodeTool +from agent_framework_monty import _execute_code_tool as execute_code_module +from agent_framework_monty import _monty_bridge as bridge_module + +# --------------------------------------------------------------------------- +# Fake Monty runtime - drop-in replacement for pydantic_monty +# --------------------------------------------------------------------------- + + +@dataclass +class _FakeMontyComplete: + output: Any = None + + +@dataclass +class _FakeFunctionSnapshot: + function_name: str + call_id: int + args: tuple[Any, ...] = () + kwargs: dict[str, Any] = field(default_factory=dict) + is_os_function: bool = False + _script: _FakeScript | None = None + + def resume(self, payload: Any) -> Any: + assert self._script is not None, "Snapshot must be attached to a script." + return self._script.advance(("function_resume", self, payload)) + + +@dataclass +class _FakeFutureSnapshot: + pending_call_ids: list[int] + _script: _FakeScript | None = None + + def resume(self, payload: Any) -> Any: + assert self._script is not None, "Snapshot must be attached to a script." + return self._script.advance(("future_resume", self, payload)) + + +@dataclass +class _FakeNameLookupSnapshot: + variable_name: str + + +@dataclass +class _PrintAction: + """Marker pushed onto a script to emit captured stdout via the print callback.""" + + text: str + + +class _FakeScript: + """Replayable Monty progress script with a resume log.""" + + def __init__(self, items: Iterable[Any]) -> None: + self._queue: list[Any] = list(items) + self.resume_log: list[tuple[str, Any, Any]] = [] + + def attach(self, snapshot: Any) -> Any: + snapshot._script = self + return snapshot + + def next_item(self) -> Any: + if not self._queue: + return _FakeMontyComplete(output=None) + item = self._queue.pop(0) + if isinstance(item, _FakeMontyComplete): + return item + if isinstance(item, _PrintAction): + return item + if isinstance(item, _FakeNameLookupSnapshot): + return item + return self.attach(item) + + def advance(self, log_entry: tuple[str, Any, Any]) -> Any: + self.resume_log.append(log_entry) + return self.next_item() + + +_current_script: list[_FakeScript | None] = [None] + + +def _set_script(*items: Any) -> _FakeScript: + script = _FakeScript(items) + _current_script[0] = script + return script + + +def _get_script() -> _FakeScript: + script = _current_script[0] + assert script is not None, "Test must call _set_script(...) before running code." + return script + + +class _FakeMonty: + def __init__( + self, + code: str, + *, + script_name: str, + type_check: bool, + type_check_stubs: str | None, + ) -> None: + self.code = code + self.script_name = script_name + self.type_check = type_check + self.type_check_stubs = type_check_stubs + self._script = _get_script() + + def start(self, *, print_callback: Any) -> Any: + while True: + item = self._script.next_item() + if isinstance(item, _PrintAction): + print_callback("stdout", item.text) + continue + return item + + +@pytest.fixture(autouse=True) +def fake_monty_module(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]: + """Install a fake ``pydantic_monty`` module for the duration of each test.""" + fake = types.ModuleType("pydantic_monty") + fake.Monty = _FakeMonty # type: ignore[attr-defined] + fake.MontyComplete = _FakeMontyComplete # type: ignore[attr-defined] + fake.FunctionSnapshot = _FakeFunctionSnapshot # type: ignore[attr-defined] + fake.FutureSnapshot = _FakeFutureSnapshot # type: ignore[attr-defined] + fake.NameLookupSnapshot = _FakeNameLookupSnapshot # type: ignore[attr-defined] + + monkeypatch.setitem(sys.modules, "pydantic_monty", fake) + _current_script[0] = None + yield + _current_script[0] = None + + +# --------------------------------------------------------------------------- +# Sample tools used across tests +# --------------------------------------------------------------------------- + + +@tool +def add_tool( + a: Annotated[int, "First addend"], + b: Annotated[int, "Second addend"], +) -> int: + """Add two integers.""" + return a + b + + +@tool +def mul_tool( + a: Annotated[int, "First factor"], + b: Annotated[int, "Second factor"], +) -> int: + """Multiply two integers.""" + return a * b + + +@tool(approval_mode="always_require") +def dangerous_tool(payload: Annotated[str, "Anything"]) -> str: + """A tool that always requires approval.""" + return payload + + +# --------------------------------------------------------------------------- +# MontyExecuteCodeTool tests +# --------------------------------------------------------------------------- + + +def test_tool_construction_defaults() -> None: + monty_tool = MontyExecuteCodeTool() + assert monty_tool.name == "execute_code" + assert monty_tool.approval_mode == "never_require" + assert monty_tool.get_tools() == [] + + +def test_add_remove_clear_tools_round_trip() -> None: + monty_tool = MontyExecuteCodeTool() + + monty_tool.add_tools([add_tool, mul_tool]) + assert [t.name for t in monty_tool.get_tools()] == ["add_tool", "mul_tool"] + + monty_tool.remove_tool("add_tool") + assert [t.name for t in monty_tool.get_tools()] == ["mul_tool"] + + with pytest.raises(KeyError): + monty_tool.remove_tool("missing") + + monty_tool.clear_tools() + assert monty_tool.get_tools() == [] + + +def test_approval_required_tool_gates_execute_code() -> None: + monty_tool = MontyExecuteCodeTool(tools=[add_tool]) + assert monty_tool.approval_mode == "never_require" + + monty_tool.add_tools([dangerous_tool]) + assert monty_tool.approval_mode == "always_require" + + monty_tool.remove_tool("dangerous_tool") + assert monty_tool.approval_mode == "never_require" + + +def test_default_approval_mode_always_require_is_sticky() -> None: + monty_tool = MontyExecuteCodeTool(tools=[add_tool], approval_mode="always_require") + assert monty_tool.approval_mode == "always_require" + + monty_tool.clear_tools() + assert monty_tool.approval_mode == "always_require" + + +def test_dynamic_description_reflects_registered_tools() -> None: + monty_tool = MontyExecuteCodeTool(tools=[add_tool]) + description = monty_tool.description + assert "add_tool" in description + assert "Monty" in description + + monty_tool.add_tools([mul_tool]) + description_updated = monty_tool.description + assert "mul_tool" in description_updated + + +def test_create_run_tool_snapshots_current_state() -> None: + monty_tool = MontyExecuteCodeTool(tools=[add_tool], approval_mode="never_require") + run_tool = monty_tool.create_run_tool() + + assert run_tool is not monty_tool + assert [t.name for t in run_tool.get_tools()] == ["add_tool"] + assert run_tool.approval_mode == monty_tool.approval_mode + + # Mutating the original must not leak into the snapshot. + monty_tool.add_tools([mul_tool]) + assert [t.name for t in run_tool.get_tools()] == ["add_tool"] + + +def test_build_serializable_state_matches_effective_config() -> None: + monty_tool = MontyExecuteCodeTool(tools=[add_tool, dangerous_tool]) + state = monty_tool.build_serializable_state() + assert state["runtime"] == "monty" + assert state["approval_mode"] == "always_require" + assert set(state["tool_names"]) == {"add_tool", "dangerous_tool"} + assert state["workspace_root"] is None + assert state["file_mounts"] == [] + assert state["resource_limits"] is None + + +def test_file_mounts_normalized_and_round_tripped(tmp_path: Path) -> None: + from agent_framework_monty import FileMount + from agent_framework_monty._execute_code_tool import _normalize_mount_path + + host_a = tmp_path / "a" + host_a.mkdir() + host_b = tmp_path / "b" + host_b.mkdir() + + monty_tool = MontyExecuteCodeTool( + file_mounts=[ + str(host_a), # shorthand: same path on both sides + (str(host_b), "/work"), # explicit tuple + FileMount(host_path=host_a, mount_path="/data", mode="read-only"), + ], + ) + + mounts = monty_tool.get_file_mounts() + by_mount = {m.mount_path: m for m in mounts} + + # The shorthand string is normalized through _normalize_mount_path (POSIX-style), + # so on Windows `C:\\...` becomes `/C:/...`. Compare against the same normalizer. + shorthand_key = _normalize_mount_path(str(host_a)) + assert set(by_mount) == {shorthand_key, "/work", "/data"} + assert by_mount["/work"].host_path == host_b.resolve() + assert by_mount["/data"].mode == "read-only" + assert by_mount[shorthand_key].mode == "overlay" # default + + +def test_workspace_root_auto_mounts_at_input(tmp_path: Path) -> None: + monty_tool = MontyExecuteCodeTool(workspace_root=tmp_path) + mounts = monty_tool._effective_mounts() + assert any(m.mount_path == "/input" and m.mode == "read-write" for m in mounts) + + +def test_workspace_root_yields_to_explicit_input_mount(tmp_path: Path) -> None: + from agent_framework_monty import FileMount + + explicit = tmp_path / "explicit" + explicit.mkdir() + monty_tool = MontyExecuteCodeTool( + workspace_root=tmp_path, + file_mounts=[FileMount(host_path=explicit, mount_path="/input", mode="read-only")], + ) + input_mounts = [m for m in monty_tool._effective_mounts() if m.mount_path == "/input"] + assert len(input_mounts) == 1 + assert input_mounts[0].mode == "read-only" + assert input_mounts[0].host_path == explicit.resolve() + + +def test_remove_file_mount_raises_on_missing() -> None: + monty_tool = MontyExecuteCodeTool() + with pytest.raises(KeyError): + monty_tool.remove_file_mount("/never-added") + + +def test_dynamic_description_mentions_filesystem_when_mounts_configured(tmp_path: Path) -> None: + monty_tool = MontyExecuteCodeTool(workspace_root=tmp_path) + description = monty_tool.description + assert "Filesystem access is enabled" in description + assert "/input" in description + + +def test_dynamic_description_default_mentions_no_filesystem() -> None: + monty_tool = MontyExecuteCodeTool() + description = monty_tool.description + assert "Filesystem access is unavailable" in description + + +def test_resource_limits_round_trip() -> None: + monty_tool = MontyExecuteCodeTool(resource_limits={"max_duration_secs": 5.0}) + assert monty_tool.resource_limits == {"max_duration_secs": 5.0} + state = monty_tool.build_serializable_state() + assert state["resource_limits"] == {"max_duration_secs": 5.0} + + +def test_build_instructions_includes_registered_tools() -> None: + monty_tool = MontyExecuteCodeTool(tools=[add_tool]) + instructions = monty_tool.build_instructions(tools_visible_to_model=False) + assert "add_tool" in instructions + assert "execute_code" in instructions + assert "asyncio.gather" in instructions + + +def test_execute_code_filtered_out_when_added_as_tool() -> None: + spurious = FunctionTool( + name="execute_code", + description="should not appear", + func=lambda: None, + ) + monty_tool = MontyExecuteCodeTool(tools=[spurious, add_tool]) + assert [t.name for t in monty_tool.get_tools()] == ["add_tool"] + + +# --------------------------------------------------------------------------- +# _run_code behavior with the fake Monty runtime +# --------------------------------------------------------------------------- + + +async def test_run_code_with_no_tools_returns_default_text() -> None: + _set_script(_FakeMontyComplete(output=None)) + + monty_tool = MontyExecuteCodeTool() + result = await monty_tool._run_code(code="None") + + assert len(result) == 1 + assert isinstance(result[0], Content) + + +async def test_run_code_surfaces_stdout_and_output() -> None: + _set_script(_PrintAction("hello\n"), _FakeMontyComplete(output=42)) + + monty_tool = MontyExecuteCodeTool() + result = await monty_tool._run_code(code="print('hello')") + + text_contents = [c for c in result if c.type == "text"] + assert any("hello" in (c.text or "") for c in text_contents) + assert any( + (c.text or "").strip() and json.loads(c.text or "null") == 42 + for c in text_contents + if (c.text or "").strip().isdigit() + ) + + +async def test_run_code_direct_typed_call_invokes_registered_tool() -> None: + func_snapshot = _FakeFunctionSnapshot( + function_name="add_tool", + call_id=1, + kwargs={"a": 2, "b": 3}, + ) + future_snapshot = _FakeFutureSnapshot(pending_call_ids=[1]) + script = _set_script(func_snapshot, future_snapshot, _FakeMontyComplete(output=None)) + + monty_tool = MontyExecuteCodeTool(tools=[add_tool]) + await monty_tool._run_code(code="await add_tool(a=2, b=3)") + + payloads = [payload for _, _, payload in script.resume_log] + assert {"future": ...} in payloads + final_resume = next(p for p in payloads if isinstance(p, dict) and 1 in p) + assert final_resume[1] == {"return_value": 5} + + +async def test_run_code_call_tool_fallback_invokes_registered_tool() -> None: + func_snapshot = _FakeFunctionSnapshot( + function_name="call_tool", + call_id=7, + args=("add_tool",), + kwargs={"a": 4, "b": 8}, + ) + future_snapshot = _FakeFutureSnapshot(pending_call_ids=[7]) + script = _set_script(func_snapshot, future_snapshot, _FakeMontyComplete(output=None)) + + monty_tool = MontyExecuteCodeTool(tools=[add_tool]) + await monty_tool._run_code(code="await call_tool('add_tool', a=4, b=8)") + + payloads = [payload for _, _, payload in script.resume_log] + final_resume = next(p for p in payloads if isinstance(p, dict) and 7 in p) + assert final_resume[7] == {"return_value": 12} + + +async def test_run_code_unknown_tool_returns_nameerror_resume() -> None: + func_snapshot = _FakeFunctionSnapshot( + function_name="does_not_exist", + call_id=11, + ) + script = _set_script(func_snapshot, _FakeMontyComplete(output=None)) + + monty_tool = MontyExecuteCodeTool(tools=[add_tool]) + await monty_tool._run_code(code="await does_not_exist()") + + payloads = [payload for _, _, payload in script.resume_log] + assert any(isinstance(p, dict) and p.get("exc_type") == "NameError" for p in payloads) + + +async def test_run_code_os_function_is_rejected_with_permissionerror() -> None: + os_snapshot = _FakeFunctionSnapshot( + function_name="os.listdir", + call_id=12, + is_os_function=True, + ) + script = _set_script(os_snapshot, _FakeMontyComplete(output=None)) + + monty_tool = MontyExecuteCodeTool(tools=[add_tool]) + await monty_tool._run_code(code="import os; os.listdir('.')") + + payloads = [payload for _, _, payload in script.resume_log] + assert any(isinstance(p, dict) and p.get("exc_type") == "PermissionError" for p in payloads) + + +async def test_when_any_returns_nameerror_now_that_it_is_removed() -> None: + """`when_any` is no longer part of the DSL and should resolve to a NameError.""" + func_snapshot = _FakeFunctionSnapshot( + function_name="when_any", + call_id=99, + args=([{"tool": "add_tool", "kwargs": {"a": 1, "b": 2}}],), + ) + script = _set_script(func_snapshot, _FakeMontyComplete(output=None)) + + monty_tool = MontyExecuteCodeTool(tools=[add_tool]) + await monty_tool._run_code(code="await when_any([{'tool': 'add_tool', 'kwargs': {'a': 1, 'b': 2}}])") + + payloads = [payload for _, _, payload in script.resume_log] + assert any(isinstance(p, dict) and p.get("exc_type") == "NameError" for p in payloads) + + +async def test_run_code_call_tool_with_unregistered_name_returns_error() -> None: + func_snapshot = _FakeFunctionSnapshot( + function_name="call_tool", + call_id=20, + args=("missing",), + kwargs={}, + ) + script = _set_script(func_snapshot, _FakeMontyComplete(output=None)) + + monty_tool = MontyExecuteCodeTool(tools=[add_tool]) + await monty_tool._run_code(code="await call_tool('missing')") + + payloads = [payload for _, _, payload in script.resume_log] + assert any( + isinstance(p, dict) and p.get("exc_type") == "ValueError" and "Tool 'missing'" in p.get("message", "") + for p in payloads + ) + + +async def test_run_code_returns_error_content_on_runtime_failure(monkeypatch: pytest.MonkeyPatch) -> None: + class _BoomBridge: + def __init__(self, tool_map: Any, **_: Any) -> None: + pass + + async def run(self, code: str) -> dict[str, Any]: + raise RuntimeError("boom") + + monkeypatch.setattr(execute_code_module, "InlineCodeBridge", _BoomBridge) + + monty_tool = MontyExecuteCodeTool() + result = await monty_tool._run_code(code="x = 1") + assert len(result) == 1 + assert result[0].type == "error" + assert "boom" in (result[0].error_details or "") + + +# --------------------------------------------------------------------------- +# MontyCodeActProvider tests +# --------------------------------------------------------------------------- + + +async def test_provider_injects_execute_code_tool_and_instructions() -> None: + provider = MontyCodeActProvider(tools=[add_tool]) + context = SessionContext(input_messages=[Message(role="user", contents=[Content.from_text("hi")])]) + state: dict[str, Any] = {} + + await provider.before_run(agent=MagicMock(), session=None, context=context, state=state) + + assert state["monty_codeact"]["tool_names"] == ["add_tool"] + assert any("add_tool" in instruction for instruction in context.instructions) + assert len(context.tools) == 1 + assert isinstance(context.tools[0], MontyExecuteCodeTool) + # The injected tool is a per-run snapshot, not the provider's stored copy. + assert context.tools[0] is not provider._execute_code_tool # type: ignore[attr-defined] + + +def test_provider_delegates_tool_management_to_internal_tool() -> None: + provider = MontyCodeActProvider() + provider.add_tools([add_tool, mul_tool]) + assert [t.name for t in provider.get_tools()] == ["add_tool", "mul_tool"] + + provider.remove_tool("add_tool") + assert [t.name for t in provider.get_tools()] == ["mul_tool"] + + provider.clear_tools() + assert provider.get_tools() == [] + + +# --------------------------------------------------------------------------- +# generate_type_stubs - signature smoke test +# --------------------------------------------------------------------------- + + +def test_generate_type_stubs_emits_dsl_and_tool_signatures() -> None: + def custom(x: int, y: str = "z") -> bool: + """Stub-test tool.""" + return True + + stubs = bridge_module.generate_type_stubs({"custom": custom}) + + assert "async def call_tool(name: str, **kwargs: Any) -> Any:" in stubs + assert "async def custom(x: int, y: str = ...) -> bool:" in stubs + assert "when_any" not in stubs + + +def test_generate_type_stubs_preserves_none_and_optional() -> None: + + def nullable_return(x: int) -> None: + """Returns nothing.""" + return + + def optional_param(x: int | None = None) -> bool: # noqa: UP045 - intentional + """Optional via typing.Optional.""" + return x is None + + def union_param(x: int | str | None) -> str: # noqa: UP007 - intentional + """Union with None.""" + return str(x) + + stubs = bridge_module.generate_type_stubs({ + "nullable_return": nullable_return, + "optional_param": optional_param, + "union_param": union_param, + }) + + # ``None`` return must round-trip as None, not Any. + assert "async def nullable_return(x: int) -> None:" in stubs + # ``Optional[X]`` is ``Union[X, None]`` at runtime; preserve None. + assert "async def optional_param(x: int | None = ...) -> bool:" in stubs + # Multi-arm union with None. + assert "async def union_param(x: int | str | None) -> str:" in stubs + + +def test_generate_type_stubs_skips_non_identifier_tool_names() -> None: + """Tool names that are not valid Python identifiers must not be splatted into stub source. + + The model can still reach them via ``call_tool("weird-name", ...)`` at + runtime; they just don't get type-checked stubs. + """ + + def evil(x: int) -> int: + return x + + def normal(x: int) -> int: + return x + + stubs = bridge_module.generate_type_stubs({ + # Hyphens are not valid identifier chars. + "weird-name": evil, + # Newlines in the name would inject arbitrary stub source. + "broken\n pass\nasync def injected": evil, + # Python keywords are valid identifiers per ``str.isidentifier()`` but + # would still produce uncompilable stubs. + "async": evil, + # Real tool that should still appear. + "normal": normal, + }) + + assert "async def normal(x: int) -> int:" in stubs + assert "weird-name" not in stubs + assert "injected" not in stubs + assert "async def async(" not in stubs + + +async def test_invoke_tool_awaits_partial_wrapped_async_method() -> None: + """A FunctionTool callback registered via partial(FunctionTool.invoke, ...) must be awaited. + + Regression for PR #5915 review feedback: relying on ``inspect.iscoroutinefunction`` + to choose between ``await`` and ``asyncio.to_thread`` is fragile for + ``functools.partial`` wrappers (cpython#98590) and would surface the + returned coroutine as a JSON-serialization error instead of the real + tool result. The bridge must always ``await`` entries in ``self.tool_map``. + """ + from functools import partial + + from agent_framework_monty._monty_bridge import InlineCodeBridge + + @tool + def adder(a: Annotated[int, ""], b: Annotated[int, ""]) -> int: + """Add.""" + return a + b + + # Mirrors what _make_tool_callback returns. + cb = partial(adder.invoke, skip_parsing=True) + bridge = InlineCodeBridge({"adder": cb}) + + cid, payload = await bridge._invoke_tool(7, "adder", {"a": 6, "b": 7}) + assert cid == 7 + assert payload == {"return_value": 13}, payload diff --git a/python/packages/monty/tests/monty/test_monty_codeact_integration.py b/python/packages/monty/tests/monty/test_monty_codeact_integration.py new file mode 100644 index 0000000000..2728936c9d --- /dev/null +++ b/python/packages/monty/tests/monty/test_monty_codeact_integration.py @@ -0,0 +1,601 @@ +# Copyright (c) Microsoft. All rights reserved. + +"""Integration tests for ``agent_framework_monty`` exercising the real Monty runtime. + +These tests import the real ``pydantic-monty`` package and run actual Python +code through it via :class:`MontyExecuteCodeTool`. They are marked +``@pytest.mark.integration`` and are skipped automatically when +``pydantic_monty`` is unavailable. +""" + +from __future__ import annotations + +import asyncio +import importlib.util +import time +from typing import Annotated, Any +from unittest.mock import MagicMock + +import pytest +from agent_framework import Agent, Content, Message, tool +from agent_framework._sessions import SessionContext + +from agent_framework_monty import MontyCodeActProvider, MontyExecuteCodeTool + + +def _monty_integration_skip_reason() -> str | None: + if importlib.util.find_spec("pydantic_monty") is None: + return "pydantic-monty is not installed." + return None + + +pytestmark = [ + pytest.mark.integration, + pytest.mark.skipif( + _monty_integration_skip_reason() is not None, + reason=_monty_integration_skip_reason() or "Monty integration tests are disabled.", + ), +] + + +# --------------------------------------------------------------------------- +# Sample tools +# --------------------------------------------------------------------------- + + +@tool +def add( + a: Annotated[int, "First addend"], + b: Annotated[int, "Second addend"], +) -> int: + """Return ``a + b``.""" + return a + b + + +@tool +def multiply( + a: Annotated[int, "First factor"], + b: Annotated[int, "Second factor"], +) -> int: + """Return ``a * b``.""" + return a * b + + +@tool +async def async_echo(value: Annotated[str, "Value to echo"]) -> str: + """Return ``value`` after a no-op await.""" + await asyncio.sleep(0) + return value + + +def _async_slow_factory(label: str, delay: float) -> Any: + @tool(name=f"slow_{label}") + async def slow(value: Annotated[int, "Input"]) -> int: + """Sleep asynchronously, then return value untouched.""" + await asyncio.sleep(delay) + return value + + return slow + + +@tool(approval_mode="always_require") +def restricted(payload: Annotated[str, "Any text"]) -> str: + """A tool that always requires approval.""" + return payload + + +def _text_outputs(contents: list[Content]) -> list[str]: + return [c.text or "" for c in contents if c.type == "text"] + + +# --------------------------------------------------------------------------- +# Basic execution +# --------------------------------------------------------------------------- + + +async def test_plain_python_print_round_trips() -> None: + monty_tool = MontyExecuteCodeTool() + result = await monty_tool._run_code(code="print('hello world')") + + texts = _text_outputs(result) + assert any("hello world" in text for text in texts) + + +async def test_last_expression_value_is_returned() -> None: + monty_tool = MontyExecuteCodeTool() + result = await monty_tool._run_code(code="5 + 7") + + texts = _text_outputs(result) + assert any(text.strip() == "12" for text in texts) + + +# --------------------------------------------------------------------------- +# Tool dispatch +# --------------------------------------------------------------------------- + + +async def test_direct_typed_tool_call_invokes_host() -> None: + monty_tool = MontyExecuteCodeTool(tools=[add]) + result = await monty_tool._run_code(code="print(await add(a=2, b=3))") + + texts = _text_outputs(result) + assert any("5" in text for text in texts) + + +async def test_call_tool_fallback_invokes_host() -> None: + monty_tool = MontyExecuteCodeTool(tools=[add]) + result = await monty_tool._run_code(code="print(await call_tool('add', a=4, b=8))") + + texts = _text_outputs(result) + assert any("12" in text for text in texts) + + +async def test_async_host_tool_is_awaited() -> None: + monty_tool = MontyExecuteCodeTool(tools=[async_echo]) + result = await monty_tool._run_code(code="print(await async_echo(value='ping'))") + + texts = _text_outputs(result) + assert any("ping" in text for text in texts) + + +# --------------------------------------------------------------------------- +# Concurrency +# --------------------------------------------------------------------------- + + +async def test_asyncio_gather_fans_out_tool_calls_concurrently() -> None: + """Two async tools dispatched via ``asyncio.gather`` should run on the event loop in parallel. + + Sync tools cannot fan out (FunctionTool.invoke runs them inline on the event loop), + so this test uses async host tools to verify the bridge's gather pipeline does + not introduce extra serialization. + """ + slow_a = _async_slow_factory("a", delay=0.25) + slow_b = _async_slow_factory("b", delay=0.25) + monty_tool = MontyExecuteCodeTool(tools=[slow_a, slow_b]) + + code = """ +results = await asyncio.gather(slow_a(value=1), slow_b(value=2)) +print(results) +""" + + start = time.perf_counter() + result = await monty_tool._run_code(code=code) + elapsed = time.perf_counter() - start + + texts = _text_outputs(result) + assert any("[1, 2]" in text for text in texts) + # Allow some scheduling slack but verify it's noticeably less than sequential (~0.5s). + assert elapsed < 0.45, f"Expected concurrent execution; took {elapsed:.3f}s" + + +# --------------------------------------------------------------------------- +# Sandbox safety + type checking +# --------------------------------------------------------------------------- + + +async def test_type_check_rejects_wrong_argument_type() -> None: + invocation_count = {"count": 0} + + @tool + def typed_add( + a: Annotated[int, "First"], + b: Annotated[int, "Second"], + ) -> int: + """Add two ints; records invocations.""" + invocation_count["count"] += 1 + return a + b + + monty_tool = MontyExecuteCodeTool(tools=[typed_add]) + result = await monty_tool._run_code(code="print(await typed_add(a='not an int', b=3))") + + texts = _text_outputs(result) + errors = [c for c in result if c.type == "error"] + # Either ty raises and surfaces as an error Content, or Monty reports the typing error in stdout. + assert errors or any("type" in text.lower() or "monty" in text.lower() for text in texts) + assert invocation_count["count"] == 0 + + +async def test_os_calls_are_blocked() -> None: + monty_tool = MontyExecuteCodeTool() + code = """ +try: + import os + os.listdir('/') + print('LEAKED') +except PermissionError as exc: + print('blocked:', exc) +except Exception as exc: + print('other:', type(exc).__name__) +""" + result = await monty_tool._run_code(code=code) + texts = _text_outputs(result) + assert not any("LEAKED" in text for text in texts) + assert any("blocked" in text or "PermissionError" in text or "other" in text for text in texts) + + +async def test_unknown_tool_call_returns_clean_error() -> None: + monty_tool = MontyExecuteCodeTool(tools=[add]) + code = """ +try: + await call_tool('missing') +except Exception as exc: + print('err:', type(exc).__name__, str(exc)) +""" + result = await monty_tool._run_code(code=code) + texts = _text_outputs(result) + assert any("missing" in text for text in texts) + + +# --------------------------------------------------------------------------- +# Print capture +# --------------------------------------------------------------------------- + + +async def test_print_truncation_caps_output() -> None: + monty_tool = MontyExecuteCodeTool() + # Emit more than MAX_PRINT_OUTPUT_CHARS bytes of output. + code = """ +for _ in range(2000): + print('X' * 64) +""" + result = await monty_tool._run_code(code=code) + texts = _text_outputs(result) + combined = "\n".join(texts) + assert len(combined) <= 9000 # MAX_PRINT_OUTPUT_CHARS=8192 plus a small truncation marker + assert "[stdout truncated]" in combined + + +# --------------------------------------------------------------------------- +# Filesystem (workspace_root, file_mounts, output capture, resource limits) +# --------------------------------------------------------------------------- + + +async def test_workspace_root_reads_seed_files_from_host(tmp_path: Any) -> None: + seed = tmp_path / "seed.txt" + seed.write_text("hello from host", encoding="utf-8") + monty_tool = MontyExecuteCodeTool(workspace_root=tmp_path) + + code = """ +import pathlib +data = pathlib.Path('/input/seed.txt').read_text() +print(data) +""" + result = await monty_tool._run_code(code=code) + texts = _text_outputs(result) + assert any("hello from host" in text for text in texts) + + +async def test_workspace_root_writes_are_captured_as_content(tmp_path: Any) -> None: + monty_tool = MontyExecuteCodeTool(workspace_root=tmp_path) + + code = """ +import pathlib +pathlib.Path('/input/report.txt').write_text('result-payload') +print('wrote report') +""" + result = await monty_tool._run_code(code=code) + data_contents = [c for c in result if c.type == "data"] + assert len(data_contents) == 1, [c.type for c in result] + written = data_contents[0] + # Content.from_data stores bytes as a base64-encoded data: URI. + import base64 + + assert written.uri is not None + payload = written.uri.split(",", 1)[1] + assert base64.b64decode(payload) == b"result-payload" + assert (written.additional_properties or {}).get("path") == "/input/report.txt" + # And the file actually landed on the host filesystem (read-write mode). + assert (tmp_path / "report.txt").read_text() == "result-payload" + + +async def test_read_only_mount_writes_are_rejected_and_not_captured(tmp_path: Any) -> None: + from agent_framework_monty import FileMount + + seed = tmp_path / "seed.txt" + seed.write_text("ro-content", encoding="utf-8") + + monty_tool = MontyExecuteCodeTool( + file_mounts=[FileMount(host_path=tmp_path, mount_path="/ro", mode="read-only")], + ) + + code = """ +import pathlib +print(pathlib.Path('/ro/seed.txt').read_text()) +try: + pathlib.Path('/ro/should-not-exist.txt').write_text('nope') + print('LEAKED') +except Exception as exc: + print('write blocked:', type(exc).__name__) +""" + result = await monty_tool._run_code(code=code) + texts = _text_outputs(result) + assert any("ro-content" in t for t in texts) + assert not any("LEAKED" in t for t in texts) + # No write went to host; no captured Content for the rejected write. + assert not (tmp_path / "should-not-exist.txt").exists() + assert not any(c.type == "data" for c in result) + + +async def test_overlay_mount_writes_do_not_persist_to_host(tmp_path: Any) -> None: + from agent_framework_monty import FileMount + + monty_tool = MontyExecuteCodeTool( + file_mounts=[FileMount(host_path=tmp_path, mount_path="/overlay", mode="overlay")], + ) + + code = """ +import pathlib +pathlib.Path('/overlay/scratch.txt').write_text('overlay-only') +print('wrote') +""" + result = await monty_tool._run_code(code=code) + assert any("wrote" in t for t in _text_outputs(result)) + # Overlay writes stay in-memory: nothing on host, nothing captured. + assert not (tmp_path / "scratch.txt").exists() + assert not any(c.type == "data" for c in result) + + +async def test_resource_limit_short_duration_aborts_long_loop() -> None: + # Cap CPU time hard; a busy loop should be killed before it can print 'done'. + monty_tool = MontyExecuteCodeTool(resource_limits={"max_duration_secs": 0.2}) + + code = """ +total = 0 +for i in range(10_000_000): + total += i +print('done', total) +""" + result = await monty_tool._run_code(code=code) + # Result is either an error Content (timeout surfaces as RuntimeError) or + # truncated stdout without the 'done' marker. + texts = _text_outputs(result) + assert not any("done" in t for t in texts), texts + + +# --------------------------------------------------------------------------- +# Symlink escape regression (MSRC-style) +# --------------------------------------------------------------------------- + + +def _symlinks_supported(tmp: Any) -> bool: + """Return True if the current platform/environment supports symlinks. + + Mirrors python/packages/core/tests/core/test_skills.py so the symlink + regression tests are skipped on restricted Windows CI runners instead of + failing on ``OSError`` / ``NotImplementedError`` during creation. + """ + test_target = tmp / "_symlink_test_target" + test_link = tmp / "_symlink_test_link" + try: + test_target.write_text("test", encoding="utf-8") + test_link.symlink_to(test_target) + return True + except (OSError, NotImplementedError): + return False + finally: + test_link.unlink(missing_ok=True) + test_target.unlink(missing_ok=True) + + +async def test_symlinks_inside_workspace_are_not_followed_by_runtime(tmp_path: Any) -> None: + """A pre-existing symlink in workspace_root must NOT let sandbox code read its target. + + Monty's mount layer enforces this (PermissionError at the OS bridge), but we + pin the behavior here so any future change to the OS dispatch path is + detected. + """ + if not _symlinks_supported(tmp_path): + pytest.skip("Symlinks not supported on this platform/environment") + + workspace = tmp_path / "workspace" + workspace.mkdir() + outside = tmp_path / "outside_secret.txt" + outside.write_text("SECRET_OUTSIDE_WORKSPACE", encoding="utf-8") + (workspace / "leak.txt").symlink_to(outside) + + monty_tool = MontyExecuteCodeTool(workspace_root=workspace) + code = """ +import pathlib +try: + print('read:', pathlib.Path('/input/leak.txt').read_text()) +except PermissionError as exc: + print('blocked:', exc) +except Exception as exc: + print('other:', type(exc).__name__, exc) +""" + result = await monty_tool._run_code(code=code) + texts = _text_outputs(result) + assert not any("SECRET_OUTSIDE_WORKSPACE" in t for t in texts), texts + assert any("blocked" in t or "PermissionError" in t or "other" in t for t in texts), texts + + +async def test_post_capture_skips_symlinks_pointing_outside_workspace(tmp_path: Any) -> None: + """File capture must NOT read through a symlink that points outside the mount. + + Reproduces the MSRC-reported Hyperlight pattern in Monty's post-execution + file-capture path: an attacker-placed ``workspace/leak.txt -> /outside/secret`` + must not be returned as Content. + """ + if not _symlinks_supported(tmp_path): + pytest.skip("Symlinks not supported on this platform/environment") + workspace = tmp_path / "workspace" + workspace.mkdir() + outside = tmp_path / "outside_secret.txt" + outside.write_text("SECRET_OUTSIDE_WORKSPACE", encoding="utf-8") + (workspace / "leak.txt").symlink_to(outside) + outside_dir = tmp_path / "outside_dir" + outside_dir.mkdir() + (outside_dir / "deep.txt").write_text("DEEP_SECRET", encoding="utf-8") + (workspace / "leak_dir").symlink_to(outside_dir) + + monty_tool = MontyExecuteCodeTool(workspace_root=workspace) + # Run trivial code so the post-execution scan fires. + result = await monty_tool._run_code(code="print('ran')") + + # Inspect the URIs of any returned data Content items. + import base64 + + leaked_paths: list[str] = [] + leaked_bodies: list[bytes] = [] + for content in result: + if content.type != "data" or not content.uri: + continue + payload = content.uri.split(",", 1)[1] if "," in content.uri else "" + try: + body = base64.b64decode(payload) + except Exception: # noqa: BLE001 + body = b"" + leaked_bodies.append(body) + leaked_paths.append((content.additional_properties or {}).get("path", "")) + + assert not any(b"SECRET_OUTSIDE_WORKSPACE" in body for body in leaked_bodies), ( + "Symlink file outside workspace was captured: " + repr(leaked_paths) + ) + assert not any(b"DEEP_SECRET" in body for body in leaked_bodies), ( + "Symlinked directory escape was captured: " + repr(leaked_paths) + ) + + +async def test_post_capture_still_returns_real_writes_when_symlinks_present(tmp_path: Any) -> None: + """The symlink-skipping logic must not regress capture of legitimate sandbox writes.""" + if not _symlinks_supported(tmp_path): + pytest.skip("Symlinks not supported on this platform/environment") + workspace = tmp_path / "workspace" + workspace.mkdir() + outside = tmp_path / "outside_secret.txt" + outside.write_text("SHOULD_NEVER_LEAK", encoding="utf-8") + (workspace / "leak.txt").symlink_to(outside) + + monty_tool = MontyExecuteCodeTool(workspace_root=workspace) + code = """ +import pathlib +pathlib.Path('/input/report.txt').write_text('legit-output') +print('wrote') +""" + result = await monty_tool._run_code(code=code) + import base64 + + data_items = [c for c in result if c.type == "data" and c.uri] + # Exactly one new file should be captured: report.txt. + assert len(data_items) == 1, [(c.additional_properties or {}).get("path") for c in data_items] + item = data_items[0] + assert (item.additional_properties or {}).get("path") == "/input/report.txt" + payload = item.uri.split(",", 1)[1] if item.uri and "," in item.uri else "" + assert base64.b64decode(payload) == b"legit-output" + + +# --------------------------------------------------------------------------- +# Provider + approval gating +# --------------------------------------------------------------------------- + + +async def test_provider_run_tool_executes_real_monty_end_to_end() -> None: + provider = MontyCodeActProvider(tools=[add]) + context = SessionContext(input_messages=[Message(role="user", contents=[Content.from_text("hi")])]) + state: dict[str, Any] = {} + + await provider.before_run(agent=MagicMock(), session=None, context=context, state=state) + + run_tool = context.tools[0] + assert isinstance(run_tool, MontyExecuteCodeTool) + + result = await run_tool._run_code(code="print(await add(a=10, b=32))") + texts = _text_outputs(result) + assert any("42" in text for text in texts) + + +async def test_approval_required_tool_gates_execute_code_end_to_end() -> None: + provider = MontyCodeActProvider(tools=[restricted]) + context = SessionContext(input_messages=[Message(role="user", contents=[Content.from_text("hi")])]) + state: dict[str, Any] = {} + + await provider.before_run(agent=MagicMock(), session=None, context=context, state=state) + run_tool = context.tools[0] + assert isinstance(run_tool, MontyExecuteCodeTool) + assert run_tool.approval_mode == "always_require" + assert state["monty_codeact"]["approval_mode"] == "always_require" + + +# --------------------------------------------------------------------------- +# End-to-end Agent run with a fake chat client +# --------------------------------------------------------------------------- + + +async def test_agent_runs_monty_codeact_end_to_end() -> None: + """A fake chat client emits one execute_code tool call; Monty runs it end-to-end.""" + from collections.abc import Awaitable, Mapping, MutableSequence + + from agent_framework import ( + BaseChatClient, + ChatResponse, + ChatResponseUpdate, + FunctionInvocationLayer, + ResponseStream, + ) + + class _FakeCodeActChatClient(FunctionInvocationLayer[Any], BaseChatClient[Any]): + def __init__(self) -> None: + FunctionInvocationLayer.__init__(self) + BaseChatClient.__init__(self) + self.call_count = 0 + + def _inner_get_response( + self, + *, + messages: MutableSequence[Message], + stream: bool, + options: Mapping[str, Any], + **kwargs: Any, + ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]: + if stream: + raise AssertionError("Streaming is not used in this integration test.") + + async def _get_response() -> ChatResponse: + self.call_count += 1 + + if self.call_count == 1: + return ChatResponse( + messages=Message( + role="assistant", + contents=[ + Content.from_function_call( + call_id="execute_code_call", + name="execute_code", + arguments={"code": "print(await add(a=6, b=7))"}, + ) + ], + ) + ) + + function_results = [ + content for message in messages for content in message.contents if content.type == "function_result" + ] + assert len(function_results) == 1 + + result_content = function_results[0] + result_text = "" + if isinstance(result_content.result, list): + for item in result_content.result: + text = getattr(item, "text", None) + if text: + result_text += text + else: + result_text = str(result_content.result or "") + + return ChatResponse( + messages=Message( + role="assistant", + contents=[f"answer: {result_text.strip() or 'none'}"], + ) + ) + + return _get_response() + + client = _FakeCodeActChatClient() + provider = MontyCodeActProvider(tools=[add]) + agent = Agent(client=client, context_providers=[provider]) + + response = await agent.run("Add 6 and 7 inside execute_code.") + assert "13" in (response.text or "") + assert client.call_count == 2 diff --git a/python/pyproject.toml b/python/pyproject.toml index d7aa3d3496..3454c53c0f 100644 --- a/python/pyproject.toml +++ b/python/pyproject.toml @@ -88,6 +88,7 @@ agent-framework-github-copilot = { workspace = true } agent-framework-hyperlight = { workspace = true } agent-framework-lab = { workspace = true } agent-framework-mem0 = { workspace = true } +agent-framework-monty = { workspace = true } agent-framework-ollama = { workspace = true } agent-framework-openai = { workspace = true } agent-framework-orchestrations = { workspace = true } diff --git a/python/samples/02-agents/context_providers/code_act/README.md b/python/samples/02-agents/context_providers/code_act/README.md index 264123d70f..4e52c18da4 100644 --- a/python/samples/02-agents/context_providers/code_act/README.md +++ b/python/samples/02-agents/context_providers/code_act/README.md @@ -1,20 +1,31 @@ -# Hyperlight CodeAct context provider +# CodeAct context providers -Demonstrates the provider-owned [Hyperlight](https://github.com/hyperlight-dev/hyperlight) -CodeAct flow. `HyperlightCodeActProvider` injects an `execute_code` tool into the -agent and keeps the registered sandbox tools (`compute`, `fetch_data`) hidden -from the model — the model must call them from inside the sandbox using -`call_tool(...)`. +Demonstrates the provider-owned CodeAct flow with two backends: + +| File | Backend | Notes | +|------|---------|-------| +| [`code_act.py`](code_act.py) | [Hyperlight](https://github.com/hyperlight-dev/hyperlight) WASM sandbox via `HyperlightCodeActProvider` | Hardened sandbox with WASM isolation; sandbox tools called via `call_tool(...)`. | +| [`monty_code_act.py`](monty_code_act.py) | [Monty](https://github.com/pydantic/monty) Rust-based Python interpreter via `MontyCodeActProvider` (alpha) | Cross-platform pure interpreter; sandbox tools can be called as typed async functions (`await compute(...)`) or via `call_tool(...)`. | + +Both providers inject an `execute_code` tool into the agent and keep the +registered sandbox tools (`compute`, `fetch_data`) hidden from the model — the +model invokes them from inside the sandbox. ## Installation ```bash -pip install agent-framework agent-framework-hyperlight --pre +pip install agent-framework agent-framework-hyperlight --pre # Hyperlight sample +pip install agent-framework agent-framework-monty --pre # Monty sample ``` > The Hyperlight Wasm backend is currently published only for `linux/x86_64` and > `win32/AMD64` with Python `<3.14`. On other platforms `execute_code` will fail > at runtime when it tries to create the sandbox. +> +> Monty is cross-platform and has no hypervisor/WASM backend dependency, but it +> interprets a Python subset (e.g. `os`/network/subprocess access is blocked). +> `agent-framework-monty` is an alpha package and is not yet part of +> `agent-framework[all]`; install it explicitly with `--pre`. ## Prerequisites @@ -25,7 +36,8 @@ pip install agent-framework agent-framework-hyperlight --pre ## Run ```bash -python code_act.py +python code_act.py # Hyperlight +python monty_code_act.py # Monty ``` -See [`code_act.py`](code_act.py) for the full annotated example. +See the source files for the full annotated examples. diff --git a/python/samples/02-agents/context_providers/code_act/monty_code_act.py b/python/samples/02-agents/context_providers/code_act/monty_code_act.py new file mode 100644 index 0000000000..862c92c1d7 --- /dev/null +++ b/python/samples/02-agents/context_providers/code_act/monty_code_act.py @@ -0,0 +1,201 @@ +# Copyright (c) Microsoft. All rights reserved. + +from __future__ import annotations + +import asyncio +import logging +import os +from collections.abc import Awaitable, Callable +from typing import Annotated, Any, Literal + +from agent_framework import Agent, FunctionInvocationContext, function_middleware, tool +from agent_framework.foundry import FoundryChatClient +from agent_framework_monty import MontyCodeActProvider +from azure.identity import AzureCliCredential +from dotenv import load_dotenv + +"""This sample demonstrates the provider-owned Monty CodeAct flow. + +The sample keeps `compute` and `fetch_data` off the direct agent tool surface and +registers them only with `MontyCodeActProvider`. The model therefore sees a +single `execute_code` tool and calls the provider-owned tools from inside the +sandbox - either as typed async functions (`await compute(...)`) or via the +generic `call_tool(...)` fallback. + +`MontyCodeActProvider` uses [pydantic-monty](https://github.com/pydantic/monty), +a Rust-based Python interpreter, so it runs cross-platform with no +hypervisor/WASM backend dependency. + +Note: `agent-framework-monty` is an alpha package and is not yet part of +`agent-framework[all]`. Install it explicitly with: + + pip install agent-framework agent-framework-monty --pre + +It is imported as `agent_framework_monty` (no lazy-loading namespace yet). +""" + +load_dotenv() + +_CYAN = "\033[36m" +_YELLOW = "\033[33m" +_GREEN = "\033[32m" +_DIM = "\033[2m" +_RESET = "\033[0m" + + +class _ColoredFormatter(logging.Formatter): + """Dim logger output so it does not compete with sample prints.""" + + def format(self, record: logging.LogRecord) -> str: + return f"{_DIM}{super().format(record)}{_RESET}" + + +logging.basicConfig(level=logging.WARNING) +logging.getLogger().handlers[0].setFormatter( + _ColoredFormatter("[%(asctime)s] %(levelname)s: %(message)s"), +) + + +@function_middleware +async def log_function_calls( + context: FunctionInvocationContext, + call_next: Callable[[], Awaitable[None]], +) -> None: + """Log tool calls, including readable execute_code blocks.""" + import time + + function_name = context.function.name + arguments = context.arguments if isinstance(context.arguments, dict) else {} + + if function_name == "execute_code" and "code" in arguments: + print(f"\n{_YELLOW}{'─' * 60}") + print("▶ execute_code") + print(f"{'─' * 60}{_RESET}") + print(arguments["code"]) + print(f"{_YELLOW}{'─' * 60}{_RESET}") + else: + pairs = ", ".join(f"{name}={value!r}" for name, value in arguments.items()) + print(f"\n{_YELLOW}▶ {function_name}({pairs}){_RESET}") + + start = time.perf_counter() + await call_next() + elapsed = time.perf_counter() - start + + result = context.result + if function_name == "execute_code" and isinstance(result, list): + for output in result: + if output.type == "text" and output.text: + print(f"{_GREEN}stdout:\n{output.text}{_RESET}") + elif output.type == "error" and output.error_details: + print(f"{_YELLOW}stderr:\n{output.error_details}{_RESET}") + else: + print(f"{_YELLOW}◀ {function_name} → {result!r}{_RESET}") + + print(f"{_DIM} ({elapsed:.4f}s){_RESET}") + + +@tool(approval_mode="never_require") +def compute( + operation: Annotated[ + Literal["add", "subtract", "multiply", "divide"], + "Math operation: add, subtract, multiply, or divide.", + ], + a: Annotated[float, "First numeric operand."], + b: Annotated[float, "Second numeric operand."], +) -> float: + """Perform a math operation for sandboxed code.""" + operations = { + "add": a + b, + "subtract": a - b, + "multiply": a * b, + "divide": a / b if b else float("inf"), + } + return operations[operation] + + +@tool(approval_mode="never_require") +async def fetch_data( + table: Annotated[str, "Name of the simulated table to query."], +) -> list[dict[str, Any]]: + """Fetch records from a named table.""" + await asyncio.sleep(0.5) + data: dict[str, list[dict[str, Any]]] = { + "users": [ + {"id": 1, "name": "Alice", "role": "admin"}, + {"id": 2, "name": "Bob", "role": "user"}, + {"id": 3, "name": "Charlie", "role": "admin"}, + ], + "products": [ + {"id": 101, "name": "Widget", "price": 9.99}, + {"id": 102, "name": "Gadget", "price": 19.99}, + ], + } + return data.get(table, []) + + +async def main() -> None: + """Run the provider-owned Monty CodeAct sample.""" + # 1. Create the Monty-backed provider and register sandbox tools on it. + codeact = MontyCodeActProvider( + tools=[compute, fetch_data], + approval_mode="never_require", + ) + + # 2. Create the client and the agent. + agent = Agent( + client=FoundryChatClient( + project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"], + model=os.environ["FOUNDRY_MODEL"], + credential=AzureCliCredential(), + ), + name="MontyCodeActProviderAgent", + instructions="You are a helpful assistant.", + context_providers=[codeact], + middleware=[log_function_calls], + ) + + # 3. Run a request that should use execute_code plus provider-owned tools. + query = ( + "Fetch all users, find admins, multiply 7*(3*2), and print the users, " + "admins, and multiplication result. Use a single execute_code call. " + "You may call the registered tools directly as typed async functions " + "(`await compute(operation='multiply', a=7, b=6)`) or via " + "`call_tool('compute', ...)`." + ) + print(f"{_CYAN}{'=' * 60}") + print("Monty CodeAct provider sample") + print(f"{'=' * 60}{_RESET}") + print(f"{_CYAN}User: {query}{_RESET}") + result = await agent.run(query) + print(f"{_CYAN}Agent: {result.text}{_RESET}") + + +""" +Sample output (shape only): + +============================================================ +Monty CodeAct provider sample +============================================================ +User: Fetch all users, find admins, multiply 7*(3*2), ... + +──────────────────────────────────────────────────────────── +▶ execute_code +──────────────────────────────────────────────────────────── +users = await fetch_data(table="users") +admins = [u for u in users if u["role"] == "admin"] +result = await compute(operation="multiply", a=7, b=6) +print("Users:", users) +print("Admins:", admins) +print("7 * 6 =", result) +──────────────────────────────────────────────────────────── +stdout: +Users: [...] +Admins: [...] +7 * 6 = 42.0 + (0.5xxx s) +Agent: ... +""" + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/02-agents/tools/monty_code_interpreter/README.md b/python/samples/02-agents/tools/monty_code_interpreter/README.md new file mode 100644 index 0000000000..d2797077d6 --- /dev/null +++ b/python/samples/02-agents/tools/monty_code_interpreter/README.md @@ -0,0 +1,40 @@ +# Monty local code interpreter + +Demonstrates the standalone [Monty](https://github.com/pydantic/monty) +`MontyExecuteCodeTool` — a sandboxed local code interpreter that the agent can +invoke directly. Two patterns are shown: + +| File | Pattern | +|------|---------| +| [`monty_code_interpreter.py`](monty_code_interpreter.py) | **Standalone tool** — `MontyExecuteCodeTool` is added to the agent tool list and self-describes its sandbox tools, so no extra agent instructions are needed. Best for quick prototyping. | +| [`monty_code_interpreter_manual_wiring.py`](monty_code_interpreter_manual_wiring.py) | **Manual static wiring** — sandbox tools and CodeAct instructions are built once and passed to the `Agent` constructor alongside a direct-only tool (`send_email`). Best when the tool set is fixed for the agent's lifetime. | + +For the recommended provider-driven pattern (with dynamic tool / capability +management), see +[`../../context_providers/code_act/`](../../context_providers/code_act/). + +## Installation + +```bash +pip install agent-framework agent-framework-monty --pre +``` + +> `agent-framework-monty` is an alpha package and is not yet part of +> `agent-framework[all]`. The `--pre` flag is required. +> +> Monty is cross-platform and has no hypervisor/WASM backend dependency. +> Inside the sandbox, OS / filesystem / network calls are blocked +> (`PermissionError`); registered host tools retain full Python access. + +## Prerequisites + +- An Azure AI Foundry project endpoint (`FOUNDRY_PROJECT_ENDPOINT`) +- A deployed model (`FOUNDRY_MODEL`) +- Azure CLI authenticated (`az login`) + +## Run + +```bash +python monty_code_interpreter.py +python monty_code_interpreter_manual_wiring.py +``` diff --git a/python/samples/02-agents/tools/monty_code_interpreter/monty_code_interpreter.py b/python/samples/02-agents/tools/monty_code_interpreter/monty_code_interpreter.py new file mode 100644 index 0000000000..dc9016b915 --- /dev/null +++ b/python/samples/02-agents/tools/monty_code_interpreter/monty_code_interpreter.py @@ -0,0 +1,114 @@ +# Copyright (c) Microsoft. All rights reserved. + +from __future__ import annotations + +import asyncio +import os +from typing import Annotated, Any, Literal + +from agent_framework import Agent, tool +from agent_framework.foundry import FoundryChatClient +from agent_framework_monty import MontyExecuteCodeTool +from azure.identity import AzureCliCredential +from dotenv import load_dotenv + +"""This sample demonstrates the standalone Monty execute_code tool. + +The sample adds `MontyExecuteCodeTool` directly to the agent. The tool's own +description advertises the registered sandbox tools (as typed async functions +and via `call_tool(...)`) plus the Monty DSL, so no extra CodeAct-specific +agent instructions are required. + +Note: `agent-framework-monty` is an alpha package and is not yet part of +`agent-framework[all]`. Install it explicitly with: + + pip install agent-framework agent-framework-monty --pre +""" + +load_dotenv() + + +@tool(approval_mode="never_require") +def compute( + operation: Annotated[ + Literal["add", "subtract", "multiply", "divide"], + "Math operation: add, subtract, multiply, or divide.", + ], + a: Annotated[float, "First numeric operand."], + b: Annotated[float, "Second numeric operand."], +) -> float: + """Perform a math operation used by sandboxed code.""" + operations = { + "add": a + b, + "subtract": a - b, + "multiply": a * b, + "divide": a / b if b else float("inf"), + } + return operations[operation] + + +@tool(approval_mode="never_require") +def fetch_data( + table: Annotated[str, "Name of the simulated table to query."], +) -> list[dict[str, Any]]: + """Fetch simulated records from a named table.""" + data: dict[str, list[dict[str, Any]]] = { + "users": [ + {"id": 1, "name": "Alice", "role": "admin"}, + {"id": 2, "name": "Bob", "role": "user"}, + {"id": 3, "name": "Charlie", "role": "admin"}, + ], + "products": [ + {"id": 101, "name": "Widget", "price": 9.99}, + {"id": 102, "name": "Gadget", "price": 19.99}, + ], + } + return data.get(table, []) + + +async def main() -> None: + """Run the standalone Monty execute_code sample.""" + # 1. Create the packaged execute_code tool and register sandbox tools on it. + execute_code = MontyExecuteCodeTool( + tools=[compute, fetch_data], + approval_mode="never_require", + ) + + # 2. Create the client and the agent. + agent = Agent( + client=FoundryChatClient( + project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"], + model=os.environ["FOUNDRY_MODEL"], + credential=AzureCliCredential(), + ), + name="MontyExecuteCodeToolAgent", + instructions="You are a helpful assistant.", + tools=execute_code, + ) + + # 3. Run one request through the direct-tool surface. + print("=" * 60) + print("Monty execute_code tool sample") + print("=" * 60) + query = ( + "Fetch all users, find admins, multiply 6*7, and print the users, admins, " + "and multiplication result. Use one execute_code call." + ) + print(f"User: {query}") + result = await agent.run(query) + print(f"Agent: {result.text}") + + +""" +Sample output (shape only): + +============================================================ +Monty execute_code tool sample +============================================================ +User: Fetch all users, find admins, multiply 6*7, ... +Agent: ... +""" + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/02-agents/tools/monty_code_interpreter/monty_code_interpreter_manual_wiring.py b/python/samples/02-agents/tools/monty_code_interpreter/monty_code_interpreter_manual_wiring.py new file mode 100644 index 0000000000..104a256a25 --- /dev/null +++ b/python/samples/02-agents/tools/monty_code_interpreter/monty_code_interpreter_manual_wiring.py @@ -0,0 +1,136 @@ +# Copyright (c) Microsoft. All rights reserved. + +from __future__ import annotations + +import asyncio +import os +from typing import Annotated, Any, Literal + +from agent_framework import Agent, tool +from agent_framework.foundry import FoundryChatClient +from agent_framework_monty import MontyExecuteCodeTool +from azure.identity import AzureCliCredential +from dotenv import load_dotenv + +"""This sample demonstrates manual static wiring of Monty CodeAct without a provider. + +Instead of using `MontyCodeActProvider` with `context_providers=`, this sample +creates a `MontyExecuteCodeTool` directly, extracts its CodeAct instructions +once, and passes both to the `Agent` constructor at build time. + +This avoids the per-run provider lifecycle (`before_run` / `after_run`) and is +well-suited when the tool registry is fixed for the agent's lifetime. The +tradeoff is that dynamic tool changes between runs are not supported - any +mutations to the tool would not update the agent's instructions automatically. + +Note: `agent-framework-monty` is an alpha package and is not yet part of +`agent-framework[all]`. Install it explicitly with: + + pip install agent-framework agent-framework-monty --pre +""" + +load_dotenv() + + +@tool(approval_mode="never_require") +def compute( + operation: Annotated[ + Literal["add", "subtract", "multiply", "divide"], + "Math operation: add, subtract, multiply, or divide.", + ], + a: Annotated[float, "First numeric operand."], + b: Annotated[float, "Second numeric operand."], +) -> float: + """Perform a math operation used by sandboxed code.""" + operations = { + "add": a + b, + "subtract": a - b, + "multiply": a * b, + "divide": a / b if b else float("inf"), + } + return operations[operation] + + +@tool(approval_mode="never_require") +def fetch_data( + table: Annotated[str, "Name of the simulated table to query."], +) -> list[dict[str, Any]]: + """Fetch simulated records from a named table.""" + data: dict[str, list[dict[str, Any]]] = { + "users": [ + {"id": 1, "name": "Alice", "role": "admin"}, + {"id": 2, "name": "Bob", "role": "user"}, + {"id": 3, "name": "Charlie", "role": "admin"}, + ], + "products": [ + {"id": 101, "name": "Widget", "price": 9.99}, + {"id": 102, "name": "Gadget", "price": 19.99}, + ], + } + return data.get(table, []) + + +@tool(approval_mode="never_require") +def send_email( + to: Annotated[str, "Recipient email address."], + subject: Annotated[str, "Email subject line."], + body: Annotated[str, "Email body text."], +) -> str: + """Simulate sending an email (direct-only tool, not available inside the sandbox).""" + return f"Email sent to {to}: {subject}" + + +async def main() -> None: + """Run the manual static-wiring Monty sample.""" + # 1. Create the execute_code tool and register sandbox tools on it. + execute_code = MontyExecuteCodeTool( + tools=[compute, fetch_data], + approval_mode="never_require", + ) + + # 2. Build CodeAct instructions once. Setting tools_visible_to_model=False + # tells the instructions builder that sandbox tools are not in the agent's + # direct tool list, so the model must call them inside execute_code. + codeact_instructions = execute_code.build_instructions(tools_visible_to_model=False) + + # 3. Create the client and the agent with everything wired at construction time. + # - send_email is a direct-only tool (not available inside the sandbox). + # - execute_code carries sandbox tools (compute, fetch_data) for Monty. + agent = Agent( + client=FoundryChatClient( + project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"], + model=os.environ["FOUNDRY_MODEL"], + credential=AzureCliCredential(), + ), + name="MontyManualWiringAgent", + instructions=f"You are a helpful assistant.\n\n{codeact_instructions}", + tools=[send_email, execute_code], + ) + + # 4. Run a request that exercises both the sandbox and the direct tool. + print("=" * 60) + print("Manual static-wiring Monty CodeAct sample") + print("=" * 60) + query = ( + "Fetch all users, find admins, multiply 6*7, and print the users, admins, " + "and multiplication result. Use one execute_code call. " + "Then send an email to admin@example.com summarising the results." + ) + print(f"User: {query}") + result = await agent.run(query) + print(f"Agent: {result.text}") + + +""" +Sample output (shape only): + +============================================================ +Manual static-wiring Monty CodeAct sample +============================================================ +User: Fetch all users, find admins, multiply 6*7, ... +Agent: ... +""" + + +if __name__ == "__main__": + asyncio.run(main()) diff --git a/python/samples/04-hosting/foundry-hosted-agents/README.md b/python/samples/04-hosting/foundry-hosted-agents/README.md index bb55657564..ebb0741892 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/README.md @@ -18,7 +18,8 @@ This directory contains samples that demonstrate how to use hosted [Agent Framew | 8 | [Azure AI Search RAG](responses/08_azure_search_rag/) | An agent with Retrieval Augmented Generation (RAG) capabilities backed by Azure AI Search, grounding answers in documents indexed in a pre-provisioned search index. | | 9 | [Foundry Skills](responses/09_foundry_skills/) | An agent that uploads `SKILL.md` files to the Foundry Skills REST API and downloads them at startup, decoupling tone/policy guidelines from agent code. | | 10 | [Foundry Memory](responses/10_foundry_memory/) | An agent with persistent semantic memory backed by an Azure AI Foundry Memory Store, using `FoundryMemoryProvider` to remember user facts across sessions. | -| 11 | [Using deployed agent](responses/using_deployed_agent.py) | A sample demonstrating how to invoke an agent that has already been deployed to Foundry, showing how to interact with a hosted agent in code. | +| 11 | [Monty CodeAct](responses/11_monty_codeact/) | An agent with a Monty-backed CodeAct context provider, exposing a single `execute_code` tool that runs Python in a [pydantic-monty](https://github.com/pydantic/monty) interpreter and invokes typed host tools (`compute`, `fetch_data`) from inside the sandbox. Uses the alpha `agent-framework-monty` package. | +| 12 | [Using deployed agent](responses/using_deployed_agent.py) | A sample demonstrating how to invoke an agent that has already been deployed to Foundry, showing how to interact with a hosted agent in code. | ### Invocations API diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/Dockerfile b/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/Dockerfile new file mode 100644 index 0000000000..514bc9a0d0 --- /dev/null +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/Dockerfile @@ -0,0 +1,25 @@ +FROM python:3.12-slim + +# Bring in the `uv` binary from a pinned Astral image. Update this tag intentionally; +# `latest` would make rebuilds non-deterministic. +COPY --from=ghcr.io/astral-sh/uv:0.11.6 /uv /uvx /usr/local/bin/ + +ENV UV_LINK_MODE=copy \ + UV_COMPILE_BYTECODE=1 \ + UV_PROJECT_ENVIRONMENT=/app/.venv \ + PATH="/app/.venv/bin:${PATH}" + +WORKDIR /app + +# Sync dependencies first to maximize Docker layer caching. +COPY pyproject.toml ./ +RUN uv sync --no-install-project --no-cache + +# Now copy the rest of the agent and finalize the environment. +COPY . ./ +RUN uv sync --no-cache + +EXPOSE 8088 + +CMD ["uv", "run", "--no-sync", "python", "main.py"] + diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/README.md new file mode 100644 index 0000000000..e5b0ee90fc --- /dev/null +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/README.md @@ -0,0 +1,116 @@ +# What this sample demonstrates + +An [Agent Framework](https://github.com/microsoft/agent-framework) agent with a +**Monty-backed CodeAct context provider** hosted using the **Responses protocol**. +The model receives one tool (`execute_code`) and runs Python inside a +[Monty](https://github.com/pydantic/monty) interpreter; the registered host +tools (`compute`, `fetch_data`) are only reachable from inside the sandbox via +typed `await compute(...)` calls or the generic `call_tool(...)` fallback. + +> [!NOTE] +> `agent-framework-monty` is an **alpha** package, so the `pyproject.toml` +> sets `[tool.uv] prerelease = "allow"` to let `uv sync` pick up the +> `1.0.0a*` release from PyPI. + +## How It Works + +### Model Integration + +The agent uses `FoundryChatClient` to create a Responses client from the project +endpoint and the model deployment. The agent supports both streaming (SSE +events) and non-streaming (JSON) response modes. + +See [main.py](main.py) for the full implementation. + +### CodeAct context provider + +`MontyCodeActProvider` is added to the agent via `context_providers=[...]`. On +every run it injects: + +- An `execute_code` tool that runs Python in the Monty interpreter. +- Dynamic CodeAct instructions describing the available host tools and DSL. + +The host tools (`compute`, `fetch_data`) are **not** exposed as direct agent +tools — the model can only call them from inside `execute_code`, either as +typed async functions (`await compute(operation="multiply", a=6, b=7)`) or via +the generic `call_tool("compute", operation="multiply", a=6, b=7)` fallback. +Code is type-checked against the host tool signatures using +[ty](https://docs.astral.sh/ty/) before any tool runs. + +OS-level access (filesystem, network, subprocess) is blocked inside the +sandbox; the registered host tools retain full Python access. + +### Observability + +Agent Framework's [native OpenTelemetry instrumentation](https://learn.microsoft.com/en-us/agent-framework/agents/observability?pivots=programming-language-python) is enabled by setting these env vars in `agent.yaml` / `agent.manifest.yaml`: + +- `ENABLE_INSTRUMENTATION=true` — turns on the framework's span/metric/log emitters. +- `ENABLE_SENSITIVE_DATA=true` — includes prompts, tool inputs, tool outputs, and completions in telemetry. **Dev/test only.** + +`main.py` wires Azure Monitor at startup: + +1. Reads `APPLICATIONINSIGHTS_CONNECTION_STRING` (Foundry hosting injects this automatically for the project's attached Application Insights resource; set it yourself when running locally). +2. Calls `azure.monitor.opentelemetry.configure_azure_monitor(connection_string=...)` to register Azure Monitor exporters with the global OTel tracer/meter/logger providers. +3. Calls `agent_framework.observability.enable_instrumentation()` so Agent Framework emits its `invoke_agent`, `chat`, `execute_tool`, and `execute_code` spans on those providers. + +Trace linking happens automatically: the Foundry hosting layer's incoming `Responses` request becomes the **parent span**, and every framework / tool span (including the `execute_code` invocation that runs Monty) becomes a child via OpenTelemetry context propagation since both layers share the same global tracer provider. In Application Insights you can click any operation and see the full tree from inbound HTTP all the way down to individual `compute(...)` / `fetch_data(...)` calls inside the Monty sandbox. + +## Running the Agent Host + +This sample uses `pyproject.toml` + `uv sync` rather than the parent +README's `requirements.txt` flow. To run locally: + +1. Install dependencies into a local virtual environment: + + ```bash + uv sync + ``` + +2. Set the environment variables described in the + [parent README](../../README.md#running-the-agent-host-locally) (Foundry + project endpoint, model deployment, optional Application Insights), then + start the host: + + ```bash + uv run python main.py + ``` + +Refer to the parent README for the shared `azd` / Docker / invocation / +deployment guidance. + +## Interacting with the agent + +> Depending on how you run the agent host, you can invoke the agent using +> `curl` (`Invoke-WebRequest` in PowerShell) or `azd`. Please refer to the +> [parent README](../../README.md) for more details. Use this README for +> sample queries you can send to the agent. + +Send a POST request to the server with a JSON body containing an `"input"` +field. Try queries that benefit from combining Python with multiple tool calls: + +```bash +curl -X POST http://localhost:8088/responses \ + -H "Content-Type: application/json" \ + -d '{"input": "Fetch all users, find the admins, then multiply the count by 7. Use a single execute_code call."}' +``` + +```bash +curl -X POST http://localhost:8088/responses \ + -H "Content-Type: application/json" \ + -d '{"input": "Compute the total price for one of every product in the products table. Use execute_code."}' +``` + +The model should respond with one `execute_code` call whose code looks like: + +```python +users = await fetch_data(table="users") +admins = [u for u in users if u["role"] == "admin"] +result = await compute(operation="multiply", a=len(admins), b=7) +print(result) +``` + +## Deploying the Agent to Foundry + +To host the agent on Foundry, follow the instructions in the +[Deploying the Agent to Foundry](../../README.md#deploying-the-agent-to-foundry) +section of the README in the parent directory. diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/agent.manifest.yaml b/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/agent.manifest.yaml new file mode 100644 index 0000000000..b406d26219 --- /dev/null +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/agent.manifest.yaml @@ -0,0 +1,28 @@ +name: agent-framework-agent-monty-codeact-responses +description: > + An Agent Framework agent with a Monty-backed CodeAct context provider hosted by Foundry. +metadata: + tags: + - Agent Framework + - AI Agent Hosting + - Azure AI AgentServer + - Responses Protocol + - CodeAct + - Monty +template: + name: agent-framework-agent-monty-codeact-responses + kind: hosted + protocols: + - protocol: responses + version: 1.0.0 + environment_variables: + - name: AZURE_AI_MODEL_DEPLOYMENT_NAME + value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}" + - name: ENABLE_INSTRUMENTATION + value: "true" + - name: ENABLE_SENSITIVE_DATA + value: "true" +resources: + - kind: model + id: gpt-4.1-mini + name: AZURE_AI_MODEL_DEPLOYMENT_NAME diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/agent.yaml b/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/agent.yaml new file mode 100644 index 0000000000..8288362298 --- /dev/null +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/agent.yaml @@ -0,0 +1,15 @@ +kind: hosted +name: agent-framework-agent-monty-codeact-responses +protocols: + - protocol: responses + version: 1.0.0 +resources: + cpu: "0.25" + memory: 0.5Gi +environment_variables: + - name: AZURE_AI_MODEL_DEPLOYMENT_NAME + value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME} + - name: ENABLE_INSTRUMENTATION + value: "true" + - name: ENABLE_SENSITIVE_DATA + value: "true" diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/main.py b/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/main.py new file mode 100644 index 0000000000..de7629f0f6 --- /dev/null +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/main.py @@ -0,0 +1,136 @@ +# Copyright (c) Microsoft. All rights reserved. + +import logging +import os +from typing import Annotated, Any, Literal + +from agent_framework import Agent, tool +from agent_framework.foundry import FoundryChatClient +from agent_framework.observability import enable_instrumentation +from agent_framework_foundry_hosting import ResponsesHostServer +from agent_framework_monty import MontyCodeActProvider +from azure.identity import DefaultAzureCredential +from dotenv import load_dotenv +from pydantic import Field + +# Load environment variables from .env file (no-op when injected by Foundry). +load_dotenv() + +logger = logging.getLogger(__name__) + + +def _setup_telemetry() -> None: + """Wire Agent Framework spans to the Application Insights resource attached to the Foundry project. + + Foundry-hosted runtimes inject ``APPLICATIONINSIGHTS_CONNECTION_STRING`` automatically; + locally you can set it yourself (see README). When the connection string is present we + configure Azure Monitor OTel exporters once and then flip the framework's instrumentation + flag so it emits ``invoke_agent`` / ``chat`` / ``execute_tool`` spans. The hosting layer's + incoming-request span becomes the parent automatically via OpenTelemetry context + propagation when both layers share the same global tracer provider. + """ + connection_string = os.environ.get("APPLICATIONINSIGHTS_CONNECTION_STRING") + if not connection_string: + logger.info( + "APPLICATIONINSIGHTS_CONNECTION_STRING is not set; Agent Framework spans will not " + "be exported to Azure Monitor. Set the env var to enable telemetry." + ) + return + + try: + from azure.monitor.opentelemetry import configure_azure_monitor + except ImportError: + logger.warning( + "azure-monitor-opentelemetry is not installed; skipping Azure Monitor setup. " + "Install it to export telemetry." + ) + return + + # Configure the global OTel providers (tracer/meter/logger) to export to Azure Monitor. + # Idempotent for repeated imports because we only call it from this entry point. + configure_azure_monitor(connection_string=connection_string) + # Flip the Agent Framework instrumentation flag so its spans are actually emitted on + # the now-configured global providers. + enable_instrumentation() + logger.info("Azure Monitor + Agent Framework instrumentation enabled.") + + +@tool(approval_mode="never_require") +def compute( + operation: Annotated[ + Literal["add", "subtract", "multiply", "divide"], + Field(description="Math operation: add, subtract, multiply, or divide."), + ], + a: Annotated[float, Field(description="First numeric operand.")], + b: Annotated[float, Field(description="Second numeric operand.")], +) -> float: + """Perform a math operation used by sandboxed code.""" + operations = { + "add": a + b, + "subtract": a - b, + "multiply": a * b, + "divide": a / b if b else float("inf"), + } + return operations[operation] + + +@tool(approval_mode="never_require") +def fetch_data( + table: Annotated[str, Field(description="Name of the simulated table to query.")], +) -> list[dict[str, Any]]: + """Fetch simulated records from a named table.""" + data: dict[str, list[dict[str, Any]]] = { + "users": [ + {"id": 1, "name": "Alice", "role": "admin"}, + {"id": 2, "name": "Bob", "role": "user"}, + {"id": 3, "name": "Charlie", "role": "admin"}, + ], + "products": [ + {"id": 101, "name": "Widget", "price": 9.99}, + {"id": 102, "name": "Gadget", "price": 19.99}, + ], + } + return data.get(table, []) + + +def main() -> None: + """Host a Monty CodeAct agent over the Responses protocol.""" + # Set up telemetry BEFORE building the client/agent so the framework picks up + # the configured tracer provider when it lazily wires instrumentation. + _setup_telemetry() + + client = FoundryChatClient( + project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"], + model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"], + credential=DefaultAzureCredential(), + ) + + # MontyCodeActProvider injects a sandboxed `execute_code` tool into every + # agent run, plus dynamic instructions describing the registered host tools. + # The host tools are hidden from the model - they can only be invoked from + # inside the sandbox (`await compute(...)` or `call_tool(...)`). + codeact = MontyCodeActProvider( + tools=[compute, fetch_data], + approval_mode="never_require", + ) + + agent = Agent( + client=client, + instructions=( + "You are a friendly assistant. Use `execute_code` to combine " + "Python control flow with the provided host tools whenever the " + "task requires lookups, transformations, or computation." + ), + context_providers=[codeact], + # 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) + server.run() + + +if __name__ == "__main__": + main() diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/pyproject.toml b/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/pyproject.toml new file mode 100644 index 0000000000..4abc446619 --- /dev/null +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/11_monty_codeact/pyproject.toml @@ -0,0 +1,20 @@ +[project] +name = "agent-framework-agent-monty-codeact-responses" +version = "0.1.0" +description = "Foundry-hosted Agent Framework agent with a Monty-backed CodeAct context provider." +requires-python = ">=3.12,<3.14" +dependencies = [ + "agent-framework-foundry", + "agent-framework-foundry-hosting", + # agent-framework-monty is an alpha (1.0.0a*) release on PyPI. + "agent-framework-monty", + # Azure Monitor OpenTelemetry exporter; used to send agent telemetry to the + # Application Insights instance attached to the Foundry project. + "azure-monitor-opentelemetry", +] + +[tool.uv] +# `agent-framework-monty` is an alpha package; allow the prerelease resolver +# to pick up 1.0.0a* releases from PyPI. +prerelease = "allow" + diff --git a/python/uv.lock b/python/uv.lock index 5154479024..c3faa1a16c 100644 --- a/python/uv.lock +++ b/python/uv.lock @@ -50,6 +50,7 @@ members = [ "agent-framework-hyperlight", "agent-framework-lab", "agent-framework-mem0", + "agent-framework-monty", "agent-framework-ollama", "agent-framework-openai", "agent-framework-orchestrations", @@ -720,6 +721,21 @@ requires-dist = [ { name = "mem0ai", specifier = ">=1.0.0,<2" }, ] +[[package]] +name = "agent-framework-monty" +version = "1.0.0a260518" +source = { editable = "packages/monty" } +dependencies = [ + { name = "agent-framework-core", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" }, + { name = "pydantic-monty", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" }, +] + +[package.metadata] +requires-dist = [ + { name = "agent-framework-core", editable = "packages/core" }, + { name = "pydantic-monty", specifier = ">=0,<0.1" }, +] + [[package]] name = "agent-framework-ollama" version = "1.0.0b260514" @@ -5608,6 +5624,77 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/36/c7/cfc8e811f061c841d7990b0201912c3556bfeb99cdcb7ed24adc8d6f8704/pydantic_core-2.41.5-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:56121965f7a4dc965bff783d70b907ddf3d57f6eba29b6d2e5dabfaf07799c51", size = 2145302, upload-time = "2025-11-04T13:43:46.64Z" }, ] +[[package]] +name = "pydantic-monty" +version = "0.0.17" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "typing-extensions", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/f4/f8/431ba0b79d02922811392c4e3d283d6508f7052ceaa1936cc34878703ecc/pydantic_monty-0.0.17.tar.gz", hash = "sha256:9c4904a8fbc63282793f3afd2d180124494c7fc371783f365e5691c9586360af", size = 1007724, upload-time = "2026-04-22T20:13:48.915Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/5e/19/8105bc0b3acb42f6cb48a29669a5e21316bc05e3e9b6fab64cf94b483712/pydantic_monty-0.0.17-cp310-cp310-macosx_10_12_x86_64.whl", hash = "sha256:3c3b6c026d8a0437eeb4d6b2d908be75e2715e0555b9a13f076b7e9ba9bbae19", size = 7344730, upload-time = "2026-04-22T20:13:24.408Z" }, + { url = "https://files.pythonhosted.org/packages/6d/a2/7281cdb37481c4252292b63bebf737c87d0fd463f3174499608607de0907/pydantic_monty-0.0.17-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:c80b4d34437abd209c042f81f8ecea81a097022fb9b01431ab859b877edfbc4d", size = 7334937, upload-time = "2026-04-22T20:15:06.923Z" }, + { url = "https://files.pythonhosted.org/packages/a5/68/0bf7c0c627a56d8653b42888a3c1fc33cd33d2532ec456d9358275d7c792/pydantic_monty-0.0.17-cp310-cp310-manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:beecc1f7e5b10db40d7b2b24a68166a36514289a2402bfef370a7984e90a2ab8", size = 7864543, upload-time = "2026-04-22T20:14:46.273Z" }, + { url = "https://files.pythonhosted.org/packages/09/9b/5a6f006541fd3bdc64b6dfbbaeabfb2244c89a22d7077a1fc92ec497c03e/pydantic_monty-0.0.17-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:64ea7babdcc9fba93089fa52589b6d0549f755e37500f6cf4aeaeb8e56328a3e", size = 7138764, upload-time = "2026-04-22T20:15:30.516Z" }, + { url = "https://files.pythonhosted.org/packages/01/cc/59cca979bd427d166df8c827fba9e794c4a5c08943e225a22adf9854a78f/pydantic_monty-0.0.17-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:a7fe77a191205becb622eaecb075e8bcbbbe4dac20a916d9c58ce6d59a22a8da", size = 7444006, upload-time = "2026-04-22T20:15:23.386Z" }, + { url = "https://files.pythonhosted.org/packages/1f/c5/d027170fb33fcbc038febb76dfd2d9047f5194a250ea608e3ed8e5ec28d4/pydantic_monty-0.0.17-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:2cdbefc180cc83c8b8415aaf95b9099bb2cb15261f40ebe2c92f13e7d52439a4", size = 7967564, upload-time = "2026-04-22T20:14:57.315Z" }, + { url = "https://files.pythonhosted.org/packages/3e/01/ac0d4bc1ff00acfac14b7cb2ee322d08778c206cd57f43da8206a2f6ce78/pydantic_monty-0.0.17-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:575ce5aa31db18bbbf6275f00e9b0c005ca393bfb73a2f306a577ad490ec2d98", size = 8199021, upload-time = "2026-04-22T20:15:14.488Z" }, + { url = "https://files.pythonhosted.org/packages/51/85/8d0c6e5f127da9ebc0fcda6e411592d12b7606347d67aecd4363df5eed6b/pydantic_monty-0.0.17-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e252ec54fc4728406045f7be36ca45dbea8e6856df9c6154b1b9821b8952dfa2", size = 7769814, upload-time = "2026-04-22T20:14:55.197Z" }, + { url = "https://files.pythonhosted.org/packages/ac/cc/cb4d1b14b039eab00b33a7274f15f81739c3f272e2dfbeb8fb13c6b0c85d/pydantic_monty-0.0.17-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:fba71e5cb49f15a1446ecee142c8cc11f4bd6df4fcb4926465c83181474b2fd4", size = 7317432, upload-time = "2026-04-22T20:14:19.993Z" }, + { url = "https://files.pythonhosted.org/packages/c8/16/737c7a023abbcb21848eb4d58f7167d9f4f8cdc46858ce8ed835cc2c137c/pydantic_monty-0.0.17-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:69136647abd56f804987834e37573adcc5c3b3d05013b8b3a2939f44b3bd5199", size = 7767816, upload-time = "2026-04-22T20:13:40.002Z" }, + { url = "https://files.pythonhosted.org/packages/dc/9f/5302b784f882ae8a8396f29f8c5ab4c16524c173a3d777b94af33858fdf2/pydantic_monty-0.0.17-cp310-cp310-win32.whl", hash = "sha256:d5b3beb6169b59adea10fdefb1e54bfa9a66165404891dfb6fcf16f7749cda3b", size = 7230648, upload-time = "2026-04-22T20:14:27.03Z" }, + { url = "https://files.pythonhosted.org/packages/1c/27/8c219f619dad466ec25db365acf88e2a50450dd862e0daff0eb281b6176b/pydantic_monty-0.0.17-cp310-cp310-win_amd64.whl", hash = "sha256:50ed9561b6dd1a1863d4cac81e4eaca64cb10ab541aaab92fcb5996739bb8e7f", size = 8075073, upload-time = "2026-04-22T20:14:17.073Z" }, + { url = "https://files.pythonhosted.org/packages/e7/42/ca8e42d9f3318f5c454cf8b168d814ec97c6f2afc38756d4b1b806184f6d/pydantic_monty-0.0.17-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:af890d691f6055491a4e643dd5bf09e07bd7a20ad70038531aada6415ab8794a", size = 7344138, upload-time = "2026-04-22T20:13:29.155Z" }, + { url = "https://files.pythonhosted.org/packages/56/c8/cfaf0a56087301d4e88f72cf54ea45a7eebc09c021c85b8864447f1e3755/pydantic_monty-0.0.17-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:2f38a69858dfdd2c9474156616d05e25a288e2080aee24152fa40c19ad425f0e", size = 7334903, upload-time = "2026-04-22T20:14:31.489Z" }, + { url = "https://files.pythonhosted.org/packages/51/77/a751a6f73f854aa85fed94cfa5ecab21d7bf218c9fa03c96f9edf470cc4e/pydantic_monty-0.0.17-cp311-cp311-manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:bb88264e291cee56770a775f57125538c4713c6d362e89ee63bff506f650a0df", size = 7864258, upload-time = "2026-04-22T20:13:15.594Z" }, + { url = "https://files.pythonhosted.org/packages/0a/fe/2eb51eb37e9f712cada64fa8d7df4b63b1f5fc635290147ab158ff0e1ef1/pydantic_monty-0.0.17-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:54c317611454aba8be7ca96aeeea9429f4702a5c4ba89812bea82bed0d8e34fd", size = 7138153, upload-time = "2026-04-22T20:14:22.255Z" }, + { url = "https://files.pythonhosted.org/packages/bb/15/835b10cdec3b96b089eef9899df6850b7f84a10225c491698b0ecf8e532a/pydantic_monty-0.0.17-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:9563b5b4933f0f08c0e66ec66aaa4f43f2388bcc04b984e58aab2146dacd3829", size = 7443572, upload-time = "2026-04-22T20:13:17.951Z" }, + { url = "https://files.pythonhosted.org/packages/16/92/aca140923fad8a2821a135cfeaa2fbb3321063bbadaa760424a016bb1ac6/pydantic_monty-0.0.17-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:35f267a501bc1910178a1515fdd3dd927273fbb44e44b8718cb3b33aee79f41b", size = 7967178, upload-time = "2026-04-22T20:14:06.032Z" }, + { url = "https://files.pythonhosted.org/packages/d7/ca/7c4ff1e3fe2e82a4745decfca67b54a7a61cd306875e32d8e41c5192c69e/pydantic_monty-0.0.17-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:35b000c52755f25f322ea7c4d079f09aa60635ffe24a6463899e423066a41bf3", size = 8198241, upload-time = "2026-04-22T20:15:21.2Z" }, + { url = "https://files.pythonhosted.org/packages/30/0b/702db7b753b96ebc6713e7cbdfaecdb471df3e3cb0f0f6e828620a743b78/pydantic_monty-0.0.17-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:61b517776ad13aa4580b1dd89188b18296ceeaf88256423563bbc99e804fd83f", size = 7768859, upload-time = "2026-04-22T20:13:20.044Z" }, + { url = "https://files.pythonhosted.org/packages/29/9c/8d16e0cc0c36d1444f25d57da68dd22216bf0961c457a482429cec32141b/pydantic_monty-0.0.17-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:5da5362ef25665a23a3b13024497719f65cafa61d696cac76429f84701bee2e2", size = 7316674, upload-time = "2026-04-22T20:14:52.579Z" }, + { url = "https://files.pythonhosted.org/packages/6f/4d/d47ae703d402e45475333c4bf11b117c8068305f00c1363dbaea13d0fd09/pydantic_monty-0.0.17-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:7e655b6ddd552c02b751f1d57fc291fbd5654ff8b166a8bd634857879160d0b7", size = 7767515, upload-time = "2026-04-22T20:15:16.539Z" }, + { url = "https://files.pythonhosted.org/packages/99/9b/e17fb50d0df5cf9908f8fffa25c5909ed0eb92ca102ded06f7a6d6133e78/pydantic_monty-0.0.17-cp311-cp311-win32.whl", hash = "sha256:ea8b3ae8c42d572cefad841d3bda63cc458d9de2361cb9172914250e6dbe2c75", size = 7230347, upload-time = "2026-04-22T20:14:08.083Z" }, + { url = "https://files.pythonhosted.org/packages/5e/82/d3119f59652d04bcf69d671ddbd38464d5775fbc738a258d3c8f7800e29d/pydantic_monty-0.0.17-cp311-cp311-win_amd64.whl", hash = "sha256:3293c2f7524bfc7c3d8c794f1c1dc1eb4cf9c65a5e222061e2218ced85f3f6df", size = 8074183, upload-time = "2026-04-22T20:14:50.42Z" }, + { url = "https://files.pythonhosted.org/packages/d1/31/95827babdb35149f076c5d191b6b1e7a7c58f4bc72432f905e02e4e3231e/pydantic_monty-0.0.17-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:27c2254fa7a7b05e969f79578889230d293c62e0b1ee28371ec4f3c54b14426a", size = 7342248, upload-time = "2026-04-22T20:15:18.775Z" }, + { url = "https://files.pythonhosted.org/packages/cb/67/ca9cfc07cd445d22def53e9db86912f9ae3e11ef772ce41c2ff41a47eac5/pydantic_monty-0.0.17-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:445cc471ce6f5a88ef06741b7ebc7002a2253d182f55a2f47094d4adedaaf497", size = 7311255, upload-time = "2026-04-22T20:15:27.913Z" }, + { url = "https://files.pythonhosted.org/packages/df/96/abc9c4972d91a9673435b84e12b99d038e42d1f99648fc9e5f242e09d00e/pydantic_monty-0.0.17-cp312-cp312-manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:39121038405911f59da7bf61164251f59bad3fb1b0cd28f43c42c3949eee2c8a", size = 7868109, upload-time = "2026-04-22T20:15:04.779Z" }, + { url = "https://files.pythonhosted.org/packages/75/82/9e4d55529bb99d882b9277a721762537a8bc1345ab1d052bb614a88bd15b/pydantic_monty-0.0.17-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:dafc8ffe57c257002f623afdb7d0e41f73de850179ebd90b42611e4f2b6f9884", size = 7139709, upload-time = "2026-04-22T20:15:25.386Z" }, + { url = "https://files.pythonhosted.org/packages/96/97/f1af6acefb7bb38d73934d6853998bbd327de7418b811372519080d9fd84/pydantic_monty-0.0.17-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:ea00838ef8f37dcd8085defcbdfe89fdd05297a6533f1d3f4cad857d13cedc7b", size = 7450444, upload-time = "2026-04-22T20:13:37.974Z" }, + { url = "https://files.pythonhosted.org/packages/1d/91/af92ef409e1c065345cf1451bbcf19e00f70a250b8372ec65143ca9a9238/pydantic_monty-0.0.17-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:683d18089acf14d0de293245b9e37c7f0ec64e6d266f6773144211931aa3ec97", size = 7967525, upload-time = "2026-04-22T20:13:42.674Z" }, + { url = "https://files.pythonhosted.org/packages/7b/1f/23ecd6e268ef24ce6b0fe4a1e76a314990d2e923ac5791e29d657418243d/pydantic_monty-0.0.17-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:c1829993dd50cf497cbed66ea9f6c8ff7d157d22592a05c7399f92fb8a549e3c", size = 8199124, upload-time = "2026-04-22T20:15:00.02Z" }, + { url = "https://files.pythonhosted.org/packages/42/2a/36b694ea0c7e202250a81a57faf00f218738da6c5d070c752f2d81cd34ce/pydantic_monty-0.0.17-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8a7869e3f41a54cc588096c52a8a4de25ecd81e75c867ea4164b14ea1ae1a57f", size = 7739623, upload-time = "2026-04-22T20:14:37.57Z" }, + { url = "https://files.pythonhosted.org/packages/98/e5/090357d7bc0f0751d1afbb71330695fa26554699c88ba56ecaad91657088/pydantic_monty-0.0.17-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:f9c17663e2c6f07aec5bc54cd7e39a9e20f250a97a9081e1b2b932eb00d0afc5", size = 7317755, upload-time = "2026-04-22T20:14:48.367Z" }, + { url = "https://files.pythonhosted.org/packages/15/63/67200070cf33325ecfda81d4aee3bf312250ce80bd73058103e04e0f3587/pydantic_monty-0.0.17-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:5d2cf98afe2fb124f6ade91d9663d54277478cad417164f83df1854a41ef450c", size = 7769158, upload-time = "2026-04-22T20:14:39.611Z" }, + { url = "https://files.pythonhosted.org/packages/58/ce/9ecfbc2f45406cfb247fafdea4f4a8412db3e559a22c4385eb15266ba2c1/pydantic_monty-0.0.17-cp312-cp312-win32.whl", hash = "sha256:b2185cc4effbbd6793eed4e0f0bcb6a3dbfbb3289ea4d47888708813f0a3dd47", size = 7227917, upload-time = "2026-04-22T20:14:15.122Z" }, + { url = "https://files.pythonhosted.org/packages/d3/80/9be3bef8273817ccc17da25c3ce4ff5d5d45e5629c17eacc90cdef073821/pydantic_monty-0.0.17-cp312-cp312-win_amd64.whl", hash = "sha256:7833daed757ec9b09b627cc3577a4a76b114c5148f779531d7cfdb1095bcf0a9", size = 8043469, upload-time = "2026-04-22T20:13:22.102Z" }, + { url = "https://files.pythonhosted.org/packages/b5/44/0e106b8b27eb93b66e4f3d279486464e05ba5ee31088848e58b5f506f879/pydantic_monty-0.0.17-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:e0cdac8c3c16477596bc96ee1cec4f2fbaccd089e2daa1e7b9f227cc89f97cb1", size = 7341507, upload-time = "2026-04-22T20:14:41.717Z" }, + { url = "https://files.pythonhosted.org/packages/e5/88/a0315fa08e62e2d1ef00c03d8202d7bef3f1f71543bebfb916fea265c0a2/pydantic_monty-0.0.17-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:37290d6a1c35aba5cfb8b490bb31c0d822e8ddca8f3ca9ea068e30930d80dd1e", size = 7311916, upload-time = "2026-04-22T20:13:34.022Z" }, + { url = "https://files.pythonhosted.org/packages/e7/e5/e4da6acb408594cbfbfb8dd3c0491b9b2ee54e9183e7ebc5f584baa07af9/pydantic_monty-0.0.17-cp313-cp313-manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:49f252b2fb918686d3e8f76cb30245e782d1560a7fa68dbc0f6940d83c12bd41", size = 7867465, upload-time = "2026-04-22T20:13:31.466Z" }, + { url = "https://files.pythonhosted.org/packages/58/d4/64c2f8eb708a743b0944ea8f71dfd51bc655285b4be28d55577dafbb29fa/pydantic_monty-0.0.17-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:2254d25c34463d67069f5f1567157bde9311654cd5371f8933b8ea9815bfa26a", size = 7139262, upload-time = "2026-04-22T20:14:10.715Z" }, + { url = "https://files.pythonhosted.org/packages/0c/67/5d766f9cd304e871a5dfe5f0a85eaa533538ef07e9b2858fdf9f37f83694/pydantic_monty-0.0.17-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f0688a1fa5dc045ac7b7e996d7269b94f74f116d7b1e352c7b5bb5ad53d4fe03", size = 7450119, upload-time = "2026-04-22T20:13:44.515Z" }, + { url = "https://files.pythonhosted.org/packages/33/98/fa16779021d93edb19807e87cdba56bbec6adfad21f10b41a212572ce513/pydantic_monty-0.0.17-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:7b35121ac555ed201405c69d531e4cb916da6984b8cd2e15c8a319117349faf6", size = 7967398, upload-time = "2026-04-22T20:13:55.576Z" }, + { url = "https://files.pythonhosted.org/packages/92/64/287a42720bc9e975ab5b52625aa9fc6bcef8298dd821022cc45c6ee1808d/pydantic_monty-0.0.17-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:7c97dc44af25d4392b474902fc40f78f09fe8f44ba791364670334fe12abc077", size = 8198835, upload-time = "2026-04-22T20:15:02.072Z" }, + { url = "https://files.pythonhosted.org/packages/97/37/03edb1fd582b79b2b462afc3fea5e1c8fea73afefc4870dc35fc3c7c492e/pydantic_monty-0.0.17-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:3ed2fb365ef9ca921de9a17786ecfa2efe06e65678e6ca57be51658a2a880f31", size = 7739241, upload-time = "2026-04-22T20:13:46.925Z" }, + { url = "https://files.pythonhosted.org/packages/11/0b/b765c9ca2ae27def1caa07345aba073ae1239fc2d9cca7a375f3dc2195f7/pydantic_monty-0.0.17-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:5bf9f07b38dd12747e3c95b169a5afb3e2e9107622e01e548246c84d19a69c99", size = 7316719, upload-time = "2026-04-22T20:14:13.058Z" }, + { url = "https://files.pythonhosted.org/packages/e4/3b/64fe872cd575ab5262e1ba2959554ead198c939cfaa425f7f8e9b1ad2694/pydantic_monty-0.0.17-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:a5e9bafd4b5acbc0a8e12ee8403a3ce37281c3b0fa5909d3f412bee76c69003c", size = 7769150, upload-time = "2026-04-22T20:13:57.784Z" }, + { url = "https://files.pythonhosted.org/packages/76/b4/b6a0bb41f39bac2e11e6a2fd42ca0886893fafa6344fb17c3f0a94e22e83/pydantic_monty-0.0.17-cp313-cp313-win32.whl", hash = "sha256:1c239ae3e610d3f39cd1609285209a4e2d046b465ac1bfed0d4374c615eed0fa", size = 7227705, upload-time = "2026-04-22T20:15:12.262Z" }, + { url = "https://files.pythonhosted.org/packages/86/e7/d8cd62f537f7ab17714ee19ea221a0e341dab407215376ab1c41d79794c9/pydantic_monty-0.0.17-cp313-cp313-win_amd64.whl", hash = "sha256:1886c3590b02f359ae991f1e76691064f167330eda4fbf22762127ce17d0eb48", size = 8043469, upload-time = "2026-04-22T20:14:24.86Z" }, + { url = "https://files.pythonhosted.org/packages/69/c0/8354baf835e1a04c4b9e11d253f82df7d625a9305e6a23a177fb895b1484/pydantic_monty-0.0.17-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:a166bd04d1996f0d144fbb5e1391cd1c0fbdacd4fa3b689dd48931388679fe98", size = 7341303, upload-time = "2026-04-22T20:14:35.653Z" }, + { url = "https://files.pythonhosted.org/packages/00/ac/d58221b5e17915421ca00bb08b805ac121b6accb194785d5422da4a2f5fc/pydantic_monty-0.0.17-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:d82f319e3fd79707a7b81bbb68596509d14ac73502d2f0daf4ab5d281efdfbdc", size = 7318912, upload-time = "2026-04-22T20:13:59.966Z" }, + { url = "https://files.pythonhosted.org/packages/81/3f/8eeb8f652f6cd6e06a737aa9f00de2949e37a669b31756bc51b6182457b4/pydantic_monty-0.0.17-cp314-cp314-manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:f38b9875f7ff56fe69538b60b2ecbdcbe2b8b7780407ceb05fe0ee1414bf8d19", size = 7867027, upload-time = "2026-04-22T20:13:51.426Z" }, + { url = "https://files.pythonhosted.org/packages/55/ba/ec6620c27c8b4cada6ce53378c52c245e238e50a20b968cafdc1b8573c4e/pydantic_monty-0.0.17-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:74a778bb5a4dcdbc85b3b9002f9a72a43fb6ffd88635bfdd502e8d3053008337", size = 7137542, upload-time = "2026-04-22T20:13:35.939Z" }, + { url = "https://files.pythonhosted.org/packages/41/78/5419785630511b54b15cfb094871bcb53ec9025ba8d91bd7ab5b22b6c98f/pydantic_monty-0.0.17-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:9e2ab074a65738e9c1b4be9a432e7ca1e9987a6706018dc7a5af6d4ce7cecdf3", size = 7450222, upload-time = "2026-04-22T20:13:53.378Z" }, + { url = "https://files.pythonhosted.org/packages/61/04/cec11fa96a47034da3c21af53e73f43d2270f5ce96cd710809859fe9c0b2/pydantic_monty-0.0.17-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:00fd1cd28b4200c9ccd02629868486b366af1bfe1f0584d4c9e513b7a941a868", size = 7967405, upload-time = "2026-04-22T20:14:03.826Z" }, + { url = "https://files.pythonhosted.org/packages/81/e3/f2be0fb975100b6936ca36a8410098f10fab3b26729c0b0d1de2fac59ff3/pydantic_monty-0.0.17-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:26ea6684555bfd00cbe9d2df3e73caada3d82200c168c63cc475197b55b88401", size = 8199028, upload-time = "2026-04-22T20:13:26.802Z" }, + { url = "https://files.pythonhosted.org/packages/2c/43/358bdaa9c50d21fe4a25a71d43ce9af2d6796616fa47aca84f807433564e/pydantic_monty-0.0.17-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f804a03a3bbd0cf0ade1d4ce11b50ca6858e9c4440b27c746faf1d3c0a272954", size = 7749903, upload-time = "2026-04-22T20:15:09.626Z" }, + { url = "https://files.pythonhosted.org/packages/9a/da/8bcd0a78abf13edceca36aaf5c180fad963e4c2e042fd7247b9e96048306/pydantic_monty-0.0.17-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:b5476e6c08b86b0bea554b97ce9b142aac1177447f2d3c5751864b27991fd1b1", size = 7312704, upload-time = "2026-04-22T20:14:33.668Z" }, + { url = "https://files.pythonhosted.org/packages/88/49/5de8bb7f8b82c3ebb8f2485e0b7a40055b072193039d95dcb5d35fcba72c/pydantic_monty-0.0.17-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:b5fcdcca45439844bee268686f37226dbf5803ec7a5945f5536c41419f151dac", size = 7768902, upload-time = "2026-04-22T20:14:29.389Z" }, + { url = "https://files.pythonhosted.org/packages/f0/7c/500a002f1a52f17c8b8a989875da3e1590c18ce95c89856aa967e2348a36/pydantic_monty-0.0.17-cp314-cp314-win32.whl", hash = "sha256:4dd3e6e80a415e7272f7a7583a4f8e045096653f6074e181117eb61fc8fe3b45", size = 7227049, upload-time = "2026-04-22T20:14:01.871Z" }, + { url = "https://files.pythonhosted.org/packages/5c/20/b8f552f2a863778f49ebb708f18aaf0bfb275480a48965786e06efacf1c4/pydantic_monty-0.0.17-cp314-cp314-win_amd64.whl", hash = "sha256:36a8090a628e8cf91df8f66c721a71050ac8f48473d4992b9afbd9585941a647", size = 8062999, upload-time = "2026-04-22T20:14:44.006Z" }, +] + [[package]] name = "pydantic-settings" version = "2.14.0"