Skip to content

Agent Zero AI framework

Add reusable agent profile commands

Alessandro2a2890d89298
diff --git a/plugins/_a0_connector/AGENTS.md b/plugins/_a0_connector/AGENTS.md
index b16a4f449..462af9153 100644
--- a/plugins/_a0_connector/AGENTS.md
+++ b/plugins/_a0_connector/AGENTS.md
@@ -54,6 +54,8 @@
after all chunks for the `op_id` are assembled.
- Host browser status metadata may advertise `available_browsers` entries with browser ids, labels, CDP endpoints, status, and enabled state; keep older CLI payloads without those fields compatible.
- Model preset definitions exposed through v1 are global; project arguments select scope but never create project-owned definitions. Model switcher state reports the effective main, utility, and embedding models and preserves embedding-change notifications.
+- The protected v1 `agent_editor` route delegates to the bundled Agent Editor
+ API and must not define another profile schema or write profile files itself.
- Computer Use receipts describe transport success unless the connector returns explicit effect evidence. Linux target-bound typing requires a verified active/focused `window_id`; window activation uses focus, never a press action on an application or window node. Do not retry an identical failed Computer Use call.
## Work Guidance
diff --git a/plugins/_a0_connector/api/v1/agent_editor.py b/plugins/_a0_connector/api/v1/agent_editor.py
new file mode 100644
index 000000000..c43d708d1
--- /dev/null
+++ b/plugins/_a0_connector/api/v1/agent_editor.py
@@ -0,0 +1,13 @@
+"""POST /api/plugins/_a0_connector/v1/agent_editor."""
+from __future__ import annotations
+
+from helpers.api import Request, Response
+import plugins._a0_connector.api.v1.base as connector_base
+
+
+class AgentEditor(connector_base.ProtectedConnectorApiHandler):
+ async def process(self, input: dict, request: Request) -> dict | Response:
+ from plugins._agent_editor.api.agent_editor import AgentEditor as CoreAgentEditor
+
+ handler = CoreAgentEditor(self.app, self.thread_lock)
+ return await handler.process(input, request)
diff --git a/plugins/_a0_connector/api/v1/capabilities.py b/plugins/_a0_connector/api/v1/capabilities.py
index 4c9e5e035..379c6ff65 100644
--- a/plugins/_a0_connector/api/v1/capabilities.py
+++ b/plugins/_a0_connector/api/v1/capabilities.py
@@ -36,6 +36,7 @@ _OPTIONAL_FEATURES: dict[str, tuple[str, ...]] = {
"settings_get": ("helpers.settings", "helpers.subagents"),
"settings_set": ("helpers.settings", "helpers.subagents"),
"agent_profile_set": ("api.agent_profile_set",),
+ "agent_editor": ("plugins._agent_editor.api.agent_editor",),
"agents_list": ("helpers.subagents",),
"skills_list": ("helpers.skills", "helpers.files", "helpers.projects", "helpers.runtime"),
"skills_activate": ("helpers.skills", "helpers.persist_chat"),
diff --git a/plugins/_agent_editor/AGENTS.md b/plugins/_agent_editor/AGENTS.md
index cbf809cd2..9676d6191 100644
--- a/plugins/_agent_editor/AGENTS.md
+++ b/plugins/_agent_editor/AGENTS.md
@@ -32,6 +32,9 @@
`agents.json` and changes only the requested profile entry through the existing
project storage owner.
- Never call `helpers.subagents.save_agent_data`.
+- Fast creation from slash commands and connector clients calls
+ `helpers/editor.py:save_easy_profile`, so profile IDs, validation, sparse
+ writes, and the mutation boundary stay identical to Easy mode.
- Authored profile definitions remain YAML; editor-written plugin configs remain
JSON.
- Profile config paths use `helpers.plugins.determine_plugin_asset_path` for the
diff --git a/plugins/_agent_editor/api/agent_editor.py b/plugins/_agent_editor/api/agent_editor.py
index 462be8c00..2d996d833 100644
--- a/plugins/_agent_editor/api/agent_editor.py
+++ b/plugins/_agent_editor/api/agent_editor.py
@@ -23,6 +23,19 @@ class AgentEditor(ApiHandler):
"ok": True,
"state": editor.build_editor_state(profile_id, context),
}
+ if action == "quick_create":
+ profile_id, receipt = editor.save_easy_profile(
+ input.get("title"),
+ input.get("instructions"),
+ context,
+ tool_policy=input.get("tool_policy"),
+ )
+ return {
+ "ok": True,
+ **receipt,
+ "profile_id": profile_id,
+ "effective_profile": editor.build_profile_state(profile_id, context),
+ }
if action in {"plan", "save"}:
patch = input.get("patch")
plan = editor.build_change_plan(patch, context)
diff --git a/plugins/_agent_editor/extensions/webui/initFw_end/agent-editor.js b/plugins/_agent_editor/extensions/webui/initFw_end/agent-editor.js
index c317e502f..9b8f4a29f 100644
--- a/plugins/_agent_editor/extensions/webui/initFw_end/agent-editor.js
+++ b/plugins/_agent_editor/extensions/webui/initFw_end/agent-editor.js
@@ -6,5 +6,7 @@ export default async function initAgentEditor() {
if (initialized) return;
initialized = true;
globalThis.openAgentEditor = (options = {}) => store.open(options);
- globalThis.testAgentProfile = (profileId) => store.openFreshChat(String(profileId || ""), false);
+ globalThis.testAgentProfile = (profileId, projectName) => (
+ store.openFreshChat(String(profileId || ""), false, projectName)
+ );
}
diff --git a/plugins/_agent_editor/helpers/editor.py b/plugins/_agent_editor/helpers/editor.py
index 99ef10de9..11ad405a8 100644
--- a/plugins/_agent_editor/helpers/editor.py
+++ b/plugins/_agent_editor/helpers/editor.py
@@ -11,6 +11,7 @@ import threading
import time
from types import SimpleNamespace
from typing import Any
+import unicodedata
from urllib.parse import urlencode
from uuid import uuid4
@@ -120,6 +121,39 @@ def validate_profile_id(profile_id: Any) -> str:
return value
+def profile_id_from_title(title: Any) -> str:
+ if not isinstance(title, str) or not title.strip():
+ raise ValueError("Agent name is required.")
+ value = unicodedata.normalize("NFKD", title).encode("ascii", "ignore").decode()
+ value = re.sub(r"[^a-z0-9_-]+", "-", value.lower())
+ value = re.sub(r"[-_]{2,}", "-", value).strip("-_")[:64].rstrip("-_")
+ if not value:
+ raise ValueError("Agent name must contain at least one letter or number.")
+ return validate_profile_id(value)
+
+
+def save_easy_profile(
+ title: Any,
+ instructions: Any,
+ context: Any | None = None,
+ *,
+ tool_policy: Any | None = None,
+) -> tuple[str, dict[str, Any]]:
+ if not isinstance(instructions, str) or not instructions.strip():
+ raise ValueError("Instructions are required for a new agent.")
+ profile_id = profile_id_from_title(title)
+ patch: dict[str, Any] = {
+ "profile_id": profile_id,
+ "creating": True,
+ "editor_mode": "easy",
+ "metadata": {"set": {"title": title}, "reset": []},
+ "prompts": {"set": {SPECIFICS_FILE: instructions}, "reset": []},
+ }
+ if tool_policy is not None:
+ patch["tool_policy"] = _mapping(tool_policy, "tool_policy")
+ return profile_id, apply_change_plan(build_change_plan(patch, context))
+
+
def _context_project_name(context: Any | None) -> str:
return str(projects.get_context_project_name(context) or "") if context else ""
diff --git a/plugins/_agent_editor/webui/agent-editor-store.js b/plugins/_agent_editor/webui/agent-editor-store.js
index ac112bd0c..727b9674b 100644
--- a/plugins/_agent_editor/webui/agent-editor-store.js
+++ b/plugins/_agent_editor/webui/agent-editor-store.js
@@ -1238,15 +1238,16 @@ const model = {
}
},
- async openFreshChat(profileId, showReadyNote = false) {
+ async openFreshChat(profileId, showReadyNote = false, projectName = this.projectName) {
+ const scopeProject = String(projectName || "");
try {
const created = await callJsonApi("/chat_create", {
current_context: this.intent.contextId || chatsStore.selected || "",
});
await callJsonApi("/projects", {
- action: this.projectName ? "activate" : "deactivate",
+ action: scopeProject ? "activate" : "deactivate",
context_id: created.ctxid,
- ...(this.projectName ? { name: this.projectName } : {}),
+ ...(scopeProject ? { name: scopeProject } : {}),
});
await callJsonApi("/agent_profile_set", {
context_id: created.ctxid,
diff --git a/plugins/_commands/AGENTS.md b/plugins/_commands/AGENTS.md
index 30196cebc..3c5c051fa 100644
--- a/plugins/_commands/AGENTS.md
+++ b/plugins/_commands/AGENTS.md
@@ -33,6 +33,8 @@
- Commands accept prefix syntax (`/goal objective`) and exact postfix syntax (`objective /goal`); ordinary mid-sentence mentions are not invocations. The composer picker opens only for prefix syntax, while postfix commands resolve when sent.
- WebUI sends resolve through the picker effect path, while backend-originated messages resolve before reaching the agent.
- `/stop` uses the same shared cancellation operation as the composer Stop button, including progress cleanup and terminal logging.
+- `/profile` opens Manage agents without arguments, keeps existing profile
+ selection, and creates through Agent Editor when given a name and instructions.
- Built-in `/computer-use on|off` emits a bounded `computer_use` effect. WebUI
only directs the user to Host access in A0 Launcher or the same command in A0
CLI; it never changes a Launcher gateway lease from Agent Zero page content.
diff --git a/plugins/_commands/commands/connector_commands.py b/plugins/_commands/commands/connector_commands.py
index ad1f5de98..d72708a40 100644
--- a/plugins/_commands/commands/connector_commands.py
+++ b/plugins/_commands/commands/connector_commands.py
@@ -5,7 +5,7 @@ from typing import Any
from agent import AgentContext
from api.stop import stop_context
from helpers import message_queue as mq
-from helpers import plugins, projects
+from helpers import plugins, projects, subagents
from helpers.integration_commands import try_handle_command
from helpers.state_monitor_integration import mark_dirty_for_context
@@ -34,7 +34,7 @@ def run(payload: dict[str, Any]) -> dict[str, Any]:
if command == "project":
return _handle_project(context, raw_args)
if command == "profile":
- return _handle_profile(context, raw_args)
+ return _handle_profile(context, raw_args, arguments)
if command == "plugins":
return _effects({"type": "open_modal", "path": "/components/plugins/list/plugin-list.html"})
if command == "compact":
@@ -113,13 +113,43 @@ def _handle_project(context: AgentContext | None, raw_args: str) -> dict[str, An
return _show_markdown("Project", try_handle_command(context, f"/project {raw_args}") or "")
-def _handle_profile(context: AgentContext | None, raw_args: str) -> dict[str, Any]:
+def _handle_profile(
+ context: AgentContext | None,
+ raw_args: str,
+ arguments: dict[str, Any],
+) -> dict[str, Any]:
if not raw_args:
- return _effects({"type": "open_modal", "path": "/components/settings/settings.html"})
+ return _effects({"type": "open_agent_editor", "view": "manage"})
error = _require_context(context)
if error:
return _effects(_toast(error, level="error"))
- return _show_markdown("Agent Profile", try_handle_command(context, f"/agent {raw_args}") or "")
+
+ positional = [str(value) for value in arguments.get("positional") or []]
+ project_name = projects.get_context_project_name(context)
+ desired = raw_args.strip().strip("\"'").casefold()
+ profiles = subagents.get_available_agents_dict(project_name or None)
+ if len(positional) < 2 or any(
+ desired in {profile_id.casefold(), (item.title or profile_id).casefold()}
+ for profile_id, item in profiles.items()
+ ):
+ return _show_markdown("Agent Profile", try_handle_command(context, f"/agent {raw_args}") or "")
+
+ from plugins._agent_editor.helpers import editor
+
+ title = positional[0]
+ instructions = " ".join(positional[1:])
+ try:
+ profile_id, _ = editor.save_easy_profile(title, instructions, context)
+ except ValueError as exc:
+ return _effects(_toast(str(exc), level="error"))
+ return _effects(
+ _toast(f"Created agent {title}."),
+ {
+ "type": "test_agent_profile",
+ "profile_id": profile_id,
+ "project_name": project_name or "",
+ },
+ )
def _handle_models(context: AgentContext | None, raw_args: str) -> dict[str, Any]:
diff --git a/plugins/_commands/commands/profile.command.yaml b/plugins/_commands/commands/profile.command.yaml
index 082585831..28b079a66 100644
--- a/plugins/_commands/commands/profile.command.yaml
+++ b/plugins/_commands/commands/profile.command.yaml
@@ -1,5 +1,5 @@
name: profile
-description: Pick or set the active Agent Zero Core profile.
-argument_hint: "[profile]"
+description: Manage, select, or quickly create an agent profile.
+argument_hint: '[profile | "name" "instructions"]'
type: script
script_path: connector_commands.py
diff --git a/plugins/_commands/tests/test_commands_plugin.py b/plugins/_commands/tests/test_commands_plugin.py
index 4e7a783cd..cc7c47d05 100644
--- a/plugins/_commands/tests/test_commands_plugin.py
+++ b/plugins/_commands/tests/test_commands_plugin.py
@@ -296,6 +296,63 @@ def test_models_command_always_opens_modal():
}
+def test_profile_command_opens_agent_manager() -> None:
+ result = connector_commands.run(
+ {
+ "invocation": {"command_name": "profile", "raw_arguments": ""},
+ "context": {"context_id": ""},
+ }
+ )
+
+ assert result == {
+ "text": "",
+ "effects": [{"type": "open_agent_editor", "view": "manage"}],
+ }
+
+
+def test_profile_command_quick_creates_with_the_agent_editor(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from plugins._agent_editor.helpers import editor
+
+ context = SimpleNamespace()
+ saved: list[tuple[str, str, object]] = []
+ monkeypatch.setattr(connector_commands, "_context", lambda _context_id: context)
+ monkeypatch.setattr(connector_commands.projects, "get_context_project_name", lambda _context: "")
+ monkeypatch.setattr(connector_commands.subagents, "get_available_agents_dict", lambda _project: {})
+ monkeypatch.setattr(
+ editor,
+ "save_easy_profile",
+ lambda title, instructions, profile_context: (
+ saved.append((title, instructions, profile_context)) or "source-scout",
+ {},
+ ),
+ )
+
+ result = connector_commands.run(
+ {
+ "invocation": {
+ "command_name": "profile",
+ "raw_arguments": '"Source Scout" "Verify every claim"',
+ "arguments": {
+ "positional": ["Source Scout", "Verify every claim"],
+ },
+ },
+ "context": {"context_id": "ctx-1"},
+ }
+ )
+
+ assert saved == [("Source Scout", "Verify every claim", context)]
+ assert result["effects"] == [
+ {"type": "toast", "message": "Created agent Source Scout.", "level": "success"},
+ {
+ "type": "test_agent_profile",
+ "profile_id": "source-scout",
+ "project_name": "",
+ },
+ ]
+
+
def test_stop_command_uses_the_composer_stop_operation(monkeypatch):
class Log:
def __init__(self):
diff --git a/plugins/_commands/webui/commands-slash-store.js b/plugins/_commands/webui/commands-slash-store.js
index c44f733cc..704ccb534 100644
--- a/plugins/_commands/webui/commands-slash-store.js
+++ b/plugins/_commands/webui/commands-slash-store.js
@@ -431,6 +431,23 @@ const model = {
if (path) await window.openModal?.(path);
continue;
}
+ if (type === "open_agent_editor") {
+ await globalThis.openAgentEditor?.({
+ view: String(effect.view || "manage"),
+ profileId: String(effect.profile_id || ""),
+ });
+ continue;
+ }
+ if (type === "test_agent_profile") {
+ const profileId = String(effect.profile_id || "").trim();
+ if (profileId) {
+ await globalThis.testAgentProfile?.(
+ profileId,
+ String(effect.project_name || ""),
+ );
+ }
+ continue;
+ }
if (type === "show_markdown") {
hadToast = true;
notifyInfo(
diff --git a/tests/test_agent_editor.py b/tests/test_agent_editor.py
index 95339a3f2..1cf70bf24 100644
--- a/tests/test_agent_editor.py
+++ b/tests/test_agent_editor.py
@@ -127,6 +127,20 @@ def test_new_easy_profile_writes_only_minimum_exact_files(user_root: Path) -> No
)
+def test_quick_create_uses_the_easy_sparse_save_path(user_root: Path) -> None:
+ profile_id, receipt = editor.save_easy_profile(
+ "Café Research",
+ "Verify sources and return concise citations.",
+ )
+
+ assert profile_id == "cafe-research"
+ assert len(receipt["written"]) == 2
+ assert yaml_helper.loads(
+ (user_root / profile_id / "agent.yaml").read_text(encoding="utf-8")
+ ) == {"title": "Café Research"}
+ assert not list((user_root / profile_id).rglob("*.json"))
+
+
def test_editor_lifecycle_needs_no_model_or_utility_configuration(
user_root: Path,
monkeypatch: pytest.MonkeyPatch,
diff --git a/tests/test_agent_editor_webui.py b/tests/test_agent_editor_webui.py
index 04601c726..624626676 100644
--- a/tests/test_agent_editor_webui.py
+++ b/tests/test_agent_editor_webui.py
@@ -723,3 +723,15 @@ if (pending.length !== requestCount) throw new Error("cached profile catalog une
check=True,
text=True,
)
+
+
+def test_profile_slash_effects_reuse_the_agent_editor_entry_points() -> None:
+ slash_store = (
+ ROOT / "plugins" / "_commands" / "webui" / "commands-slash-store.js"
+ ).read_text(encoding="utf-8")
+
+ assert 'type === "open_agent_editor"' in slash_store
+ assert "globalThis.openAgentEditor?." in slash_store
+ assert 'type === "test_agent_profile"' in slash_store
+ assert "globalThis.testAgentProfile?." in slash_store
+ assert "String(effect.project_name || \"\")" in slash_store