Python: Add agent-framework-agentsandbox connector to integrate agent-sandbox

[aleks-stefanovic]

Motivation & Context

Agent Framework ships agent-framework-hyperlight as the reference CodeAct backend: LLM-emitted Python runs in an in-process WASM micro-VM — great for short, stateless computations, but it has no real filesystem, cannot pip install, and cannot run non-WASM libraries.

This PR adds a container-grade, persistent peer: agent-framework-agentsandbox, which runs the model's execute_code inside a Kubernetes Pod managed by the kubernetes-sigs/agent-sandbox controller. It targets the scenarios Hyperlight cannot cover — persistent filesystem and pip install across calls, real Linux libraries, optional gVisor/Kata isolation, warm-pool pre-warming, and running on infrastructure the team already operates, without shipping code or data to a hosted interpreter.

The connector plugs into the same extension points as Hyperlight (ContextProvider + FunctionTool) and keeps the same constructor surface (approval_mode, the execute_code input schema, Content return shape, CodeAct instruction injection), so switching backends is an import change.

Description & Review Guide

What are the major changes?

New package python/packages/agentsandbox/ (agent-framework-agentsandbox):

Path	What it is
agent_framework_agentsandbox/_provider.py	AgentSandboxCodeActProvider (ContextProvider) — injects the execute_code tool + CodeAct instructions on every run
agent_framework_agentsandbox/_execute_code_tool.py	AgentSandboxExecuteCodeTool (FunctionTool named execute_code) — owns the Pod lifecycle; native async via the agent-sandbox AsyncSandboxClient / AsyncSandbox; claims Pods from a SandboxWarmPool
agent_framework_agentsandbox/_instructions.py	CodeAct prompt + tool-description builders
tests/agentsandbox/test_agentsandbox_codeact.py	Unit tests (stubbed sandbox; no cluster required)
README.md, TESTING.md	Usage + full local end-to-end test guide

Plus:

• python/packages/core/agent_framework/agentsandbox/ — lazy-import shim so from agent_framework.agentsandbox import … works (same pattern as ollama / hyperlight).
• python/samples/02-agents/context_providers/agentsandbox_codeact/ — runnable demo using OllamaChatClient (no API key); a two-turn flow shows the Pod's filesystem persisting across execute_code calls.
• Workspace registration in python/pyproject.toml and a row in python/PACKAGE_STATUS.md (alpha).

How it compares to agent-framework-hyperlight:

	hyperlight	agentsandbox
Runtime	In-process WASM micro-VM	Kubernetes Pod
Startup	Microseconds	Seconds (sub-second with SandboxWarmPool)
State across calls	Snapshot/reset every call	Persistent — filesystem + pip install-ed packages
Isolation	VM-level, no Linux kernel	Container + optional gVisor / Kata
Pool / pre-warm	In-process registry	SandboxWarmPool controller
Network policy	allowed_domains ctor arg	Kubernetes NetworkPolicy

What is the impact of these changes?

Additive only — a new optional connector package plus a lazy namespace under core. No existing package behavior changes. Not a breaking change.

Dependency. The connector uses agent-sandbox's native async client (AsyncSandboxClient / AsyncSandbox) and warm-pool claim API (create_sandbox(warmpool=...)), first released in k8s-agent-sandbox 0.5.0. pyproject.toml depends on k8s-agent-sandbox[async]>=0.5.0,<1 (the [async] extra pulls in httpx and kubernetes_asyncio).

Testing. Verified end-to-end on a local Kubernetes cluster with a local Ollama model: the model emits execute_code, a Pod is claimed from a warm pool, the code runs inside it, and a file written by one execute_code call is read back by a later call (filesystem persistence), including pip install persistence. Static checks are green against current main: ruff, ruff format, pyright (strict, source), mypy, and the package unit tests. TESTING.md reproduces the full local run (kind + Ollama, no API keys).

Related Issue

Fixes #

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change.

[Copilot]

Pull request overview

Adds a new Python connector package, agent-framework-agentsandbox, that provides a CodeAct-style execute_code tool backed by kubernetes-sigs/agent-sandbox (Kubernetes Pod execution with persistent filesystem/package state), plus the associated core namespace shim, docs, tests, samples, and workspace/lockfile registration.

Changes:

• Introduces AgentSandboxExecuteCodeTool and AgentSandboxCodeActProvider to run LLM-emitted Python inside an agent-sandbox Pod claimed from a SandboxWarmPool.
• Adds a core lazy-import shim (agent_framework.agentsandbox) and a runnable sample demonstrating multi-turn persistence.
• Registers the new package in the Python workspace (pyproject.toml), lockfile (uv.lock), and package status table.

Reviewed changes

Copilot reviewed 17 out of 19 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
python/uv.lock	Adds the new workspace member and locks k8s-agent-sandbox (+ transitive deps).
python/pyproject.toml	Registers agent-framework-agentsandbox as a workspace dependency.
python/PACKAGE_STATUS.md	Marks the new package as alpha.
python/packages/core/agent_framework/agentsandbox/init.py	Lazy-import namespace shim for optional connector usage (agent_framework.agentsandbox).
python/packages/core/agent_framework/agentsandbox/init.pyi	Typing stub re-exporting the connector’s public classes.
python/samples/02-agents/context_providers/README.md	Adds the new agentsandbox CodeAct sample to the context provider index.
python/samples/02-agents/context_providers/agentsandbox_codeact/README.md	Sample-specific setup and usage documentation.
python/samples/02-agents/context_providers/agentsandbox_codeact/agentsandbox_codeact.py	Runnable demo using OllamaChatClient and the new provider.
python/packages/agentsandbox/LICENSE	Adds MIT license for the new package.
python/packages/agentsandbox/README.md	Package overview, quickstart, and behavioral notes.
python/packages/agentsandbox/TESTING.md	End-to-end local testing walkthrough (kind + agent-sandbox + router + Ollama).
python/packages/agentsandbox/pyproject.toml	New package metadata, dependencies, and tooling config.
python/packages/agentsandbox/agent_framework_agentsandbox/py.typed	Marks the package as typed.
python/packages/agentsandbox/agent_framework_agentsandbox/init.py	Package exports and version resolution.
python/packages/agentsandbox/agent_framework_agentsandbox/_provider.py	ContextProvider that injects CodeAct instructions + the execute_code tool.
python/packages/agentsandbox/agent_framework_agentsandbox/_instructions.py	Builders for CodeAct instructions and tool description.
python/packages/agentsandbox/agent_framework_agentsandbox/_execute_code_tool.py	FunctionTool implementation that claims/reuses a sandbox Pod and executes code in it.
python/packages/agentsandbox/tests/agentsandbox/init.py	Test package init.
python/packages/agentsandbox/tests/agentsandbox/test_agentsandbox_codeact.py	Unit tests using a stubbed async sandbox client (no cluster required).

[aleks-stefanovic]

@microsoft-github-policy-service agree

@microsoft-github-policy-service agree

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/agentsandbox/agent_framework_agentsandbox
_execute_code_tool.py	106	13	87%	168, 173, 184, 196, 202, 238, 278–279, 285, 288–290, 309
_instructions.py	5	0	100%
_provider.py	28	1	96%	114
TOTAL	44512	5350	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
8763	33 💤	0 ❌	0 🔥	2m 20s ⏱️

[moonbox3]

@aleks-stefanovic the uv.lock has a conflict