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/extensions/python/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

4.4 KiB
Raw Blame History

Python Extensions DOX

Purpose

  • Own built-in backend lifecycle extensions under extensions/python/.
  • Keep Python hook behavior compatible with helpers.extension.call_extensions_async and call_extensions_sync.

Ownership

  • Each direct subdirectory is one named extension point.
  • Python files inside an extension point are loaded in deterministic filename order.
  • Implicit @extensible hook implementations use _functions/<module>/<qualname>/<start|end>/ layout when present.

Local Contracts

  • Extension functions must match the arguments supplied by their hook point.
  • Preserve numeric prefixes when ordering affects prompt construction, stream masking, persistence, or cleanup.
  • Use AgentContext from agent when context access is needed.
  • Do not log unmasked secrets, raw hidden prompt sections, or private user data.

Work Guidance

  • Keep extension modules import-light; many hooks run during hot paths.
  • Use mutable ctx or data dictionaries according to the hook contract when rewriting content.
  • Add or update tests when a hook changes prompt content, message history, tool output, streaming, or persistence behavior.

Verification

  • Run targeted tests for the affected lifecycle area.
  • Run a startup smoke check for agent_init, startup_migration, or system_prompt changes when practical.

Child DOX Index

Direct child DOX files:

Child Scope
_functions/AGENTS.md Implicit @extensible backend hook implementations.
agent_init/AGENTS.md Agent context initialization hooks.
banners/AGENTS.md Backend banner and discovery-card contributions.
before_main_llm_call/AGENTS.md Pre-main-model-call behavior.
error_format/AGENTS.md Error formatting and masking behavior.
hist_add_before/AGENTS.md Pre-history-insertion masking behavior.
hist_add_tool_result/AGENTS.md Tool-result history side effects.
job_loop/AGENTS.md Periodic backend maintenance jobs.
message_loop_end/AGENTS.md End-of-message-loop history and persistence behavior.
message_loop_prompts_after/AGENTS.md Prompt extras appended after message-loop prompt construction.
message_loop_prompts_before/AGENTS.md Pre-prompt-construction message-loop gates.
message_loop_start/AGENTS.md Start-of-message-loop iteration state.
monologue_end/AGENTS.md End-of-monologue UI and cleanup behavior.
monologue_start/AGENTS.md Start-of-monologue behavior such as chat renaming.
process_chain_end/AGENTS.md Process-chain completion and queued-message handling.
reasoning_stream/AGENTS.md Full reasoning stream handling.
reasoning_stream_chunk/AGENTS.md Reasoning stream chunk masking.
reasoning_stream_end/AGENTS.md Reasoning stream finalization.
response_stream/AGENTS.md Full assistant response stream handling.
response_stream_chunk/AGENTS.md Assistant response chunk masking.
response_stream_end/AGENTS.md Assistant response stream finalization.
startup_migration/AGENTS.md Startup migrations.
system_prompt/AGENTS.md Core system prompt section construction.
tool_execute_after/AGENTS.md Post-tool-execution processing.
tool_execute_before/AGENTS.md Pre-tool-execution processing.
user_message_ui/AGENTS.md User-visible UI message hooks.
util_model_call_before/AGENTS.md Pre-utility-model-call masking.
webui_ws_connect/AGENTS.md WebUI WebSocket connect behavior.
webui_ws_disconnect/AGENTS.md WebUI WebSocket disconnect behavior.
webui_ws_event/AGENTS.md Incoming WebUI WebSocket event behavior.