| 1 | # Agent Zero DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own project-wide engineering rules and the top-level DOX index. |
| 6 | - Keep detailed contracts in the closest applicable child `AGENTS.md`. |
| 7 | |
| 8 | ## Project |
| 9 | |
| 10 | - Stack: Python 3.12+ framework, Python 3.13 agent execution runtime, Flask, Alpine.js, LiteLLM, and Socket.IO. |
| 11 | - Start the WebUI with `python run_ui.py`; discover its URL from startup output, Docker mappings, or explicit configuration rather than assuming a port. |
| 12 | - Run the full test suite with `pytest` or a focused file with `pytest tests/test_name.py`. |
| 13 | - Human-facing documentation lives in `README.md` and `docs/`. |
| 14 | |
| 15 | ## Root Ownership |
| 16 | |
| 17 | - `agent.py` owns `Agent`, `AgentContext`, and loop data. |
| 18 | - `initialize.py` owns framework initialization. |
| 19 | - `models.py` owns model-provider configuration and LiteLLM integration. |
| 20 | - `run_ui.py` is the WebUI entry point. |
| 21 | - `DockerfileLocal` must remain compatible with the contracts under `docker/`. |
| 22 | - Runtime or user state under `usr/` and `tmp/` is intentionally outside tracked DOX unless the user explicitly asks otherwise. |
| 23 | |
| 24 | ## Project-Wide Contracts |
| 25 | |
| 26 | - Import `AgentContext` and `AgentContextType` from `agent`, not `helpers.context`. |
| 27 | - Never commit secrets, `.env` files, API keys, tokens, or private user data. |
| 28 | - Preserve authentication and CSRF protections. |
| 29 | - Use Linux paths and commands in examples. |
| 30 | - When a live Dockerized Agent Zero target is explicitly named, verify that exact runtime instead of assuming a fixed localhost port. |
| 31 | - Message-loop completion flows through a response tool with `break_loop`; plain or malformed Chat Completions text enters repair, and native Responses output text is normalized through the same response-tool path. |
| 32 | - Reuse the startup-preloaded local embedding model for matching runtime configurations; wrappers retain their own rate-limit configuration while sharing the underlying inference model. |
| 33 | - Prompt Markdown may retain fenced JSON examples for readability; final system-prompt rendering removes only their JSON fence markers before model calls and preserves non-JSON fences. |
| 34 | - Copy live core-plugin changes back into tracked source under `plugins/`. |
| 35 | - Develop new custom plugins under ignored `usr/plugins/`; tracked bundled plugins live under `plugins/`. |
| 36 | - Use the framework runtime for backend and plugin-hook verification, not the separate agent execution runtime. |
| 37 | |
| 38 | ## Permissions |
| 39 | |
| 40 | Allowed without asking: |
| 41 | |
| 42 | - Read repository files. |
| 43 | - Update files under `usr/`. |
| 44 | |
| 45 | Ask before: |
| 46 | |
| 47 | - Installing dependencies. |
| 48 | - Deleting core files outside `usr/` or `tmp/`. |
| 49 | - Modifying `agent.py` or `initialize.py`. |
| 50 | - Creating commits or pushing branches. |
| 51 | |
| 52 | ## DOX Workflow |
| 53 | |
| 54 | - `AGENTS.md` files are binding contracts for their subtrees. |
| 55 | - Before editing, read this file and every `AGENTS.md` on the path to each target; the closest contract controls local details without weakening parent rules. |
| 56 | - Keep work understandable from the applicable DOX chain. Put project-wide rules here and concrete ownership, workflows, inputs, outputs, side effects, and verification in child docs. |
| 57 | - Create a child `AGENTS.md` only for a durable boundary with distinct ownership or workflow. |
| 58 | - Child docs should use: Purpose, Ownership, Local Contracts, Work Guidance, Verification, and Child DOX Index. |
| 59 | - After every meaningful change, re-check the affected paths, update the closest owning docs and indexes, remove stale guidance, and run relevant verification. |
| 60 | - Do not document ignored `usr/` or `tmp/` changes unless explicitly requested. |
| 61 | - Keep DOX concise, current, operational, and free of diary entries or duplicated parent guidance. |
| 62 | |
| 63 | ## Child DOX Index |
| 64 | |
| 65 | | Child | Scope | |
| 66 | | --- | --- | |
| 67 | | [.github/AGENTS.md](.github/AGENTS.md) | GitHub Actions workflows and release automation scripts. | |
| 68 | | [agents/AGENTS.md](agents/AGENTS.md) | Bundled agent profiles, profile-local prompts, and tools. | |
| 69 | | [api/AGENTS.md](api/AGENTS.md) | HTTP API and WebSocket handler entry points. | |
| 70 | | [conf/AGENTS.md](conf/AGENTS.md) | Repository-shipped configuration defaults and templates. | |
| 71 | | [docker/AGENTS.md](docker/AGENTS.md) | Docker build contexts, images, compose files, and runtime layout. | |
| 72 | | [docs/AGENTS.md](docs/AGENTS.md) | Human-facing documentation and screenshots. | |
| 73 | | [extensions/AGENTS.md](extensions/AGENTS.md) | Backend and WebUI lifecycle extensions. | |
| 74 | | [helpers/AGENTS.md](helpers/AGENTS.md) | Shared backend utilities and runtime services. | |
| 75 | | [knowledge/AGENTS.md](knowledge/AGENTS.md) | Built-in agent self-knowledge. | |
| 76 | | [lib/AGENTS.md](lib/AGENTS.md) | Lightweight browser-side helpers outside the WebUI bundle. | |
| 77 | | [plugins/AGENTS.md](plugins/AGENTS.md) | Bundled system plugins and custom-plugin architecture. | |
| 78 | | [prompts/AGENTS.md](prompts/AGENTS.md) | Core prompt templates. | |
| 79 | | [scripts/AGENTS.md](scripts/AGENTS.md) | Repository maintenance scripts and automation inputs. | |
| 80 | | [skills/AGENTS.md](skills/AGENTS.md) | Bundled Agent Zero skills. | |
| 81 | | [tests/AGENTS.md](tests/AGENTS.md) | Pytest regression and contract tests. | |
| 82 | | [tools/AGENTS.md](tools/AGENTS.md) | Core agent tool implementations. | |
| 83 | | [webui/AGENTS.md](webui/AGENTS.md) | Alpine.js WebUI shell, components, JavaScript, CSS, and assets. | |
| 84 | |
| 85 | Intentionally unindexed local or generated roots: |
| 86 | |
| 87 | | Path | Reason | |
| 88 | | --- | --- | |
| 89 | | `.conda/`, `.venv/` | Local Python environments. | |
| 90 | | `.pytest_cache/`, `__pycache__/` | Generated test and bytecode caches. | |
| 91 | | `.vscode/`, `.windsurf/` | Editor-local configuration and assistant metadata. | |
| 92 | | `tmp/` | Ignored runtime caches, uploads, and generated work. | |
| 93 | | `usr/` | Ignored local user data, settings, plugins, chats, and workdirs. | |
| 94 | | `python/` | Generated or legacy runtime mirror; current source is in root modules and tracked source directories. | |