Skip to content

Agent Zero AI framework

Make agent profile overrides presence-aware

Alessandro641df2286818
diff --git a/agents/default/AGENTS.md b/agents/default/AGENTS.md
index 130d84cc1..956ee7057 100644
--- a/agents/default/AGENTS.md
+++ b/agents/default/AGENTS.md
@@ -8,7 +8,7 @@
## Ownership
- `agent.yaml` owns default profile metadata.
-- `agent.system.main.specifics.md` owns default profile-specific system prompt content.
+- `prompts/agent.system.main.specifics.md` owns default profile-specific system prompt content.
- Additional prompt overrides under this directory become shared defaults unless a child profile overrides them.
## Local Contracts
diff --git a/agents/default/agent.system.main.specifics.md b/agents/default/prompts/agent.system.main.specifics.md
similarity index 100%
rename from agents/default/agent.system.main.specifics.md
rename to agents/default/prompts/agent.system.main.specifics.md
diff --git a/helpers/subagents.py b/helpers/subagents.py
index df9d5ae20..e544f4276 100644
--- a/helpers/subagents.py
+++ b/helpers/subagents.py
@@ -28,11 +28,12 @@ class SubAgentListItem(BaseModel):
path: str = ""
origin: list[Origin] = []
enabled: bool = True
+ avatar: dict[str, str] | None = None
@model_validator(mode="after")
def post_validator(self):
- if self.title == "":
- self.title = self.name
+ if "title" not in self.model_fields_set and self.name:
+ object.__setattr__(self, "title", self.name)
return self
@@ -55,7 +56,7 @@ def get_agents_dict(
for name, override in overrides.items():
base_agent = merged.get(name)
merged[name] = (
- _merge_agent_list_items(base_agent, override)
+ _merge_agent_list_item(base_agent, override)
if base_agent
else override
)
@@ -92,15 +93,15 @@ def _get_agents_list_from_dir(dir: str, origin: Origin) -> dict[str, SubAgentLis
for subdir in subdirs:
try:
- agent_yaml_path = files.get_abs_path(dir, subdir, "agent.yaml")
- if files.exists(agent_yaml_path):
- agent_yaml = files.read_file(agent_yaml_path)
- agent_data = SubAgentListItem.model_validate(yaml_helper.loads(agent_yaml) or {})
- else:
- agent_json = files.read_file(files.get_abs_path(dir, subdir, "agent.json"))
- agent_data = SubAgentListItem.model_validate_json(agent_json)
+ try:
+ raw = _read_agent_definition(dir, subdir)
+ except FileNotFoundError:
+ raw = {}
+ agent_data = SubAgentListItem.model_validate(raw)
name = agent_data.name or subdir
agent_data.name = name
+ if "title" not in agent_data.model_fields_set:
+ object.__setattr__(agent_data, "title", name)
agent_data.path = files.get_abs_path(dir, subdir)
agent_data.origin = [origin]
result[name] = agent_data
@@ -111,15 +112,6 @@ def _get_agents_list_from_dir(dir: str, origin: Origin) -> dict[str, SubAgentLis
def load_agent_data(name: str, project_name: str | None = None) -> SubAgent:
- def _merge_agent(
- original: SubAgent | None, override: SubAgent | None = None
- ) -> SubAgent | None:
- if original and override:
- return _merge_agents(original, override)
- elif original:
- return original
- return override
-
from helpers import plugins
# load default, plugin, and user agents and merge
@@ -184,31 +176,26 @@ def delete_agent_data(name: str) -> None:
def _load_agent_data_from_dir(dir: str, name: str, origin: Origin) -> SubAgent | None:
+ agent_dir = files.get_abs_path(dir, name)
+ if not os.path.isdir(agent_dir):
+ return None
+
try:
- agent_yaml_path = files.get_abs_path(dir, name, "agent.yaml")
- if files.exists(agent_yaml_path):
- agent_yaml = files.read_file(agent_yaml_path)
- subagent = SubAgent.model_validate(yaml_helper.loads(agent_yaml) or {})
- else:
- subagent_json = files.read_file(files.get_abs_path(dir, name, "agent.json"))
- subagent = SubAgent.model_validate_json(subagent_json)
+ subagent = SubAgent.model_validate(_read_agent_definition(dir, name))
except Exception:
# backward compatibility (before agent.json existed)
try:
- context_file = files.read_file(files.get_abs_path(dir, name, "_context.md"))
+ subagent = SubAgent(
+ context=files.read_file(files.get_abs_path(dir, name, "_context.md"))
+ )
except Exception:
- context_file = ""
- subagent = SubAgent(
- name=name,
- title=name,
- description="",
- context=context_file,
- origin=[origin],
- prompts={},
- )
+ subagent = SubAgent()
# non-stored fields
subagent.name = name
+ if "title" not in subagent.model_fields_set:
+ object.__setattr__(subagent, "title", name)
+ subagent.path = agent_dir
subagent.origin = [origin]
prompts_dir = f"{dir}/{name}/prompts"
@@ -221,37 +208,48 @@ def _load_agent_data_from_dir(dir: str, name: str, origin: Origin) -> SubAgent |
return subagent
-def _merge_agents(base: SubAgent | None, override: SubAgent | None) -> SubAgent | None:
+def _read_agent_definition(dir: str, name: str) -> dict:
+ yaml_path = files.get_abs_path(dir, name, "agent.yaml")
+ if files.exists(yaml_path):
+ return yaml_helper.loads(files.read_file(yaml_path)) or {}
+ json_path = files.get_abs_path(dir, name, "agent.json")
+ if files.exists(json_path):
+ return json.loads(files.read_file(json_path)) or {}
+ raise FileNotFoundError
+
+
+def _merge_agent(base: SubAgent | None, override: SubAgent | None) -> SubAgent | None:
if base is None:
return override
if override is None:
return base
- merged_prompts: dict[str, str] = {}
- merged_prompts.update(base.prompts or {})
- merged_prompts.update(override.prompts or {})
-
- return SubAgent(
- name=override.name,
- title=override.title,
- description=override.description,
- context=override.context,
- origin=_merge_origins(base.origin, override.origin),
- prompts=merged_prompts,
- )
+ data = _merge_agent_metadata(base, override)
+ data["prompts"] = {**(base.prompts or {}), **(override.prompts or {})}
+ return SubAgent.model_validate(data)
-def _merge_agent_list_items(
+def _merge_agent_list_item(
base: SubAgentListItem, override: SubAgentListItem
) -> SubAgentListItem:
- return SubAgentListItem(
+ return SubAgentListItem.model_validate(_merge_agent_metadata(base, override))
+
+
+def _merge_agent_metadata(
+ base: SubAgentListItem, override: SubAgentListItem
+) -> dict:
+ data = base.model_dump()
+ data.update(
+ override.model_dump(
+ exclude_unset=True, exclude={"name", "path", "origin", "prompts"}
+ )
+ )
+ data.update(
name=override.name or base.name,
- title=override.title or base.title,
- description=override.description or base.description,
- context=override.context or base.context,
path=override.path or base.path,
- origin=_merge_origins(base.origin, override.origin),
+ origin=[*base.origin, *override.origin],
)
+ return data
def get_agents_roots() -> list[str]:
@@ -296,7 +294,7 @@ def get_all_agents_list() -> list[dict[str, str]]:
items = _get_agents_list_from_dir(root, origin=origin)
for name, item in items.items():
if name in merged:
- merged[name] = _merge_agent_list_items(merged[name], item)
+ merged[name] = _merge_agent_list_item(merged[name], item)
else:
merged[name] = item
@@ -307,10 +305,6 @@ def get_all_agents_list() -> list[dict[str, str]]:
return result
-def _merge_origins(base: list[Origin], override: list[Origin]) -> list[Origin]:
- return base + override
-
-
def get_default_promp_file_names() -> list[str]:
return files.list_files("prompts", filter="*.md")
diff --git a/helpers/subagents.py.dox.md b/helpers/subagents.py.dox.md
index 9b954ff80..f2aa5a8f1 100644
--- a/helpers/subagents.py.dox.md
+++ b/helpers/subagents.py.dox.md
@@ -14,6 +14,8 @@
- `SubAgentListItem` (`BaseModel`)
- `post_validator(self)`
- `SubAgent` (`SubAgentListItem`)
+- Profile metadata includes optional avatar metadata and merges by key presence:
+ a missing key inherits, while a present empty value explicitly clears it.
- Top-level functions:
- `get_agents_list(project_name: str | None=...) -> list[SubAgentListItem]`
- `get_agents_dict(project_name: str | None=...) -> dict[str, SubAgentListItem]`
@@ -22,11 +24,12 @@
- `save_agent_data(name: str, subagent: SubAgent) -> None`
- `delete_agent_data(name: str) -> None`
- `_load_agent_data_from_dir(dir: str, name: str, origin: Origin) -> SubAgent | None`
-- `_merge_agents(base: SubAgent | None, override: SubAgent | None) -> SubAgent | None`
-- `_merge_agent_list_items(base: SubAgentListItem, override: SubAgentListItem) -> SubAgentListItem`
+- `_read_agent_definition(dir: str, name: str) -> dict`
+- `_merge_agent(base: SubAgent | None, override: SubAgent | None) -> SubAgent | None`
+- `_merge_agent_list_item(base: SubAgentListItem, override: SubAgentListItem) -> SubAgentListItem`
+- `_merge_agent_metadata(base: SubAgentListItem, override: SubAgentListItem) -> dict`
- `get_agents_roots() -> list[str]`
- `get_all_agents_list() -> list[dict[str, str]]`
-- `_merge_origins(base: list[Origin], override: list[Origin]) -> list[Origin]`
- `get_default_promp_file_names() -> list[str]`
- `get_available_agents_dict(project_name: str | None) -> dict[str, SubAgentListItem]`
- `get_paths(agent: 'Agent|None', *subpaths, must_exist_completely: bool=..., include_project: bool=..., include_user: bool=..., include_default: bool=..., include_plugins: bool=..., default_root: str=...) -> list[str]`: Returns list of file paths for the given agent and subpaths, searched in order of priority:
@@ -37,10 +40,15 @@
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, plugin state, settings/state persistence.
+- Nonexistent profile layers return `None` instead of synthesizing empty overrides.
- Imported dependency areas include: `helpers`, `json`, `os`, `pydantic`, `typing`.
## Key Concepts
+- Presence-aware merging uses Pydantic's `model_dump(exclude_unset=True)` so
+ missing keys inherit while explicitly empty values remain overrides. Runtime
+ `name`, `path`, `origin`, and `prompts` fields are handled separately; derived
+ title fallbacks do not become authored overrides.
- Important called helpers/classes observed in the source: `cache.toggle_area`, `model_validator`, `_get_agents_list_from_dir`, `plugins.get_enabled_plugin_paths`, `_merge_agent_dicts`, `files.get_subdirectories`, `_load_agent_data_from_dir`, `_merge_agent`, `files.write_file`, `files.delete_dir`, `SubAgent`, `SubAgentListItem`, `files.find_existing_paths_by_pattern`, `get_agents_roots`, `files.list_files`, `get_agents_dict`, `cache.determine_cache_key`, `cache.add`, `projects.get_project_meta`, `FileNotFoundError`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
@@ -55,6 +63,7 @@
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_skills_runtime.py`
+ - `tests/test_subagent_metadata_merge.py`
## Child DOX Index
diff --git a/skills/a0-create-agent/SKILL.md b/skills/a0-create-agent/SKILL.md
index 6d88103c7..36cc663ea 100644
--- a/skills/a0-create-agent/SKILL.md
+++ b/skills/a0-create-agent/SKILL.md
@@ -265,7 +265,7 @@ Profiles inherit all prompts from `/a0/prompts/` and from `/a0/agents/default/`.
### The canonical override: `agent.system.main.specifics.md`
-This is the designated extension slot for profile-specific role, identity, and behavior instructions. The file ships **empty** in both `/a0/prompts/agent.system.main.specifics.md` and `/a0/agents/default/agent.system.main.specifics.md` precisely so profiles can fill it in without fighting the base prompt. It is included from `agent.system.main.md` right after `agent.system.main.role.md`, so whatever you put here layers on top of the inherited role.
+This is the designated extension slot for profile-specific role, identity, and behavior instructions. The file ships **empty** in both `/a0/prompts/agent.system.main.specifics.md` and `/a0/agents/default/prompts/agent.system.main.specifics.md` precisely so profiles can fill it in without fighting the base prompt. It is included from `agent.system.main.md` right after `agent.system.main.role.md`, so whatever you put here layers on top of the inherited role.
**Every shipped profile in `/a0/agents/` overrides this file** — a good sanity check that this is the right place for your specialization. Look at the existing profiles for concrete shape:
diff --git a/tests/test_subagent_metadata_merge.py b/tests/test_subagent_metadata_merge.py
new file mode 100644
index 000000000..7794a55e6
--- /dev/null
+++ b/tests/test_subagent_metadata_merge.py
@@ -0,0 +1,92 @@
+from pathlib import Path
+
+from helpers import subagents
+
+
+def _write_profile(root: Path, name: str, metadata: str = "") -> Path:
+ profile = root / name
+ profile.mkdir(parents=True)
+ if metadata:
+ (profile / "agent.yaml").write_text(metadata, encoding="utf-8")
+ return profile
+
+
+def test_missing_metadata_inherits_and_present_empty_clears(tmp_path: Path) -> None:
+ bundled_root = tmp_path / "agents"
+ user_root = tmp_path / "usr-agents"
+ _write_profile(
+ bundled_root,
+ "researcher",
+ "title: Researcher\ndescription: Source heavy\ncontext: Delegate research\n",
+ )
+ _write_profile(user_root, "researcher", "description: ''\ncontext: ''\n")
+
+ bundled = subagents._load_agent_data_from_dir(
+ str(bundled_root), "researcher", "default"
+ )
+ user = subagents._load_agent_data_from_dir(
+ str(user_root), "researcher", "user"
+ )
+ merged = subagents._merge_agent(bundled, user)
+
+ assert merged is not None
+ assert merged.title == "Researcher"
+ assert merged.description == ""
+ assert merged.context == ""
+ assert merged.origin == ["default", "user"]
+
+
+def test_prompt_only_override_does_not_clear_metadata(tmp_path: Path) -> None:
+ bundled_root = tmp_path / "agents"
+ user_root = tmp_path / "usr-agents"
+ _write_profile(
+ bundled_root,
+ "researcher",
+ "title: Researcher\ndescription: Source heavy\ncontext: Delegate research\n",
+ )
+ profile = _write_profile(user_root, "researcher")
+ prompts = profile / "prompts"
+ prompts.mkdir()
+ (prompts / "agent.system.main.specifics.md").write_text(
+ "Only this changes.\n", encoding="utf-8"
+ )
+
+ merged = subagents._merge_agent(
+ subagents._load_agent_data_from_dir(
+ str(bundled_root), "researcher", "default"
+ ),
+ subagents._load_agent_data_from_dir(
+ str(user_root), "researcher", "user"
+ ),
+ )
+
+ assert merged is not None
+ assert merged.title == "Researcher"
+ assert merged.description == "Source heavy"
+ assert merged.context == "Delegate research"
+ assert merged.prompts == {
+ "agent.system.main.specifics.md": "Only this changes.\n"
+ }
+
+
+def test_nonexistent_layer_is_not_an_override(tmp_path: Path) -> None:
+ assert (
+ subagents._load_agent_data_from_dir(str(tmp_path), "missing", "user")
+ is None
+ )
+
+
+def test_default_specifics_uses_only_the_canonical_prompt_path() -> None:
+ root = Path(__file__).resolve().parents[1]
+ legacy = root / "agents" / "default" / "agent.system.main.specifics.md"
+ canonical = (
+ root
+ / "agents"
+ / "default"
+ / "prompts"
+ / "agent.system.main.specifics.md"
+ )
+
+ assert not legacy.exists()
+ assert canonical.is_file()
+ assert canonical.read_bytes() == b""