vrr/agent-zero
2
0
Fork 0
mirror of https://github.com/agent0ai/agent-zero.git synced 2026-07-09 17:08:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
agent-zero/api/AGENTS.md
frdel e138e33ca9 Add file-level DOX docs & update AGENTS indexes 
Add comprehensive file-level DOX documentation across the repo and update directory AGENTS.md indexes. Many new `*.py.dox.md` files were added under api, helpers, tools, plugins, extensions, webui, and other dirs to document endpoint purpose, ownership, runtime contracts, work guidance, and verification. Several AGENTS.md files were created or updated (agents profiles, api, docker, extensions, helpers, plugins, skills, webui components, etc.) to list child DOX files and clarify documentation/work guidance. Also add example and bundled profile DOX files (agent0, default, developer, hacker, researcher) and minor updates to helpers/dirty_json.py and its tests. These changes improve on-disk documentation coverage and establish the convention that each direct runtime file should have a matching `*.dox.md` describing its contracts and verification steps.
2026-06-08 12:41:53 +02:00

2.6 KiB
Raw Blame History

API Handlers DOX

Purpose

  • Own backend HTTP API handlers and WebSocket handler entry points.
  • Keep route-level behavior, authentication, CSRF, input parsing, and response shapes explicit.

Ownership

  • Files in this directory are discovered by the route registration layer in helpers/api.py and WebSocket registration code.
  • ws_*.py files define WebSocket namespaces or handlers through helpers.ws.WsHandler.
  • Plugin-provided API handlers belong inside plugin api/ folders and follow the same base contracts.

Local Contracts

  • HTTP handlers must derive from helpers.api.ApiHandler.
  • Implement async def process(self, input: dict, request: Request) -> dict | Response.
  • Override get_methods(), requires_auth(), requires_csrf(), requires_api_key(), or requires_loopback() only when the endpoint contract requires it.
  • Keep CSRF and authentication protections intact for browser-facing state-changing endpoints.
  • WebSocket handlers must derive from helpers.ws.WsHandler and validate event data before using it.
  • Do not return secrets, raw environment values, private files, or unfiltered exception details to clients.
  • This directory is a file-documented DOX profile: every direct *.py endpoint or WebSocket module must have a same-directory *.py.dox.md file named by appending .dox.md to the full Python filename.
  • The *.py.dox.md file owns endpoint purpose, request/response concepts, auth/CSRF/API-key/loopback assumptions, side effects, important helper dependencies, and verification guidance.
  • When a Python endpoint is added, removed, renamed, or behaviorally changed, update its matching *.py.dox.md in the same change.
  • Do not leave stale file-level DOX after endpoint deletion or rename.

Work Guidance

  • Use helpers for shared behavior instead of duplicating persistence, auth, file, project, plugin, or notification logic in endpoints.
  • Keep request and response payloads stable; update frontend callers and tests together when payloads change.
  • Prefer Response for files, redirects, status codes, and plain-text errors; return dictionaries for JSON success payloads.
  • During the DOX pass, verify that every direct *.py file has a matching *.py.dox.md and that changed endpoint behavior is described there.

Verification

  • Run targeted pytest tests/test_*api*.py, endpoint-specific tests, or WebSocket tests after changing handler behavior.
  • For auth, CSRF, upload/download, tunnel, or file endpoints, run the nearest security regression tests.
  • Check file-level documentation coverage with a script or shell loop that verifies each api/*.py has a matching api/*.py.dox.md.

Child DOX Index

No child DOX files.