Skip to content

Agent Zero AI framework

Fix native Responses tool metadata

Alessandro1d88a82b5523
diff --git a/helpers/responses_tools.py b/helpers/responses_tools.py
index 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:
continue
try:
- 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 = False
for 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:
continue
if 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 fallback
def _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.md
index 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.py
index 9bb3219f0..28f880de3 100644
--- a/tests/test_responses_tools.py
+++ b/tests/test_responses_tools.py
@@ -10,11 +10,18 @@ from helpers import responses_tools
class 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 tools
durable 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_pat
assert {
"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_pat
assert not {"code_exe", "memory", "call_sub", "behaviour"} & names
assert 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"]