Add AG2 sandbox extension example

Covers AG2 1.0's native Tenki backend (ag2.extensions.tenki, merged in
ag2ai/ag2#3096): one TenkiEnvironment powering SandboxShellTool and
SandboxCodeTool, with a live no-LLM-key verify that exercises the real
factory open/exec/put_file/aclose path. Pins ag2 to the merge commit since
the 1.0.1 release predates the extension.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: opencolin

README.md

@@ -53,6 +53,7 @@ Give an agent a sandboxed place to run the code it writes.
 | [OpenAI Agents SDK](examples/openai-agents-sdk/) | Sandboxed execution as an agent tool |
 | [LlamaIndex](examples/llamaindex/) | Sandboxed execution as a `FunctionTool` |
 | [Hugging Face smolagents](examples/smolagents/) | Remote Python executor for a `CodeAgent` |
+| [AG2](examples/ag2-tenki/) | Native sandbox backend for shell + code tools |
 
 ### Developer tools
 

examples/ag2-tenki/README.md

@@ -0,0 +1,97 @@
+# AG2 agents with a Tenki sandbox
+
+[AG2](https://github.com/ag2ai/ag2) 1.0 is a ground-up rewrite of the framework (`from ag2 import Agent` — not the old AutoGen 0.x `ConversableAgent` API) with first-class sandbox tools: `SandboxShellTool` and `SandboxCodeTool` run whatever the model writes inside a pluggable sandbox backend. This example uses AG2's **native Tenki backend** — `ag2.extensions.tenki` (merged in [ag2ai/ag2#3096](https://github.com/ag2ai/ag2/pull/3096), maintained with Tenki) — so every shell command and code snippet executes in an isolated [Tenki](https://tenki.cloud) microVM instead of on your machine.
+
+## The agent
+
+One `TenkiEnvironment` powers both tools:
+
+```python
+import asyncio
+
+from ag2 import Agent
+from ag2.config import AnthropicConfig
+from ag2.extensions.tenki import TenkiEnvironment
+from ag2.tools import SandboxCodeTool, SandboxShellTool
+
+async def main() -> None:
+    env = TenkiEnvironment()
+    async with env:
+        agent = Agent(
+            "developer",
+            config=AnthropicConfig(model="claude-sonnet-4-6"),
+            tools=[SandboxShellTool(env), SandboxCodeTool(env.code_environment())],
+        )
+        reply = await agent.ask("Write hello.txt, then read it with Python.")
+        print(await reply.content())
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+(Running this agent needs an LLM key — `verify.py` below doesn't.)
+
+`env.code_environment()` matters: Tenki's default image ships `python3` (not `python`), and the returned `CodeAdapter` maps the `python` runner accordingly. Pass the env itself to `SandboxShellTool`, the adapter to `SandboxCodeTool`.
+
+## Setup (Python 3.10+)
+
+```bash
+uv venv                                 # or: python3.11 -m venv .venv
+uv pip install -r requirements.txt      # ag2 (git pin, see note) + tenki SDK
+export TENKI_API_KEY=tk_...             # from the Tenki dashboard
+```
+
+> **Release note (2026-08):** the Tenki extension merged into ag2 `main` on 2026-08-13, after the latest PyPI release (1.0.1, 2026-07-29) — so `requirements.txt` pins the merge commit via git. Once the next ag2 release ships `ag2/extensions/tenki`, this becomes simply:
+>
+> ```bash
+> pip install "ag2[anthropic]" "tenki>=0.5.4,<1"
+> ```
+
+## Configuring `TenkiEnvironment`
+
+```python
+from ag2.extensions.tenki import TenkiEnvironment, TenkiResources
+
+env = TenkiEnvironment(
+    workspace_id="your-workspace-id",   # auto-detected when the key sees one workspace
+    name="my-agent-sandbox",
+    image="workspace/image:tag",
+    env_vars={"APP_ENV": "sandbox"},
+    resources=TenkiResources(cpu_cores=2, memory_mb=4096, disk_size_gb=5),
+    timeout=60,
+    max_duration=900,
+)
+```
+
+| Parameter | Default | Purpose |
+| --- | --- | --- |
+| `api_key` | `TENKI_API_KEY` | API authentication |
+| `api_url` | `TENKI_API_URL` or production | API endpoint |
+| `workspace_id` | Auto-detected when unique | Tenki workspace scope |
+| `name` | `ag2` | Sandbox name in the Tenki dashboard |
+| `image` | Tenki default image | Registry image reference |
+| `env_vars` | `{}` | Environment variables baked into the sandbox |
+| `resources` | Tenki defaults | CPU / memory / disk overrides |
+| `timeout` | `60` s | Sandbox startup + per-command timeout |
+| `max_duration` | `900` s | Server-enforced sandbox lifetime backstop |
+| `workdir` | `/home/tenki` | Working directory for commands and files |
+
+## What the backend does
+
+- **One environment, both tools.** The same `TenkiEnvironment` serves `SandboxShellTool` directly and `SandboxCodeTool` via `code_environment()` — one sandbox, one cleanup path.
+- **Files persist across tool calls.** The factory caches sandboxes by their resolved parameters, so a file the agent writes in tool call 1 is still there in tool call 10. The sandbox lives until `aclose()` (the `async with env` exit), not per call.
+- **Cleanup has three layers.** Creation is failure-atomic (a sandbox that never becomes ready is terminated immediately), an `atexit` hook catches interpreter shutdown if `aclose()` never ran, and `max_duration` reclaims the VM server-side even if the client process dies. Sandboxes are created with inbound networking off, outbound on.
+
+## Verify
+
+```bash
+node verify.mjs      # or: .venv/bin/python verify.py
+```
+
+`verify.py` drives the real integration classes against live Tenki; no LLM key needed. It imports `ag2.extensions.tenki`, constructs `TenkiEnvironment` + `TenkiResources`, builds the `CodeAdapter`, then does what `SandboxShellTool` does per call — `env.open()` → live sandbox → `exec` (`42`) — plus a file round-trip across two `open()` calls to prove the caching, and asserts teardown on scope exit. The agent loop on top is covered by ag2's own CI.
+
+## Notes
+
+- The extension uses Tenki's **new [`tenki`](https://pypi.org/project/tenki/) Python SDK** (`tenki>=0.5.4,<1`) — the canonical successor namespace to the older `tenki-sandbox` package some earlier cookbook examples use. Don't install `tenki-sandbox` for this one.
+- Auth: a `tk_` API key works as-is. A `tenki login` browser session token must be prefixed `cookie:` for the Python SDK (`verify.py` handles this).
+- All credential/selection parameters also accept AG2 `Variable`s for per-request (multi-tenant) resolution — see the [AG2 Tenki docs](https://github.com/ag2ai/ag2/blob/main/website/docs/user-guide/extensions/tenki.mdx).

examples/ag2-tenki/requirements.txt

@@ -0,0 +1,5 @@
+# ag2's latest release (1.0.1, 2026-07-29) predates the Tenki extension merge
+# (ag2ai/ag2#3096, 2026-08-13). Pin the merge commit until the next ag2 release
+# ships ag2/extensions/tenki, then switch to a plain `ag2` pin.
+ag2 @ git+https://github.com/ag2ai/ag2.git@535dfb303cf1db9f862ac099a9f7887d3f8f9b39
+tenki>=0.5.4,<1

examples/ag2-tenki/verify.mjs

@@ -0,0 +1,11 @@
+/**
+ * Shim so the cookbook's Node verify harness can run this Python example.
+ * Runs verify.py with the example's local venv if present, else `python3`.
+ * Setup (Python 3.10+): `uv venv && uv pip install -r requirements.txt` (see README).
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+const py = existsSync(".venv/bin/python") ? ".venv/bin/python" : process.env.PYTHON || "python3";
+const r = spawnSync(py, ["verify.py"], { stdio: "inherit" });
+process.exit(r.status ?? 1);

examples/ag2-tenki/verify.py

@@ -0,0 +1,82 @@
+"""
+Smoke-verify the AG2 Tenki extension, live and without any LLM key:
+  1. `ag2.extensions.tenki` imports (the integration shipped in this ag2 build),
+  2. `TenkiEnvironment` + `TenkiResources` construct and `code_environment()`
+     builds the CodeAdapter that `SandboxCodeTool` consumes, and
+  3. the real factory path works end to end: `env.open()` creates a live Tenki
+     sandbox (exactly what `SandboxShellTool` does per call), a second `open()`
+     returns the same cached sandbox, put_file/exec/remove_file round-trip, and
+     leaving `async with env` tears the sandbox down via `aclose()`.
+
+No agent or model call is made — the tools' sandbox plumbing is the part a
+Tenki outage or an API change would break, and it is fully exercised here.
+
+Token/workspace from env (CI) or ~/.config/tenki/config.yaml (local `tenki login`).
+"""
+
+import asyncio
+import os
+import sys
+from pathlib import PurePosixPath
+
+from ag2.extensions.tenki import TenkiEnvironment, TenkiResources  # proves the extension shipped
+
+
+def cfg(key):
+    try:
+        with open(os.path.expanduser("~/.config/tenki/config.yaml")) as f:
+            for line in f:
+                if line.startswith(key + ":"):
+                    return line.split(":", 1)[1].strip()
+    except Exception:
+        pass
+    return ""
+
+
+token = os.environ.get("TENKI_AUTH_TOKEN") or os.environ.get("TENKI_API_KEY") or cfg("auth_token")
+if not token:
+    print("No token. Set TENKI_API_KEY, or run `tenki login`.")
+    sys.exit(1)
+
+# `tenki` SDK auth gap: a bare `tenki login` browser session token is sent as a
+# Bearer header (rejected); prefix it `cookie:` so it travels as a cookie.
+# A `tk_` API key works as-is.
+if not token.startswith(("tk_", "ory_st_", "cookie:")):
+    token = f"cookie:{token}"
+
+
+async def main() -> None:
+    env = TenkiEnvironment(
+        api_key=token,
+        workspace_id=os.environ.get("TENKI_WORKSPACE_ID") or cfg("current_workspace_id") or None,
+        name="cookbook-verify",
+        resources=TenkiResources(cpu_cores=1, memory_mb=1024),
+        timeout=90,
+        max_duration=600,
+    )
+    env.code_environment()  # the CodeAdapter SandboxCodeTool consumes — python runner is python3
+
+    async with env:  # the documented usage: tools share this factory for its whole scope
+        async with env.open() as sb:  # what SandboxShellTool does on every call
+            r = await sb.exec(["python3", "-c", "print(6 * 7)"])
+            assert r.exit_code == 0, f"exit {r.exit_code}: {r.output}"
+            assert r.output == "42", f"got {r.output!r}"
+
+            # The factory caches by parameter set: files persist across tool calls.
+            path = PurePosixPath("cookbook_probe.txt")
+            await sb.put_file(path, b"persisted between tool calls")
+            async with env.open() as sb2:
+                assert sb2 is sb, "expected the cached sandbox on the second open()"
+                r = await sb2.exec(["cat", str(path)])
+                assert r.exit_code == 0 and r.output == "persisted between tool calls", r.output
+            await sb.remove_file(path)
+    # `async with env` exit -> aclose() terminated the sandbox and closed the client.
+
+    print("✓ ag2-tenki: TenkiEnvironment → live sandbox via the real integration → exec 42 → aclose teardown")
+
+
+try:
+    asyncio.run(main())
+except Exception as e:  # noqa
+    print(f"✗ {type(e).__name__}: {e}")
+    sys.exit(1)