vrr/agent-zero
2
0
Fork 0
mirror of https://github.com/agent0ai/agent-zero.git synced 2026-06-01 14:21:59 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
agent-zero/api/AGENTS.md
frdel 175baa49db Add AGENTS.md DOX files and migrate docs 
Introduce DOX (AGENTS.md) contracts across the repository to formalize ownership and local work contracts: adds .github/AGENTS.md plus AGENTS.md files for agents, api, conf, docker, docs, extensions, helpers, knowledge, lib, plugins, prompts, scripts, skills, tests, tools, usr, webui (and several subfolders). Update root AGENTS.md (content and last-updated date) to include DOX framework guidance and a child DOX index. Update .gitignore to allow usr/ and usr/plugins AGENTS.md files. Remove legacy deep-dive files under docs/agents (banners, components, modals, plugins) and migrate frontend/plugin references to webui/ and plugins/ DOX locations. Also adjust plugins/README.md and several skills/*/SKILL.md files to align with the new DOX layout.
2026-06-01 13:55:07 +02:00

1.8 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.

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.

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.

Child DOX Index

No child DOX files.