agent-zero/AGENTS.md

Agent Zero DOX

Purpose

• Own project-wide engineering rules and the top-level DOX index.
• Keep detailed contracts in the closest applicable child AGENTS.md.

Project

• Stack: Python 3.12+ framework, Python 3.13 agent execution runtime, Flask, Alpine.js, LiteLLM, and Socket.IO.
• Start the WebUI with python run_ui.py; discover its URL from startup output, Docker mappings, or explicit configuration rather than assuming a port.
• Run the full test suite with pytest or a focused file with pytest tests/test_name.py.
• Human-facing documentation lives in README.md and docs/.

Root Ownership

• agent.py owns Agent, AgentContext, and loop data.
• initialize.py owns framework initialization.
• models.py owns model-provider configuration and LiteLLM integration.
• run_ui.py is the WebUI entry point.
• DockerfileLocal must remain compatible with the contracts under docker/.
• Runtime or user state under usr/ and tmp/ is intentionally outside tracked DOX unless the user explicitly asks otherwise.

Project-Wide Contracts

• Import AgentContext and AgentContextType from agent, not helpers.context.
• Never commit secrets, .env files, API keys, tokens, or private user data.
• Preserve authentication and CSRF protections.
• Use Linux paths and commands in examples.
• When a live Dockerized Agent Zero target is explicitly named, verify that exact runtime instead of assuming a fixed localhost port.
• 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.
• 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.
• Copy live core-plugin changes back into tracked source under plugins/.
• Develop new custom plugins under ignored usr/plugins/; tracked bundled plugins live under plugins/.
• Use the framework runtime for backend and plugin-hook verification, not the separate agent execution runtime.

Permissions

Allowed without asking:

• Read repository files.
• Update files under usr/.

Ask before:

• Installing dependencies.
• Deleting core files outside usr/ or tmp/.
• Modifying agent.py or initialize.py.
• Creating commits or pushing branches.

DOX Workflow

• AGENTS.md files are binding contracts for their subtrees.
• 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.
• 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.
• Create a child AGENTS.md only for a durable boundary with distinct ownership or workflow.
• Child docs should use: Purpose, Ownership, Local Contracts, Work Guidance, Verification, and Child DOX Index.
• After every meaningful change, re-check the affected paths, update the closest owning docs and indexes, remove stale guidance, and run relevant verification.
• Do not document ignored usr/ or tmp/ changes unless explicitly requested.
• Keep DOX concise, current, operational, and free of diary entries or duplicated parent guidance.

Child DOX Index

Child	Scope
.github/AGENTS.md	GitHub Actions workflows and release automation scripts.
agents/AGENTS.md	Bundled agent profiles, profile-local prompts, and tools.
api/AGENTS.md	HTTP API and WebSocket handler entry points.
conf/AGENTS.md	Repository-shipped configuration defaults and templates.
docker/AGENTS.md	Docker build contexts, images, compose files, and runtime layout.
docs/AGENTS.md	Human-facing documentation and screenshots.
extensions/AGENTS.md	Backend and WebUI lifecycle extensions.
helpers/AGENTS.md	Shared backend utilities and runtime services.
knowledge/AGENTS.md	Built-in agent self-knowledge.
lib/AGENTS.md	Lightweight browser-side helpers outside the WebUI bundle.
plugins/AGENTS.md	Bundled system plugins and custom-plugin architecture.
prompts/AGENTS.md	Core prompt templates.
scripts/AGENTS.md	Repository maintenance scripts and automation inputs.
skills/AGENTS.md	Bundled Agent Zero skills.
tests/AGENTS.md	Pytest regression and contract tests.
tools/AGENTS.md	Core agent tool implementations.
webui/AGENTS.md	Alpine.js WebUI shell, components, JavaScript, CSS, and assets.

Intentionally unindexed local or generated roots:

Path	Reason
.conda/, .venv/	Local Python environments.
.pytest_cache/, __pycache__/	Generated test and bytecode caches.
.vscode/, .windsurf/	Editor-local configuration and assistant metadata.
tmp/	Ignored runtime caches, uploads, and generated work.
usr/	Ignored local user data, settings, plugins, chats, and workdirs.
python/	Generated or legacy runtime mirror; current source is in root modules and tracked source directories.