Skip to content

Agent Zero AI framework

Describe bundled tool arguments in Responses schemas

Alessandroa0b8c52f63c6
diff --git a/helpers/responses_tools.py b/helpers/responses_tools.py
index 17ebb48b5..316db6533 100644
--- a/helpers/responses_tools.py
+++ b/helpers/responses_tools.py
@@ -4,6 +4,7 @@ import hashlib
import json
import os
import re
+from copy import deepcopy
from typing import Any
from helpers import files, subagents, tool_policy
@@ -27,9 +28,85 @@ TOOL_PROMPT_SUFFIX = ".md"
MAX_TOOL_DESCRIPTION_CHARS = 1024
TOOL_PROMPT_KWARGS_KEY = "_tool_prompt_kwargs"
+# Canonical arguments for the resolved bundled implementations, not tool-name aliases.
+BUNDLED_TOOL_PARAMETERS: dict[str, dict[str, Any]] = {
+ "tools/response.py": {
+ "text": {"type": "string", "minLength": 1},
+ },
+ "tools/search_engine.py": {"query": {"type": "string"}},
+ "tools/vision_load.py": {
+ "paths": {"type": "array", "items": {"type": "string"}},
+ "query": {"type": "string"},
+ },
+ "tools/wait.py": {
+ "seconds": {"type": "number"},
+ "minutes": {"type": "number"},
+ "hours": {"type": "number"},
+ "days": {"type": "number"},
+ "until": {"type": "string"},
+ },
+ "tools/notify_user.py": {
+ "message": {"type": "string"},
+ "title": {"type": "string"},
+ "detail": {"type": "string"},
+ "type": {"type": "string", "enum": ["info", "success", "warning", "error", "progress"]},
+ "priority": {"type": "integer", "enum": [10, 20]},
+ "timeout": {"type": "integer"},
+ },
+ "tools/call_subordinate.py": {
+ "message": {"type": "string"},
+ "profile": {"type": "string"},
+ "name": {"type": "string"},
+ "reset": {"type": "boolean"},
+ "context_id": {"type": "string"},
+ "attachments": {"type": "array", "items": {"type": "string"}},
+ },
+ "tools/skills_tool.py": {
+ "action": {"type": "string", "enum": ["list", "search", "load", "read_file"]},
+ "query": {"type": "string"},
+ "skill_name": {"type": "string"},
+ "file_path": {"type": "string"},
+ },
+ "plugins/_code_execution/tools/code_execution_tool.py": {
+ "runtime": {"type": "string", "enum": ["terminal", "python", "nodejs", "output", "reset"]},
+ "code": {"type": "string"},
+ "session": {"type": "integer"},
+ "reset": {"type": "boolean"},
+ "allow_running": {"type": "boolean"},
+ },
+ "plugins/_code_execution/tools/input.py": {
+ "keyboard": {"type": "string"},
+ "session": {"type": "integer"},
+ },
+ "plugins/_memory/tools/memory_load.py": {
+ "query": {"type": "string"},
+ "threshold": {"type": "number"},
+ "limit": {"type": "integer"},
+ "filter": {"type": "string"},
+ },
+ "plugins/_memory/tools/memory_save.py": {
+ "text": {"type": "string"},
+ "area": {"type": "string"},
+ },
+ "plugins/_memory/tools/memory_delete.py": {"ids": {"type": "string"}},
+ "plugins/_memory/tools/memory_forget.py": {
+ "query": {"type": "string"},
+ "threshold": {"type": "number"},
+ "filter": {"type": "string"},
+ },
+ "plugins/_memory/tools/behaviour_adjustment.py": {"adjustments": {"type": "string"}},
+ "plugins/_goal/tools/goal.py": {
+ "action": {"type": "string", "enum": ["get", "create", "update"]},
+ "objective": {"type": "string"},
+ "status": {"type": "string", "enum": ["complete", "blocked"]},
+ "note": {"type": "string"},
+ "token_budget": {"type": "integer", "minimum": 1},
+ },
+}
+
def build_responses_function_tools(agent: Any) -> tuple[list[dict[str, Any]], dict[str, str]]:
- """Build permissive Responses function tools from A0 tool prompts and MCP schemas."""
+ """Build Responses function tools from available implementations and prompt/MCP schemas."""
tools: list[dict[str, Any]] = []
name_map: dict[str, str] = {}
@@ -44,6 +121,7 @@ def build_responses_function_tools(agent: Any) -> tuple[list[dict[str, Any]], di
{
"type": "function",
"name": native_name,
+ "strict": False,
"description": _truncate(
tool_policy.tool_prompt_description(
prompt,
@@ -51,7 +129,7 @@ def build_responses_function_tools(agent: Any) -> tuple[list[dict[str, Any]], di
fallback=tool_name,
)
),
- "parameters": _schema_from_prompt(prompt),
+ "parameters": _schema_for_tool(agent, tool_name, prompt),
}
)
@@ -69,6 +147,7 @@ def build_responses_function_tools(agent: Any) -> tuple[list[dict[str, Any]], di
{
"type": "function",
"name": native_name,
+ "strict": False,
"description": _truncate(str(tool.get("description") or tool_name)),
"parameters": _schema_from_any(tool.get("input_schema")),
}
@@ -225,6 +304,24 @@ def _schema_from_prompt(prompt: str) -> dict[str, Any]:
return _permissive_schema()
+def _schema_for_tool(agent: Any, tool_name: str, prompt: str) -> dict[str, Any]:
+ if schema := _schema_from_embedded_json(prompt):
+ return schema
+ for path in subagents.get_paths(agent, "tools", tool_name + ".py"):
+ if not files.exists(path):
+ continue
+ relative = os.path.relpath(os.path.realpath(path), files.get_abs_path())
+ properties = BUNDLED_TOOL_PARAMETERS.get(relative)
+ if properties is not None:
+ return {
+ "type": "object",
+ "properties": deepcopy(properties),
+ "additionalProperties": True,
+ }
+ break # A custom implementation shadows the bundled contract.
+ return _schema_from_prompt(prompt)
+
+
def _schema_from_embedded_json(prompt: str) -> dict[str, Any]:
marker = "Input schema for tool_args:"
index = (prompt or "").find(marker)
diff --git a/helpers/responses_tools.py.dox.md b/helpers/responses_tools.py.dox.md
index c1a96e654..b9b731dcc 100644
--- a/helpers/responses_tools.py.dox.md
+++ b/helpers/responses_tools.py.dox.md
@@ -17,8 +17,9 @@
owns the Responses-specific prompt-name compatibility rules.
- Local prompt-derived function names use existing bullet declarations that pair a backticked name with `arg` or `args` for multi-tool prompt files, otherwise prefer explicit `"tool_name"` examples, then the first prompt heading, and finally the prompt filename.
- Apply registered tool-prompt render kwargs before deriving native metadata so descriptions never expose unresolved prompt templates.
-- Keep emitted schemas provider-neutral; provider-specific strictness belongs at the provider request boundary.
-- Use an explicitly embedded JSON input schema when present. Infer only an unambiguous single backticked argument on an otherwise empty `args:` line; all other local tools receive an honest permissive object schema instead of prose-guessed types.
+- Emit generated definitions with `strict: false` so Responses does not normalize optional or extensible arguments into required strict fields. Provider-specific strictness (such as Codex's final response) belongs at the provider request boundary.
+- Explicitly embedded JSON schemas take precedence. Otherwise use canonical argument properties only for a matching resolved bundled implementation in `BUNDLED_TOOL_PARAMETERS`; custom/profile overrides must not inherit a same-named bundled contract. Properties remain optional and extensible for action-dependent inputs and runtime aliases; runtime validation remains authoritative.
+- For unlisted implementations, infer only an unambiguous single backticked argument on an otherwise empty `args:` line; otherwise retain a permissive object instead of prose-guessed types.
- Native local-tool descriptions reuse the tool catalog's compact prompt
description; Responses retains native-name mapping, schema derivation, and
provider description limits.
diff --git a/tests/test_responses_tools.py b/tests/test_responses_tools.py
index 67e5fabc4..ffba38885 100644
--- a/tests/test_responses_tools.py
+++ b/tests/test_responses_tools.py
@@ -158,6 +158,7 @@ def test_responses_function_tools_add_empty_properties_to_mcp_schemas(
{
"type": "function",
"name": "remote_noop",
+ "strict": False,
"description": "Remote noop",
"parameters": {
"type": "object",
@@ -196,7 +197,7 @@ def test_response_tool_native_contract_stays_provider_neutral(monkeypatch):
assert description == "final answer to user"
assert response_tool["parameters"] == responses_tools._schema_from_prompt(prompt)
- assert "strict" not in response_tool
+ assert response_tool["strict"] is False
def test_complex_prompt_args_are_not_guessed_as_string_schemas():
@@ -213,6 +214,30 @@ def test_complex_prompt_args_are_not_guessed_as_string_schemas():
}
+def test_bundled_schema_follows_implementation_and_explicit_overrides(monkeypatch, tmp_path):
+ tool_path = PROJECT_ROOT / "plugins/_code_execution/tools/code_execution_tool.py"
+ custom_path = tmp_path / "code_execution_tool.py"
+ monkeypatch.setattr(
+ responses_tools.subagents, "get_paths",
+ lambda *args: [str(custom_path), str(tool_path)],
+ )
+ schema = responses_tools._schema_for_tool(None, "code_execution_tool", "")
+ assert schema["properties"]["session"] == {"type": "integer"}
+ assert schema["properties"]["reset"] == {"type": "boolean"}
+ assert "output" in schema["properties"]["runtime"]["enum"]
+ assert "code" not in schema.get("required", []) # Output polling needs no code.
+ schema["properties"]["runtime"]["enum"].clear()
+ assert responses_tools._schema_for_tool(None, "code_execution_tool", "")["properties"]["runtime"]["enum"]
+
+ custom_path.write_text("class CustomTool: pass\n")
+ assert responses_tools._schema_for_tool(None, "code_execution_tool", "") == responses_tools._permissive_schema()
+ explicit = 'Input schema for tool_args: {"type":"object","properties":{"custom":{"type":"boolean"}},"required":["custom"],"additionalProperties":false}'
+ assert responses_tools._schema_for_tool(None, "code_execution_tool", explicit) == {
+ "type": "object", "properties": {"custom": {"type": "boolean"}},
+ "required": ["custom"], "additionalProperties": False,
+ }
+
+
def test_responses_function_tools_include_vision_prompt(monkeypatch, tmp_path):
prompt_root = tmp_path / "prompts"
prompt_root.mkdir()