Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 8 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Inspired by Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode/) and
- **Failed tool calls raise** — a REST tool whose API answers with an HTTP error raises `HTTPStatusError` (with `status_code` and `body`), and any other failure, including an MCP tool that reports one, raises `ToolError`. ADK returns these as values for a model to read, but sandbox code reads return values, so it would otherwise carry on as if the call had worked.
- **Bake any Python package into the image** — extend the published base image with anything the model's code needs to `import`, no runtime `pip install` required. The sandbox reports what it has installed, so the model is told about it automatically.
- **Cross-turn persistence via ADK Artifacts** — files the code creates or changes are saved as artifacts automatically, and `save_artifact` / `load_artifact` / `list_artifacts` are auto-injected and route through your configured `ArtifactService`.
- **Tool results saved as artifacts** — on by default; every tool's result is persisted as a `code_mode.tool_result` artifact (with optional model-supplied name/description) so hosts can forward outputs and large results stay out of the prompt. Opt out with `save_tool_results_as_artifacts=False`.
- **Tool results saved as artifacts** — on by default; every tool's result is persisted as a `code_mode.tool_result` artifact (with optional model-supplied name/description) so hosts can forward outputs and later turns can reload them. The code always gets the full result. Opt out with `save_tool_results_as_artifacts=False`.
- **Bounded stdout/stderr** — overflow lands in a session artifact instead of poisoning the prompt.
- **Production-ready remote sandbox** — `RemoteBackend` connects to an isolated per-turn container over WebSocket, reused across the turn's `execute_code` calls. Deploy on any cloud platform (Cloud Run, Fargate, ACI, Kubernetes, Fly.io, etc.).
- **Local development** — `UnsafeLocalDockerBackend` runs the sandbox against your local Docker daemon for fast iteration. **Not for production** — see [Safety](#-safety).
Expand Down Expand Up @@ -225,7 +225,7 @@ save_artifact(
mime_type="application/json",
)
print(list_artifacts())
report = json.loads(load_artifact(filename="report.json")["data"])
report = load_artifact(filename="report.json") # {"status": "ready"}, already parsed
```

Pass `include_artifact_tools=False` to opt out. To react when the model saves an artifact, pass `on_artifacts_saved`:
Expand All @@ -241,7 +241,7 @@ ExecuteCodeTool(tools=..., backend=..., on_artifacts_saved=on_saved)

### Tool results as artifacts

By default (`save_tool_results_as_artifacts=True`) every non-artifact tool is wrapped so its return value is saved as a session artifact tagged `code_mode.tool_result = "true"`. This lets a host forward tool outputs to the user (read the marker in `on_artifacts_saved`) and lets a later turn reload a result with `load_artifact`. Results over 50,000 bytes return a dictionary with a `tool_result_artifact` filename and a `note` instead of the inline result.
By default (`save_tool_results_as_artifacts=True`) every non-artifact tool is wrapped so its return value is saved as a session artifact tagged `code_mode.tool_result = "true"`. This lets a host forward tool outputs to the user (read the marker in `on_artifacts_saved`) and lets a later turn reload a result with `load_artifact`. The code always gets the full result.

Naming is transparent: the filename is derived from the tool name and call id. Each wrapped tool also gains two **optional** parameters — `artifact_name` and `artifact_description` — that the model may pass to name/describe the saved artifact; both land in the artifact's `custom_metadata` (`code_mode.artifact_name` / `code_mode.artifact_description`) alongside the marker. Set `save_tool_results_as_artifacts=False` to return tool results inline without persisting them.

Expand Down Expand Up @@ -281,7 +281,7 @@ The model can read spilled stdout back from the overflow artifact:
```python
from tools import load_artifact
spilled = load_artifact(filename="code_mode/stdout/<call-id>.txt")
print(spilled["data"][-2000:])
print(spilled[-2000:])
```

### Turn-scoped sessions
Expand Down Expand Up @@ -313,14 +313,13 @@ preinstalled packages, and available functions. Print function calls, variables,
to see output, only stdout/stderr are returned. Variables and files persist across
calls within the same turn and reset on the next turn. Every file the code writes in
the working directory, and every tool's result, is saved as an artifact; use
`load_artifact` (imported the same way) to read one in a later turn. Large tool
results return a `tool_result_artifact` pointer. Tool calls that
`load_artifact` (imported the same way) to read one in a later turn. Tool calls that
call APIs raise HTTP errors as `HTTPStatusError` (with `status_code` and `body`);
other failures raise `ToolError`. Import both from `tools`. Each call can run for up
to 60s.
~~~

With `append_code_mode_metadata_to_system_instruction` disabled that middle sentence is replaced by the discovery text the pointer tier uses (see [Fitting the budget](#fitting-the-budget)), so the description never points at a section that wasn't appended. With `save_tool_results_as_artifacts=False` the description drops "and every tool's result" and the sentence about large results, and with `include_artifact_tools=False` it drops the `load_artifact` clause. The last sentence follows `timeout_seconds` and is left out when it's `None`.
With `append_code_mode_metadata_to_system_instruction` disabled that middle sentence is replaced by the discovery text the pointer tier uses (see [Fitting the budget](#fitting-the-budget)), so the description never points at a section that wasn't appended. With `save_tool_results_as_artifacts=False` the description drops "and every tool's result", and with `include_artifact_tools=False` it drops the `load_artifact` clause. The last sentence follows `timeout_seconds` and is left out when it's `None`.

The **`<code-mode>` block** is the per-deployment inventory of the sandbox, appended to the system instruction on every model turn:

Expand Down Expand Up @@ -365,7 +364,7 @@ from tools import save_artifact, load_artifact, list_artifacts
</code-mode>
~~~

Return types come from each tool's `response_json_schema`, or an MCP tool's `outputSchema`; a tool without one returns `Any`. Objects become `TypedDict` classes named after their `$defs` key or `title`, else the property holding them. Identical shapes share one class across a module, defined once at the top of its catalog section; a name clash with another module's class falls back to the tool's or parent's name; each stub file carries the classes its tool uses. An MCP tool's `outputSchema` describes the `structuredContent` field in its result. A saved tool result can also be a `ToolResultArtifact` pointer when it exceeds the size threshold. A tool with exactly one required parameter takes it positionally (`load_artifact("report.csv", version=2)`); every other parameter is keyword-only.
Return types come from each tool's `response_json_schema`, or an MCP tool's `outputSchema`; a tool without one returns `Any`. Objects become `TypedDict` classes named after their `$defs` key or `title`, else the property holding them. Identical shapes share one class across a module, defined once at the top of its catalog section; a name clash with another module's class falls back to the tool's or parent's name; each stub file carries the classes its tool uses. An MCP tool's `outputSchema` describes the `structuredContent` field in its result. A tool with exactly one required parameter takes it positionally (`load_artifact("report.csv", version=2)`); every other parameter is keyword-only.

Tags are indented; their content is not. The `<tools-package>` body is Python source, where leading whitespace is meaningful. Each installed-package line is `<import name>: <distribution> <version>`; namespace imports supplied by multiple distributions list every provider in deterministic order. Import names and providers are sorted so the block stays byte-stable for prompt caching. `<python-version>` and `<installed-packages>` are omitted entirely — rather than rendered blank — when the sandbox hasn't reported yet or the image has no extra packages, since an empty tag reads as "none exist".

Expand Down Expand Up @@ -406,7 +405,7 @@ print(open("/tools/slack/send_message.py").read()) # types, signature + docstri
print(open("/tools/slack/list_channels.py").read())
```

Text and JSON-like MIME types travel as plain strings in artifact tools; binary content is base64-encoded. `load_artifact` returns a dictionary with `kind`, `data`, and `mime_type`. Text and JSON use `kind="text"` and keep the string in `data`. Binary artifacts use `kind="bytes"` and store base64 in `data`.
Text and JSON-like MIME types travel as plain strings in artifact tools; binary content is base64-encoded. `load_artifact` returns the content itself: the parsed value for JSON, a `str` for other text, and `{"mime_type": str, "bytes": str}` (base64) for binary.

## 🛡️ Safety

Expand Down
88 changes: 50 additions & 38 deletions src/adk_code_mode/_artifact_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,14 @@

The wire format is JSON. Binary content is base64 over the wire — the model
encodes it before calling ``save_artifact`` and decodes it after
``load_artifact``. Loaded artifacts return a flat ``{"kind", "data",
"mime_type"}`` dict so the model dispatches on ``kind`` without importing
host-side types.
``load_artifact``. ``load_artifact`` returns the content itself: parsed JSON,
a ``str`` for other text, or ``{"mime_type", "bytes"}`` for binary.
"""

from __future__ import annotations

import base64
import json
from typing import Any

from google.adk.tools.function_tool import FunctionTool
Expand All @@ -31,13 +31,31 @@
def _is_text_mime(mime_type: str | None) -> bool:
if not mime_type:
return False
mime_type = _base_mime(mime_type)
if mime_type.startswith(_TEXT_MIME_PREFIXES):
return True
if mime_type in _TEXT_MIME_TYPES:
return True
return mime_type.endswith("+json") or mime_type.endswith("+xml")


def _is_json_mime(mime_type: str | None) -> bool:
base = _base_mime(mime_type or "")
return base == "application/json" or base.endswith("+json")


def _base_mime(mime_type: str) -> str:
return mime_type.split(";", 1)[0].strip().lower()


def _charset(mime_type: str | None) -> str:
for param in (mime_type or "").split(";")[1:]:
key, _, value = param.partition("=")
if key.strip().lower() == "charset":
return value.strip().strip('"')
return "utf-8"


async def save_artifact(
*,
filename: str,
Expand Down Expand Up @@ -65,11 +83,13 @@ async def save_artifact(
)

``custom_metadata`` is custom metadata to associate with the artifact.
``load_artifact`` gives back the parsed JSON, the text, or
``{"mime_type", "bytes"}`` with the same base64 string.
"""
if _is_text_mime(mime_type):
part = genai_types.Part(
inline_data=genai_types.Blob(
data=content.encode("utf-8"),
data=content.encode(_charset(mime_type)),
mime_type=mime_type or "text/plain",
)
)
Expand All @@ -88,50 +108,42 @@ async def load_artifact(
filename: str,
version: int | None = None,
tool_context: ToolContext,
) -> dict[str, Any] | None:
"""Load an artifact by filename. Returns ``None`` if not found.
) -> Any:
"""Load an artifact by filename and return its content. Returns ``None`` if not found.

Returned dict shape:
The return value depends on the artifact's mime type:

{
"kind": "text" | "bytes",
"data": <str>, # text: the string; bytes: base64-encoded
"mime_type": <str | None>,
}
- JSON (``application/json``, ``*+json``): the parsed value — for a saved
tool result, exactly what the original call returned.
- Other text (``text/*``, XML, JavaScript): the text as a ``str``.
- Binary: ``{"mime_type": <str>, "bytes": <base64 str>}``.

Example:

result = load_artifact(filename="report.json")
if result is None:
return
if result["kind"] == "text" and result["mime_type"] == "application/json":
payload = json.loads(result["data"])
elif result["kind"] == "bytes":
blob = base64.b64decode(result["data"])
rows = load_artifact(filename="search_call-1.json") # list/dict, already parsed
notes = load_artifact(filename="notes.txt") # str
image = load_artifact(filename="chart.png")
png = base64.b64decode(image["bytes"])
"""
part = await tool_context.load_artifact(filename, version=version)
if part is None:
return None
inline = part.inline_data
if inline is not None:
mime_type = inline.mime_type
data = inline.data or b""
if isinstance(data, str):
data = data.encode("utf-8")
if _is_text_mime(mime_type):
return {
"kind": "text",
"data": data.decode("utf-8"),
"mime_type": mime_type,
}
return {
"kind": "bytes",
"data": base64.b64encode(data).decode("ascii"),
"mime_type": mime_type,
}
if part.text is not None:
return {"kind": "text", "data": part.text, "mime_type": None}
return {"kind": "text", "data": "", "mime_type": None}
if inline is None:
return part.text or ""
mime_type = inline.mime_type
data = inline.data or b""
if isinstance(data, str):
data = data.encode("utf-8")
if not _is_text_mime(mime_type):
return {"mime_type": mime_type, "bytes": base64.b64encode(data).decode("ascii")}
text = data.decode(_charset(mime_type))
if _is_json_mime(mime_type):
try:
return json.loads(text)
except ValueError:
return text
return text


async def list_artifacts(*, tool_context: ToolContext) -> list[str]:
Expand Down
2 changes: 1 addition & 1 deletion src/adk_code_mode/_json.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# SPDX-FileCopyrightText: 2025-present Agenta <hello@buildagenta.com>
#
# SPDX-License-Identifier: Apache-2.0
"""JSON-safe conversion for the sandbox RPC reply."""
"""JSON-safe conversion shared by the RPC reply and saved tool results."""

from __future__ import annotations

Expand Down
10 changes: 10 additions & 0 deletions src/adk_code_mode/runtime/remote.py
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,7 @@ async def _connect(
return _RemoteSandboxSession(
ws=ws,
workdir_path=workdir_path,
max_message_size=self.max_message_size,
max_upload_workspace_bytes=self.max_upload_workspace_bytes,
max_download_workspace_bytes=self.max_download_workspace_bytes,
)
Expand All @@ -148,11 +149,13 @@ def __init__(
*,
ws: Any,
workdir_path: str,
max_message_size: int,
max_upload_workspace_bytes: int,
max_download_workspace_bytes: int,
) -> None:
self._ws = ws
self._workdir_path = workdir_path
self._max_message_size = max_message_size
self._max_upload_workspace_bytes = max_upload_workspace_bytes
self._max_download_workspace_bytes = max_download_workspace_bytes

Expand All @@ -172,6 +175,13 @@ async def begin_block(self, input_paths: Sequence[str]) -> None:

async def send(self, frame: Frame) -> None:
payload = encode(frame)
# The sandbox closes the connection on an oversized message, so refuse it
# here instead; a tool reply then reaches the code as an error.
if len(payload) > self._max_message_size:
raise ValueError(
f"{type(frame).__name__} ({len(payload):,} bytes) exceeds "
f"max_message_size ({self._max_message_size:,})"
)
try:
await self._ws.send(payload.decode("utf-8"))
except websockets.ConnectionClosed as exc:
Expand Down
7 changes: 2 additions & 5 deletions src/adk_code_mode/tool.py
Original file line number Diff line number Diff line change
Expand Up @@ -161,8 +161,6 @@ def _build_description(
saved = f" {saved} is saved as an artifact"
if artifact_tools:
saved += "; use `load_artifact` (imported the same way) to read one in a later turn"
if tool_results:
saved += ". Large tool results return a `tool_result_artifact` pointer"
limit = f" Each call can run for up to {timeout_seconds}s." if timeout_seconds else ""
return (
f"{_DESCRIPTION_PREFIX}{pointer}{_DESCRIPTION_OUTPUT}{saved}.{_DESCRIPTION_ERRORS}{limit}"
Expand Down Expand Up @@ -248,9 +246,8 @@ def __init__(
``load_artifact``. Set ``False`` for a strict tool surface.
save_tool_results_as_artifacts: If true (default), every non-artifact
tool is wrapped so its result is also saved as a session artifact,
reloadable in later turns via ``load_artifact``. Large results
return an artifact pointer. Set ``False`` to skip saving and
always get the full result inline.
reloadable in later turns via ``load_artifact``. The code always
gets the full result. Set ``False`` to skip saving.
append_code_mode_metadata_to_system_instruction: If true (default),
every model turn's system instruction gets a ``<code-mode>`` block
describing the sandbox: its Python version, its preinstalled
Expand Down
Loading
Loading