Skip to content

Agent Zero AI framework

docs(skills): teach Agent Zero to operate its own API

Alessandro54bc6ac72f1c
diff --git a/prompts/AGENTS.md b/prompts/AGENTS.md
index 2236ae7b0..dd0e0185c 100644
--- a/prompts/AGENTS.md
+++ b/prompts/AGENTS.md
@@ -20,6 +20,7 @@
- Prompt changes can alter agent behavior; keep edits narrow and intentional.
- Maintain clear separation between core behavior prompts and profile/plugin-specific customization.
- Delegation catalogs show profile IDs, titles, and context (description fallback) on separate lines; preserve project-scoped discovery.
+- Environment prompts keep runtime boundaries visible and route framework/API procedures to `a0-development` references.
- Keep configurable capability names and usage guidance in their
`agent.system.tool.*.md` prompts so tool policy removes the guidance together
with the capability; non-tool system fragments stay capability-neutral.
diff --git a/prompts/agent.system.main.environment.md b/prompts/agent.system.main.environment.md
index 3dc08fefd..0c4b81653 100644
--- a/prompts/agent.system.main.environment.md
+++ b/prompts/agent.system.main.environment.md
@@ -4,11 +4,7 @@ agent zero framework is python project in /a0 folder
linux fully root accessible via terminal
Python runtimes:
-- Framework runtime: /opt/venv-a0/bin/python runs Agent Zero itself, WebUI backend, API handlers, plugins/hooks, and framework imports.
-- Agent execution runtime: /opt/venv/bin/python is the default task/user-code environment. Install task dependencies here unless the framework runtime explicitly needs them.
-- Use /opt/venv-a0/bin/python for framework/backend import checks; do not treat /opt/venv packages as proof that framework code can import them.
-
-WebUI JSON API:
-- API handlers live at /api/<handler_name> and usually accept JSON POST requests.
-- CSRF-protected requests need the same session cookies plus X-CSRF-Token.
-- Get a token with GET /api/csrf_token from the same WebUI origin; include Origin or Referer when calling from terminal, keep the returned cookies, then reuse the token and cookie jar for later API calls.
+- /opt/venv/bin/python: task code and task dependencies
+- /opt/venv-a0/bin/python: Agent Zero framework, backend, plugins/hooks and import checks
+do not use one runtime as proof for the other
+before Agent Zero framework development or WebUI API calls, load a0-development and read relevant references
diff --git a/skills/a0-development/AGENTS.md b/skills/a0-development/AGENTS.md
index bfa89616a..76b3d91ef 100644
--- a/skills/a0-development/AGENTS.md
+++ b/skills/a0-development/AGENTS.md
@@ -3,6 +3,7 @@
## Purpose
- Own the broad Agent Zero development guide used by agents extending the framework.
+- Route user-requested application operations through existing HTTP APIs with explicit target IDs and verified results.
- Keep architecture, tools, extensions, API, agents, prompts, projects, plugins, runtime, and skills guidance in sync with the repository.
## Ownership
diff --git a/skills/a0-development/SKILL.md b/skills/a0-development/SKILL.md
index 6f51cb39d..2d21c043e 100644
--- a/skills/a0-development/SKILL.md
+++ b/skills/a0-development/SKILL.md
@@ -1,6 +1,6 @@
---
name: a0-development
-description: "Develop Agent Zero itself: framework, tools, API/WebUI, prompts, runtimes and DOX."
+description: "Develop or operate Agent Zero: projects, chats, tasks, framework, tools and API/WebUI."
version: 1.1.0
author: Agent Zero Team
tags: ["development", "framework", "agent-zero", "extending", "tools", "extensions", "skills", "api", "agents", "prompts", "dox"]
@@ -22,11 +22,19 @@ trigger_patterns:
- "prompt system"
- "agent profile"
- "dox"
+ - "manage Agent Zero projects"
+ - "create Agent Zero chat"
+ - "Agent Zero API"
+ - "create project"
+ - "activate project"
+ - "project instructions"
+ - "create chat"
+ - "new chat"
---
# Agent Zero Development
-Use this skill as the entry point for Agent Zero framework development. It is intentionally lean: load only the reference files that match the task, then verify against the current repository before changing code.
+Use this skill to develop Agent Zero or operate an existing instance on the user's behalf. For projects, chats, tasks, and other application features, read `references/operate-agent-zero.md` and use existing APIs. Load only the references needed for the task; verify current source before changing code.
## Reality Rules
@@ -48,6 +56,7 @@ Load references with:
| Need | Read |
|---|---|
+| Operate Agent Zero for the user: projects, chats, tasks, profiles, skills and settings | `references/operate-agent-zero.md` |
| Runtime split, root layout, discovery order, path and port boundaries | `references/architecture-runtime.md` |
| DOX edit workflow, when to update docs, file-level DOX checks | `references/dox-workflow.md` |
| Tool contracts, locations, prompts, and verification | `references/tools.md` |
@@ -58,7 +67,7 @@ Load references with:
## Working Flow
-1. Classify the request: tool, extension, API/WebUI, profile, prompt, skill, project, plugin, runtime, or docs.
+1. Distinguish operating existing features from developing new behavior. For application operations, follow `references/operate-agent-zero.md`; the remaining steps apply to source changes.
2. Read the root `AGENTS.md`, then the nearest child `AGENTS.md` files for the target paths.
3. Read the focused reference file from this skill.
4. Inspect the current source files named by the reference before making a claim or patch.
diff --git a/skills/a0-development/references/AGENTS.md b/skills/a0-development/references/AGENTS.md
index 0b913600c..ab79efa9d 100644
--- a/skills/a0-development/references/AGENTS.md
+++ b/skills/a0-development/references/AGENTS.md
@@ -11,7 +11,8 @@
- `dox-workflow.md` owns the edit and closeout workflow for DOX-governed changes.
- `tools.md` owns core and plugin tool development contracts.
- `extensions.md` owns backend and frontend extension contracts.
-- `api-webui.md` owns HTTP API, WebSocket, and WebUI extension guidance.
+- `api-webui.md` owns HTTP API handler, WebSocket, and WebUI extension development guidance.
+- `operate-agent-zero.md` owns authenticated API usage and project, chat, task, and application-operation workflows.
- `agents-prompts-skills-projects.md` owns profiles, prompt fragments, skills, and project metadata guidance.
- `plugins-workflow.md` owns plugin-first placement and handoff guidance.
@@ -20,6 +21,7 @@
- Every reference file must list source anchors or DOX anchors that can be checked in the repository.
- Prefer pointing to narrower `AGENTS.md` files instead of copying long subtree contracts.
- Keep examples minimal and compatible with the current helper classes.
+- Operation examples must distinguish HTTP payloads from agent-tool arguments, identify scope and side effects, and verify returned IDs/state.
- Do not include hardcoded default WebUI ports or environment-specific credentials.
## Work Guidance
diff --git a/skills/a0-development/references/api-webui.md b/skills/a0-development/references/api-webui.md
index 7ee2e4cd6..2b9bff0e6 100644
--- a/skills/a0-development/references/api-webui.md
+++ b/skills/a0-development/references/api-webui.md
@@ -55,6 +55,10 @@ Return a Flask `Response` for files, redirects, custom status codes, and plain t
Direct files under `api/*.py` require matching `api/*.py.dox.md`.
+## Calling The WebUI API
+
+To use existing features on the user's behalf, read [Operate Agent Zero](operate-agent-zero.md). It covers session authentication and CSRF, project/chat/task workflows, exact ID fields, and result verification. This reference covers implementing API and WebUI behavior.
+
## WebSocket Handlers
WebSocket handlers live in `api/ws_*.py` or plugin API folders and derive from `helpers.ws.WsHandler`:
diff --git a/skills/a0-development/references/operate-agent-zero.md b/skills/a0-development/references/operate-agent-zero.md
new file mode 100644
index 000000000..dadba67f2
--- /dev/null
+++ b/skills/a0-development/references/operate-agent-zero.md
@@ -0,0 +1,197 @@
+# Operate Agent Zero
+
+Agent Zero can use its own HTTP API to operate existing application features for the user: create and manage projects, create chats, select profiles, start work, manage scheduled tasks, and use plugin features. A request such as "create a project and start a research chat in it" can be completed directly through these APIs.
+
+Use an available agent tool when it already handles the requested operation, such as scheduling. Use the application API for administration or features without a suitable tool. Follow the user's requested scope and existing permissions; an HTTP route is not a way around blocked capabilities. Routine steps needed for an authorized outcome do not need separate confirmation.
+
+Compose existing features to complete the outcome: a research workspace can combine project instructions, a Researcher chat, and a saved recurring task; a new custom profile can be created through Agent Editor, selected in a fresh chat, and given its assignment. Persist the returned IDs, verify each transition, and start execution only when the requested outcome includes it.
+
+## Source Anchors
+
+- Routing/auth/CSRF: `/a0/helpers/api.py`, `/a0/helpers/ui_server.py`, `/a0/api/csrf_token.py`.
+- Projects: `/a0/api/projects.py`, `/a0/helpers/projects.py`.
+- Chats: `/a0/api/chat_create.py`, `/a0/api/agent_profile_set.py`, `/a0/api/poll.py`, `/a0/helpers/state_snapshot.py`.
+- Starting work: `/a0/api/message.py`, `/a0/api/message_async.py`, `/a0/api/api_message.py`.
+- Tasks: `/a0/api/scheduler_task_create.py`, `/a0/api/scheduler_task_update.py`, `/a0/helpers/task_scheduler.py`.
+- Other routes: `/a0/api/` and `/a0/plugins/<plugin>/api/`; inspect each handler and its nearest DOX before unfamiliar operations.
+
+## Connect To The Correct Instance
+
+Discover the origin from the running instance, Docker mapping, or explicit configuration. From a container, `localhost` means that container, not the user's host. Do not assume the host-published port is also the internal port. See `architecture-runtime.md`.
+
+Most WebUI endpoints require a session and CSRF token, even for POST requests that only read data:
+
+1. Reuse an authorized authenticated session. If login is enabled, the normal login is form POST `/login` with `username` and `password`; use configured or user-authorized credentials and retain the session cookies.
+2. GET `/api/csrf_token` from the same origin and cookie jar. From a terminal client, include `Origin` or `Referer`.
+3. Retain the returned cookies and send the returned `token` as `X-CSRF-Token` on subsequent requests.
+4. Keep credentials, tokens, session cookies, and returned secret/configuration fields out of chat and logs.
+
+With login disabled, session cookies and CSRF are still required for protected routes. A successful HTTP response containing the login HTML is not an API success. Keep authentication and CSRF enabled.
+
+This standard-library client works with a session cookie jar. Set `A0_WEBUI_ORIGIN` to the verified origin; authenticate the same client before fetching CSRF if login is enabled.
+
+```python
+import http.cookiejar
+import json
+import os
+import urllib.request
+
+origin = os.environ["A0_WEBUI_ORIGIN"].rstrip("/")
+cookies = http.cookiejar.CookieJar()
+client = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cookies))
+csrf = None
+
+def api(path, payload=None):
+ headers = {"Origin": origin, "Content-Type": "application/json"}
+ if csrf:
+ headers["X-CSRF-Token"] = csrf
+ request = urllib.request.Request(
+ origin + "/api/" + path,
+ data=None if payload is None else json.dumps(payload).encode(),
+ headers=headers,
+ )
+ with client.open(request, timeout=30) as response:
+ if response.headers.get_content_type() != "application/json":
+ raise RuntimeError("Expected JSON; check origin and session login")
+ result = json.load(response)
+ if result.get("ok") is False or result.get("success") is False or result.get("error"):
+ raise RuntimeError("API operation failed; inspect its error privately")
+ return result
+
+csrf = api("csrf_token")["token"]
+```
+
+HTTP errors raise exceptions. Some handlers return HTTP 200 with an `error` or `ok: false`; check the body too. Others return data without an `ok` field. After a timeout, inspect state before retrying a create or start request: the server may already have accepted it.
+
+## Identify Scope Before Acting
+
+Use `POST /api/poll` with `{}` to discover `contexts` and `tasks`. Context records include `id`, `name`, `project`, `agent_profile`, `running`, and `paused`. Match the requested target or use an ID returned by your own earlier call. Do not assume the newest chat is the current/user-requested chat. If the target remains ambiguous, clarify it.
+
+A separate shell Python process does not share the WebUI process's in-memory `AgentContext` objects. Importing `AgentContext` there is not a substitute for HTTP calls to the running server.
+
+IDs are not interchangeable:
+
+| Operation | Request ID field | Returned identity |
+|---|---|---|
+| `chat_create` | Optional `new_context`, `current_context` | `ctxid` |
+| `projects` activate/deactivate | `context_id`; activate also needs project `name` | Verify through `poll` |
+| `agent_profile_set` | `context_id`, `agent_profile` | `agent_profile` |
+| `message_async`, `poll`, `history_get`, `pause`, `stop`, `chat_remove` | `context` | Context-dependent response |
+| `chat_export` | `ctxid` | `ctxid`, `content` |
+| `scheduler_task_update`, `scheduler_task_run`, `scheduler_task_delete` | `task_id` | Use `task.uuid` from creation/listing |
+
+## Projects And Chats
+
+Creating a project creates its workspace and metadata. Activating it assigns that project to a particular chat. There is no single global "active project" for every chat.
+
+Project operations use POST `/api/projects`:
+
+| `action` | Other fields | Purpose |
+|---|---|---|
+| `list`, `list_options` | None | Discover project names/titles |
+| `load` | `name` | Read editable project data |
+| `create` | `project` object with `name`, title/instructions as needed | Create workspace |
+| `clone` | `project` with `name`, `git_url`, optional `git_token` | Clone a repository as a project |
+| `update` | `project` with existing `name` and edits | Update project metadata/instructions |
+| `activate` | `context_id`, `name` | Assign project to chat |
+| `deactivate` | `context_id` | Clear chat's project assignment |
+| `file_structure` | `name`, optional `settings` | Inspect project tree |
+| `delete` | `name` | Delete project files and detach its chats |
+
+List before create; reuse a matching project when that is what the user wants. Choose a fresh, simple directory name for a new project. Load before updates and preserve unrelated fields, especially variables, secrets, MCP settings, and plugin-owned metadata. Do not print a whole loaded project object.
+
+Example: ensure a project exists, then create an idle chat in it. Replace the illustrative name/title/instructions with the requested values.
+
+```python
+name = "research-workspace"
+existing = api("projects", {"action": "list"})["data"]
+if not any(project["name"] == name for project in existing):
+ created = api("projects", {
+ "action": "create",
+ "project": {"name": name, "title": "Research Workspace",
+ "description": "Research and source notes",
+ "instructions": "Cite sources and distinguish evidence from inference."},
+ })
+ name = created["data"]["name"]
+
+ctxid = api("chat_create", {})["ctxid"]
+api("projects", {"action": "activate", "context_id": ctxid, "name": name})
+snapshot = api("poll", {"context": ctxid, "log_from": 0, "notifications_from": 0})
+chat = next(item for item in snapshot["contexts"] if item["id"] == ctxid)
+assert chat["project"]["name"] == name
+```
+
+`chat_create` can inherit project and model override from `current_context`, subject to settings. Omit that field for an independent chat; activate the intended project explicitly. `new_context` may supply a fresh ID, but reusing an existing ID does not guarantee a new chat. Creation alone does not run a model or guarantee that the user's currently selected browser tab switches to it.
+
+For a specialized chat, list available profiles and then call:
+
+```python
+api("agent_profile_set", {"context_id": ctxid, "agent_profile": "researcher"})
+```
+
+Use an available profile ID in that project's scope and verify `agent_profile` through `poll`. The endpoint rejects profile changes while a chat is running. Creating a profile and selecting it for a chat are separate operations.
+
+## Start, Observe, And Control Chat Work
+
+- `POST /api/message_async` with `{"context": ctxid, "text": "<assigned work>"}` starts processing and returns acceptance plus `context`; it does not return task completion.
+- `POST /api/message` uses the same payload but waits for the model result. Do not synchronously call it against the same chat that is making the request.
+- Poll the target with `context`, `log_from`, and `notifications_from`; inspect its `running` state and logs, then use `history_get` or `chat_export` for results. Reset cursors when log/notification GUIDs change. Use bounded polling rather than a tight loop.
+- `pause` uses `{"context": ctxid, "paused": true}`; `false` resumes. `stop` terminates the current run. `chat_reset` resets the conversation; `chat_remove` deletes it and can remove tasks bound to that context.
+- Message queue endpoints (`message_queue_add`, `message_queue_remove`, `message_queue_send`) support follow-ups. Inspect their handlers before use; queued messages may later be consumed by the running agent.
+
+Starting a chat run or manually running a saved task consumes model resources and may execute tools. Do it when requested or needed for the user's assigned outcome, not as a side effect of merely creating or inspecting a chat. Send independent work to another chat and avoid recursive delegation back to the caller.
+
+The external API is a different contract: `POST /api/api_message` uses `X-API-KEY` with `message`, optional `context_id`, `project_name`, `agent_profile`, and attachments. It waits for a result and returns `context_id`/`response`. Its project/profile options apply when creating a context; it is not the general WebUI session API. Check `/a0/api/api_message.py` rather than mixing its fields with `message_async`.
+
+## Saved Tasks And Schedules
+
+Prefer the `scheduler` tool when available; load `scheduled-tasks` for detailed scheduling. The HTTP API also manages the same saved tasks, including a project association selected at creation.
+
+- List: POST `scheduler_tasks_list` with `{}`; result is `tasks`.
+- Create: POST `scheduler_task_create` with `name`, `prompt`, optional `system_prompt`, `attachments`, and `project_name`.
+- Type is selected by payload: a nonempty `schedule` creates a recurring task; otherwise a nonempty `plan` creates a planned task; neither creates an adhoc task. Do not send both.
+- Recurring `schedule` is an object with cron strings `minute`, `hour`, `day`, `month`, `weekday`, plus an IANA `timezone`. Use the user's intended timezone.
+- HTTP planned shape is `{"plan": {"todo": ["<future ISO datetime with UTC offset>"]}}`, not the scheduler tool's list shorthand. Verify returned planned dates.
+- Update: POST `scheduler_task_update` with `task_id` and changed fields such as `name`, `prompt`, `schedule`, `plan`, or `state`. `state: "disabled"` disables; `state: "idle"` re-enables.
+- Run now: POST `scheduler_task_run` with `task_id`. Acceptance is not completion; check the returned task and later list state/results.
+- Delete: POST `scheduler_task_delete` with `task_id`. This also handles a running task and its dedicated context.
+
+Creation uses a dedicated context; `project_name` cannot be changed through the update endpoint. Top-level `timezone` also updates runtime localization, so use explicit planned offsets or `schedule.timezone` when that is the intended scope. Do not copy tool-only fields such as `dedicated_context` into HTTP payloads and assume they are honored.
+
+For a saved draft that must not run automatically, create an adhoc task and disable it:
+
+```python
+task = api("scheduler_task_create", {
+ "name": "Research draft", "prompt": "<work to run when requested>",
+ "project_name": name,
+})["task"]
+task_id = task["uuid"]
+api("scheduler_task_update", {"task_id": task_id, "state": "disabled"})
+saved = next(t for t in api("scheduler_tasks_list", {})["tasks"] if t["uuid"] == task_id)
+assert saved["state"] == "disabled"
+```
+
+Do not use a due recurring schedule as a draft and hope to disable it before execution. Do not reset/delete the caller's own active chat to manage another task.
+
+## Other Application Features
+
+These are discovery starting points, not interchangeable payloads. Read the handler and the corresponding skill before changing state. Plugin routes depend on the plugin being enabled.
+
+| Feature | API entry point | Guidance |
+|---|---|---|
+| Profile catalog and editor | `agents` (`action: list`); `plugins/_agent_editor/agent_editor` | Editor supports scoped list/load, quick_create, plan/save and lifecycle operations. Inspect its plan before applying complex edits. Use `a0-create-agent` for creation. |
+| Skills | `skills`; `plugins/_skills/skills_catalog` | Catalog manages per-chat visibility and activation. Loading adds instructions to history; hiding is not unloading, and deactivate/clear are rejected. |
+| Slash commands | `plugins/_commands/commands` | List effective commands by `context_id`; get/save/duplicate/delete in the intended scope. Use `commands-create-slash-command`. |
+| Plugins | `plugins_list`, `plugins` | Inspect configuration and activation by plugin/project/profile. Use `a0-manage-plugin`; plugin execution/install/removal has wider effects than reading configuration. |
+| Files | `get_work_dir_files`, `edit_work_dir_file`, upload/download/rename endpoints | Several reads use GET/query parameters; uploads use multipart. Use the appropriate file/Office tool when available. |
+| Settings and MCP | `settings_get`, `settings_set`, `mcp_servers_status`, `mcp_servers_apply` | Scope changes carefully; preserve unowned settings and secrets. Do not treat a global settings update as a chat-only change. |
+| Backups and updates | `backup_*`, `self_update_*`, `restart` | Inspect previews/defaults and source contracts. Restore, restart and self-update can disrupt other work; perform only for the requested maintenance outcome. |
+| Notifications | `notification_create`, `notifications_history`, `notifications_mark_read` | Use the notification tool when available; avoid clearing other notifications as cleanup. |
+
+For a feature not listed here, find the WebUI's actual request and read the matching handler. Do not guess routes from button labels or emulate state by editing scheduler/chat/project storage behind the running server.
+
+## Verify And Report
+
+Check the returned identity and read back the actual state: project name, chat project/profile, task UUID/state, or saved feature configuration. Distinguish created, activated, started, completed, and visible in the user's selected UI. Report what happened and provide the relevant names/IDs without dumping private state.
+
+For smoke tests, use unique disposable records, avoid model execution unless required, and delete only records created by the test. Verify cleanup through the same listing endpoints. A successful CRUD test does not prove a model run, scheduled execution, external integration, or every listed feature works.