Skip to content

feat: opt in to full tool results and parsed load_artifact (re-applies #27) - #33

Closed
benclarkeio wants to merge 1 commit into
mainfrom
feat/opt-in-full-tool-results
Closed

benclarkeio wants to merge 1 commit into
mainfrom
feat/opt-in-full-tool-results

Conversation

@benclarkeio

Copy link
Copy Markdown
Contributor

Summary

#27 returned full tool results and parsed artifact content to the code, but #29's squash put the 2.x formats back, so 2.1.0 and main don't have it. This PR brings #27's behaviour back as opt-in options on ExecuteCodeTool. It keeps the 2.x formats as the defaults, so it is a minor release (2.2.0). It replaces #32, which shipped the same change as a major release.

Defaults stay 2.x

  • A tool result over 50,000 bytes is still swapped for a {"tool_result_artifact", "note"} pointer. Wrapped tools' stubs and catalog entries still return <type> | ToolResultArtifact, and the tool description still says large results return a pointer.
  • load_artifact still returns {"kind", "data", "mime_type"}.
  • No public parameter or export is removed.

New options

Both are ExecuteCodeTool arguments:

  • large_result_threshold: int | None = 50_000. Results over this many bytes become the pointer. None never substitutes: the code always gets the full result, which is still saved as an artifact. With None, stubs and the catalog drop | ToolResultArtifact, and the tool description drops the pointer sentence. ToolResultArtifactTool and wrap_tool_result_as_artifact also accept None, and the wrapper exposes large_result_threshold.
  • load_artifact_format: Literal["envelope", "parsed"] = "envelope". "parsed" injects a load_artifact that returns the content itself: parsed JSON, a str for other text, or {"mime_type": str, "bytes": <base64 str>} for binary. JSON that fails to parse comes back as a str. Its docstring in the stubs and catalog describes that format, so the model is told what it gets. Any other value raises ValueError.

DEFAULT_LARGE_RESULT_THRESHOLD and LoadArtifactFormat are now exported from adk_code_mode.

Fixes from #27, on by default

These fix bugs without changing any return format:

  • JSON-safe saving: saved tool results use the same JSON-safe conversion as the reply to the code (_json.json_safe). A dataclass or Pydantic result used to be saved as its str(); now it reloads as the value the code received.
  • Charsets: artifact text is encoded and decoded with the mime type's charset, with UTF-8 as the default. Mime parameters no longer change what counts as text, so application/json; charset=utf-8 loads as kind="text" instead of kind="bytes".
  • Remote frame size: RemoteBackend refuses a frame over max_message_size before sending it. An oversized tool reply now reaches the code as an error instead of closing the sandbox connection.

What agent-run passes to opt in

In create_execute_code_tool in src/a2anet_agent_run/agent_factory.py:

return ExecuteCodeTool(
    tools=tools,
    backend=backend,
    timeout_seconds=CODE_MODE_BLOCK_TIMEOUT_SECONDS,
    on_artifacts_saved=make_on_artifacts_saved(),
    large_result_threshold=None,
    load_artifact_format="parsed",
)

Also pin adk-code-mode==2.2.0 in pyproject.toml (both dependencies and the dev group's adk-code-mode[docker]), then run uv lock. agent-run uses nothing else this PR changes. cloudbuild.sandbox.yaml reads the sandbox version from uv.lock, so the sandbox image moves to adk-code-mode-sandbox==2.2.0 with it.

Sandbox and release

  • The sandbox needs no changes: ToolResultFrame and PROTOCOL_VERSION are unchanged, and nothing under sandbox-wheel/ changes. The size check runs on the host. The sandbox's WebSocket limit is 256 MiB, the same as the default max_message_size.
  • release-please bumps both __about__.py files together. release-please.yml publishes both adk-code-mode and adk-code-mode-sandbox to PyPI, then the base image. Merging this PR only opens the 2.2.0 release PR; merging that release PR publishes.

Tests

  • Defaults: all of main's 2.x tests still pass unchanged: the envelope, the pointer and its type, and the description. New tests check that the default threshold elides a result over 50,000 bytes, and that a large result reaches sandbox code as a pointer end to end.
  • Opt-ins:
    • Parsed load_artifact for each mime type, including a non-UTF-8 charset, and save_artifact → load_artifact round-trips.
    • large_result_threshold=None returns a 200 KB result in full and still saves it.
    • ExecuteCodeTool passes the threshold to the wrappers and injects the parsed load_artifact.
    • Stubs and the description drop the pointer when it can't occur.
    • An end-to-end sandbox run with both options.
  • Fixes: charset-aware envelope decoding and encoding, dataclass results saved JSON-safe, and the remote session refusing a frame over max_message_size without sending it.
  • make ci passes locally: ruff, mypy and pytest (278 passed). The 3 Docker-marked tests didn't run because no Docker daemon was available.

Generated by Claude Code

#27 returned full tool results and parsed artifact content, but #29's
squash put the 2.x formats back before 2.1.0. Bring #27's behaviour back
as opt-ins on `ExecuteCodeTool`, keeping the 2.x formats as the defaults.

- `large_result_threshold` (default 50,000 bytes): `None` never swaps a
  tool result for the `tool_result_artifact` pointer, so the code always
  gets the full result, which is still saved as an artifact. Stubs, the
  catalog and the tool description only mention the pointer when it can
  occur. `ToolResultArtifactTool` and `wrap_tool_result_as_artifact` also
  accept `None`
- `load_artifact_format` (default `"envelope"`): `"parsed"` injects a
  `load_artifact` that returns parsed JSON, a `str` for other text, or
  `{"mime_type", "bytes"}` for binary, with a docstring to match
- Save tool results with the same JSON-safe conversion as the reply to
  the code, so a saved result reloads as the value the code received
- Encode and decode artifact text with the mime type's charset (UTF-8 by
  default), and ignore mime parameters when deciding what is text
- `RemoteBackend` refuses a frame over `max_message_size` before sending
  it, so an oversized tool reply reaches the code as an error instead of
  closing the sandbox connection
- Export `DEFAULT_LARGE_RESULT_THRESHOLD` and `LoadArtifactFormat`

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013TYQ7F1kLDzPsAwBRC5KV1

Copy link
Copy Markdown
Contributor Author

Superseded by #34.


Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants