Agent Zero AI framework
Fix native Responses tool metadata
Alessandro1d88a82b5523
diff --git a/helpers/responses_tools.py b/helpers/responses_tools.pyindex 3b7ff725f..2da3118fc 100644--- a/helpers/responses_tools.py+++ b/helpers/responses_tools.py@@ -14,9 +14,18 @@ TOOL_NAME_EXAMPLE_PATTERN = re.compile(r"""["']tool_name["']\s*:\s*["']([A-Za-z0-9_-]{1,64})["']""")TOOL_HEADING_PATTERN = re.compile(r"^\s{0,3}#{1,6}\s+(.+?)\s*$", re.MULTILINE)+TOOL_DECLARATION_PATTERN = re.compile(+ r"^\s*-\s+`([A-Za-z0-9_-]{1,64})`:\s+(args?\b.*)$",+ re.IGNORECASE | re.MULTILINE,+)+SIMPLE_ARGS_PATTERN = re.compile(+ r"^\s*args?:\s*`([A-Za-z_][A-Za-z0-9_-]*)`\s*$",+ re.IGNORECASE | re.MULTILINE,+)TOOL_PROMPT_PREFIX = "agent.system.tool."TOOL_PROMPT_SUFFIX = ".md"MAX_TOOL_DESCRIPTION_CHARS = 1024+TOOL_PROMPT_KWARGS_KEY = "_tool_prompt_kwargs"def build_responses_function_tools(agent: Any) -> tuple[list[dict[str, Any]], dict[str, str]]:@@ -63,6 +72,9 @@ def _local_tool_prompts(agent: Any) -> list[tuple[str, str]]:tool_files = files.get_unique_filenames_in_dirs(prompt_dirs, f"{TOOL_PROMPT_PREFIX}*{TOOL_PROMPT_SUFFIX}")+ get_data = getattr(agent, "get_data", None)+ tool_kwargs = get_data(TOOL_PROMPT_KWARGS_KEY) if callable(get_data) else {}+ tool_kwargs = tool_kwargs if isinstance(tool_kwargs, dict) else {}result: list[tuple[str, str]] = []for tool_file in tool_files:basename = os.path.basename(tool_file)@@ -70,19 +82,33 @@ def _local_tool_prompts(agent: Any) -> list[tuple[str, str]]:if not fallback_name:continuetry:- prompt = agent.read_prompt(basename)+ prompt = agent.read_prompt(basename, **tool_kwargs.get(basename, {}))except Exception:try:prompt = files.read_file(tool_file)except Exception:prompt = ""- tool_name = _tool_name_from_prompt(prompt, fallback=fallback_name)- if not _include_local_tool_prompt(agent, tool_name):- continue- result.append((tool_name, prompt))+ for tool_name in _tool_names_from_prompt(prompt, fallback=fallback_name):+ if _include_local_tool_prompt(agent, tool_name):+ result.append((tool_name, prompt))++ vision_prompt = _vision_tool_prompt(agent)+ if vision_prompt:+ result.append(("vision_load", vision_prompt))return result+def _vision_tool_prompt(agent: Any) -> str:+ try:+ from plugins._model_config.helpers.model_config import get_chat_model_config++ if not get_chat_model_config(agent).get("vision", False):+ return ""+ return agent.read_prompt("agent.system.tools_vision.md")+ except Exception:+ return ""++def _include_local_tool_prompt(agent: Any, tool_name: str) -> bool:try:from plugins._a0_connector.helpers.remote_tool_prompts import (@@ -135,6 +161,15 @@ def _tool_name_from_prompt(prompt: str, *, fallback: str) -> str:return fallback+def _tool_names_from_prompt(prompt: str, *, fallback: str) -> list[str]:+ declarations = [+ match.group(1) for match in TOOL_DECLARATION_PATTERN.finditer(prompt or "")+ ]+ if declarations:+ return list(dict.fromkeys(declarations))+ return [_tool_name_from_prompt(prompt, fallback=fallback)]++def _tool_name_from_heading(heading: str) -> str:token = (heading or "").strip().split(None, 1)[0] if heading else ""name = token.strip("`'\" :")@@ -153,7 +188,10 @@ def _native_tool_name(tool_name: str) -> str:def _description_from_prompt(prompt: str, *, fallback: str) -> str:- lines: list[str] = []+ for match in TOOL_DECLARATION_PATTERN.finditer(prompt or ""):+ if match.group(1) == fallback:+ return _truncate(match.group(2))+in_fence = Falsefor raw_line in (prompt or "").splitlines():line = raw_line.strip()@@ -163,21 +201,23 @@ def _description_from_prompt(prompt: str, *, fallback: str) -> str:if in_fence or not line:continueif line.startswith("#"):- line = line.lstrip("#").strip()- if line.lower() == fallback.lower():- continue- lines.append(line)- if sum(len(part) for part in lines) >= MAX_TOOL_DESCRIPTION_CHARS:- break- description = " ".join(lines).strip() or fallback- return _truncate(description)+ continue+ return _truncate(line)+ return fallbackdef _schema_from_prompt(prompt: str) -> dict[str, Any]:schema = _schema_from_embedded_json(prompt)if schema:return schema- return _schema_from_args_line(prompt)+ match = SIMPLE_ARGS_PATTERN.search(prompt or "")+ if match:+ return {+ "type": "object",+ "properties": {match.group(1): {"type": "string"}},+ "additionalProperties": True,+ }+ return _permissive_schema()def _schema_from_embedded_json(prompt: str) -> dict[str, Any]:@@ -196,23 +236,6 @@ def _schema_from_embedded_json(prompt: str) -> dict[str, Any]:return {}-def _schema_from_args_line(prompt: str) -> dict[str, Any]:- properties: dict[str, Any] = {}- for line in (prompt or "").splitlines():- normalized = line.strip()- if "args:" not in normalized.lower() and "argument:" not in normalized.lower():- continue- for name in re.findall(r"`([A-Za-z_][A-Za-z0-9_-]*)`", normalized):- properties.setdefault(name, {"type": "string"})- if properties:- return {- "type": "object",- "properties": properties,- "additionalProperties": True,- }- return _permissive_schema()--def _schema_from_any(schema: Any) -> dict[str, Any]:if isinstance(schema, dict):normalized = dict(schema)diff --git a/helpers/responses_tools.py.dox.md b/helpers/responses_tools.py.dox.mdindex 6fd2727d4..8648408ec 100644--- a/helpers/responses_tools.py.dox.md+++ b/helpers/responses_tools.py.dox.md@@ -12,10 +12,11 @@## Local Contracts-- Build local function tools from enabled `agent.system.tool.*.md` prompt files.-- Local prompt-derived function names prefer explicit `"tool_name"` examples, then the first prompt heading, and only fall back to the prompt filename when the prompt declares no callable name.-- Function parameter schemas are object schemas with an explicit `properties` object so OpenAI-compatible servers that validate chat-style tool payloads accept permissive tools.-- Native tool descriptions omit both backtick- and tilde-fenced usage examples so Agent Zero text envelopes are not presented as function arguments.+- Build local function tools from enabled `agent.system.tool.*.md` prompt files and include `vision_load` only when the active chat model enables the matching vision prompt.+- 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.+- 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.+- Native local-tool descriptions use the matching compact multi-tool declaration or the first prose line, not a duplicate copy of the full tool manual or fenced examples.- Preserve original Agent Zero tool names through the native Responses name map.- Keep MCP tool schemas merged after local prompt-derived tools.- Connector remote tools are advertised only when `_a0_connector` runtime metadata says the matching connected CLI capability is currently available.diff --git a/tests/test_responses_tools.py b/tests/test_responses_tools.pyindex 9bb3219f0..28f880de3 100644--- a/tests/test_responses_tools.py+++ b/tests/test_responses_tools.py@@ -10,11 +10,18 @@ from helpers import responses_toolsclass FakeAgent:- def __init__(self, prompt_root: Path):+ def __init__(self, prompt_root: Path, data=None):self.prompt_root = prompt_root+ self.data = data or {}def read_prompt(self, file: str, **kwargs) -> str:- return (self.prompt_root / file).read_text(encoding="utf-8")+ prompt = (self.prompt_root / file).read_text(encoding="utf-8")+ for key, value in kwargs.items():+ prompt = prompt.replace("{{" + key + "}}", str(value))+ return prompt++ def get_data(self, key: str):+ return self.data.get(key)def _write_prompt(prompt_root: Path, basename: str, content: str) -> None:@@ -41,6 +48,10 @@ def test_responses_function_tools_use_prompt_declared_names(monkeypatch, tmp_pat"""## memory toolsdurable memory operations+ - `memory_load`: args `query`, optional `threshold`, `limit`, `filter`+ - `memory_save`: args `text`, optional `area`+ - `memory_delete`: arg `ids`+ - `memory_forget`: args `query`, optional `threshold`, `filter````json{"tool_name": "memory_load", "tool_args": {"query": "responses naming"}}```@@ -91,6 +102,9 @@ def test_responses_function_tools_use_prompt_declared_names(monkeypatch, tmp_patassert {"code_execution_tool","memory_load",+ "memory_save",+ "memory_delete",+ "memory_forget","call_subordinate","behaviour_adjustment","filename_only",@@ -98,6 +112,9 @@ def test_responses_function_tools_use_prompt_declared_names(monkeypatch, tmp_patassert not {"code_exe", "memory", "call_sub", "behaviour"} & namesassert name_map["code_execution_tool"] == "code_execution_tool"assert name_map["memory_load"] == "memory_load"+ assert name_map["memory_save"] == "memory_save"+ assert name_map["memory_delete"] == "memory_delete"+ assert name_map["memory_forget"] == "memory_forget"assert name_map["call_subordinate"] == "call_subordinate"assert name_map["behaviour_adjustment"] == "behaviour_adjustment"assert name_map["filename_only"] == "filename_only"@@ -156,6 +173,89 @@ def test_response_tool_native_contract_omits_wrapper_and_exposes_text():description = responses_tools._description_from_prompt(prompt, fallback="response")schema = responses_tools._schema_from_prompt(prompt)- assert '"tool_name"' not in description- assert "~~~" not in description+ assert description == "final answer to user"assert schema["properties"] == {"text": {"type": "string"}}+++def test_complex_prompt_args_are_not_guessed_as_string_schemas():+ for path in (+ PROJECT_ROOT / "prompts" / "agent.system.tool.scheduler.md",+ PROJECT_ROOT / "prompts" / "agent.system.tool.parallel.md",+ ):+ schema = responses_tools._schema_from_prompt(path.read_text(encoding="utf-8"))++ assert schema == {+ "type": "object",+ "properties": {},+ "additionalProperties": True,+ }+++def test_responses_function_tools_include_vision_prompt(monkeypatch, tmp_path):+ prompt_root = tmp_path / "prompts"+ prompt_root.mkdir()+ _write_prompt(+ prompt_root,+ "agent.system.tools_vision.md",+ """+ ## multimodal vision tools+ ### vision_load+ load images into the model for visual reasoning+ args: `paths` list of absolute image paths+ """,+ )+ agent = FakeAgent(prompt_root)++ monkeypatch.setattr(responses_tools.subagents, "get_paths", lambda *args: [])+ monkeypatch.setattr(+ responses_tools,+ "_vision_tool_prompt",+ lambda _agent: agent.read_prompt("agent.system.tools_vision.md"),+ )+ monkeypatch.setattr(responses_tools, "_mcp_tools", lambda _agent: [])++ tools, name_map = responses_tools.build_responses_function_tools(agent)++ assert [tool["name"] for tool in tools] == ["vision_load"]+ assert tools[0]["description"] == "load images into the model for visual reasoning"+ assert tools[0]["parameters"]["properties"] == {}+ assert name_map == {"vision_load": "vision_load"}+++def test_local_tool_prompts_use_registered_render_kwargs(monkeypatch, tmp_path):+ prompt_root = tmp_path / "prompts"+ prompt_root.mkdir()+ basename = "agent.system.tool.text_editor.md"+ _write_prompt(+ prompt_root,+ basename,+ """+ ### text_editor+ read {{default_line_count}} lines by default+ """,+ )+ agent = FakeAgent(+ prompt_root,+ data={+ responses_tools.TOOL_PROMPT_KWARGS_KEY: {+ basename: {"default_line_count": 200}+ }+ },+ )++ monkeypatch.setattr(+ responses_tools.subagents,+ "get_paths",+ lambda *args, **kwargs: [str(prompt_root)],+ )+ monkeypatch.setattr(responses_tools, "_vision_tool_prompt", lambda _agent: "")+ monkeypatch.setattr(+ responses_tools,+ "_include_local_tool_prompt",+ lambda _agent, _tool_name: True,+ )++ prompts = dict(responses_tools._local_tool_prompts(agent))++ assert "{{default_line_count}}" not in prompts["text_editor"]+ assert "read 200 lines by default" in prompts["text_editor"]