Skip to content

Agent Zero AI framework

Add extensible decorator and cache controls

frdeld82b121bc9a1
diff --git a/agent.py b/agent.py
index 0633005ea..b682b0bed 100644
--- a/agent.py
+++ b/agent.py
@@ -1,7 +1,4 @@
import asyncio, random, string, threading
-import nest_asyncio
-
-nest_asyncio.apply()
from collections import OrderedDict
from dataclasses import dataclass, field
diff --git a/initialize.py b/initialize.py
index ea8ea606d..296d2d4f5 100644
--- a/initialize.py
+++ b/initialize.py
@@ -1,9 +1,10 @@
from agent import AgentConfig
import models
-from python.helpers import runtime, settings, defer
+from python.helpers import runtime, settings, defer, extension
from python.helpers.print_style import PrintStyle
def initialize_agent(override_settings: dict | None = None):
current_settings = settings.get_settings()
if override_settings:
@@ -118,12 +119,14 @@ def initialize_agent(override_settings: dict | None = None):
# return config object
return config
def initialize_chats():
from python.helpers import persist_chat
async def initialize_chats_async():
persist_chat.load_tmp_chats()
return defer.DeferredTask().start_task(initialize_chats_async)
def initialize_mcp():
set = settings.get_settings()
async def initialize_mcp_async():
@@ -131,14 +134,17 @@ def initialize_mcp():
return _initialize_mcp(set["mcp_servers"])
return defer.DeferredTask().start_task(initialize_mcp_async)
def initialize_job_loop():
from python.helpers.job_loop import run_loop
return defer.DeferredTask("JobLoop").start_task(run_loop)
def initialize_preload():
import preload
return defer.DeferredTask().start_task(preload.preload)
def initialize_migration():
from python.helpers import migration, dotenv
# run migration
diff --git a/python/helpers/api.py b/python/helpers/api.py
index eab60baa7..afa357e21 100644
--- a/python/helpers/api.py
+++ b/python/helpers/api.py
@@ -17,8 +17,7 @@ from python.helpers import files, cache
ThreadLockType = Union[threading.Lock, threading.RLock]
CACHE_AREA = "api_handlers(api)(plugins)"
-CACHE_ENABLED = False
-
+cache.toggle_area(CACHE_AREA, False) # cache off for now
Input = dict
Output = Union[Dict[str, Any], Response, TypedDict] # type: ignore
@@ -210,10 +209,9 @@ def register_api_route(app: Flask, lock: ThreadLockType) -> None:
async def _dispatch(path: str) -> BaseResponse:
# Return cached wrapped handler if available
- if CACHE_ENABLED:
- cached = cache.get(CACHE_AREA, path)
- if cached is not None:
- return await cached()
+ cached = cache.get(CACHE_AREA, path)
+ if cached is not None:
+ return await cached()
# Resolve file path for the handler
# Try built-in api folder first, then plugin api folders
@@ -261,8 +259,7 @@ def register_api_route(app: Flask, lock: ThreadLockType) -> None:
if handler_cls.requires_loopback():
handler_fn = requires_loopback(handler_fn)
- if CACHE_ENABLED:
- cache.add(CACHE_AREA, path, handler_fn)
+ cache.add(CACHE_AREA, path, handler_fn)
return await handler_fn()
app.add_url_rule(
diff --git a/python/helpers/cache.py b/python/helpers/cache.py
index eeee64a4a..0c0e5911f 100644
--- a/python/helpers/cache.py
+++ b/python/helpers/cache.py
@@ -5,8 +5,22 @@ from typing import Any
_lock = threading.RLock()
_cache: dict[str, dict[str, Any]] = {}
+_enabled_global: bool = True
+_enabled_areas: dict[str, bool] = {}
+
+
+def toggle_global(enabled: bool) -> None:
+ global _enabled_global
+ _enabled_global = enabled
+
+
+def toggle_area(area: str, enabled: bool) -> None:
+ _enabled_areas[area] = enabled
+
def add(area: str, key: str, data: Any) -> None:
+ if not _is_enabled(area):
+ return
with _lock:
if area not in _cache:
_cache[area] = {}
@@ -14,11 +28,15 @@ def add(area: str, key: str, data: Any) -> None:
def get(area: str, key: str, default: Any = None) -> Any:
+ if not _is_enabled(area):
+ return default
with _lock:
return _cache.get(area, {}).get(key, default)
def remove(area: str, key: str) -> None:
+ if not _is_enabled(area):
+ return
with _lock:
if area in _cache:
_cache[area].pop(key, None)
@@ -38,3 +56,9 @@ def clear(area: str) -> None:
def clear_all() -> None:
with _lock:
_cache.clear()
+
+
+def _is_enabled(area: str) -> bool:
+ if not _enabled_global:
+ return False
+ return _enabled_areas.get(area, True)
diff --git a/python/helpers/extension.py b/python/helpers/extension.py
index 72e080535..c07b8546f 100644
--- a/python/helpers/extension.py
+++ b/python/helpers/extension.py
@@ -1,7 +1,11 @@
from abc import abstractmethod
from typing import Any
from python.helpers import extract_tools, files
+from python.helpers import cache
from typing import TYPE_CHECKING
+from functools import wraps
+import asyncio
+import inspect
if TYPE_CHECKING:
from agent import Agent
@@ -10,13 +14,123 @@ if TYPE_CHECKING:
DEFAULT_EXTENSIONS_FOLDER = "python/extensions"
USER_EXTENSIONS_FOLDER = "usr/extensions"
-_cache: dict[str, list[type["Extension"]]] = {}
+_CACHE_AREA = "extension_folder_classes(extensions)(plugins)"
+cache.toggle_area(_CACHE_AREA, False) # cache off for now
+
+
+class _Unset:
+ pass
+
+
+_UNSET = _Unset()
+
+
+# decorator to enable implicit extension points in existing functions
+def extensible(func):
+ """Make a function emit two implicit extension points around its execution.
+
+ The decorator derives two extension point names from the wrapped function:
+
+ - ``{func.__module__}.{func.__name__}-start``
+ - ``{func.__module__}.{func.__name__}-end``
+
+ When the wrapped function is called, the decorator builds a mutable ``data``
+ payload and passes it to both extension points via ``call_extensions``:
+
+ - ``data["args"]``: the original positional arguments tuple
+ - ``data["kwargs"]``: the original keyword arguments dict
+ - ``data["result"]``: initialized to an internal sentinel; extensions may
+ set this to short-circuit the wrapped function
+ - ``data["exception"]``: initialized to an internal sentinel; extensions may
+ set this to a ``BaseException`` instance to force-raise
+
+ Behavior:
+
+ - ``-start`` extensions run first and may mutate ``data["args"]`` /
+ ``data["kwargs"]``, set ``data["result"]`` to skip calling ``func``, or set
+ ``data["exception"]`` to abort by raising.
+ - If ``data["result"]`` is still unset, the decorator calls ``func`` (awaiting
+ it if it is async) and stores either the return value into ``data["result"]``
+ or the raised error into ``data["exception"]``.
+ - ``-end`` extensions run last and may further transform the outcome by
+ rewriting ``data["result"]`` or replacing/clearing ``data["exception"]``.
+
+ Finally, if ``data["exception"]`` contains an exception it is raised;
+ otherwise ``data["result"]`` is returned.
+ """
+ @wraps(func)
+ async def _inner_async(*args, **kwargs):
+ from agent import Agent
+
+ # prepare extension points data
+ module_name = getattr(func, "__module__", "")
+ func_name = getattr(func, "__name__", "")
+ start_point = f"{module_name}.{func_name}-start"
+ end_point = f"{module_name}.{func_name}-end"
+
+ # try to find agent instance for better extension determination
+ agent = kwargs.get("agent")
+ if (not agent or not isinstance(agent, Agent)) and args:
+ try:
+ for a in args:
+ if isinstance(a, Agent):
+ agent = a
+ break
+ except Exception:
+ agent = None
+
+ # build extension data object - func input/output
+ data = {
+ "args": args,
+ "kwargs": kwargs,
+ "result": _UNSET,
+ "exception": _UNSET,
+ }
+
+ # call start extensions, these can modify inputs, produce output or exception
+ await call_extensions(start_point, agent=agent, data=data)
+
+ # if there is an explicit exception set, raise it
+ exc = data.get("exception")
+ if isinstance(exc, BaseException):
+ raise exc
+
+ # if there is no result set, call the original function
+ if data.get("result") is _UNSET:
+ try:
+ if inspect.iscoroutinefunction(func):
+ data["result"] = await func(*args, **kwargs)
+ else:
+ data["result"] = func(*args, **kwargs)
+ except Exception as e:
+ data["exception"] = e
+
+ # call end extensions, these can modify outputs or exception
+ await call_extensions(end_point, agent=agent, data=data)
+
+ # if there's an exception, raise it
+ exc = data.get("exception")
+ if isinstance(exc, BaseException):
+ raise exc
+
+ # if there's a result, return it
+ result = data.get("result")
+ return None if result is _UNSET else result
+
+ if inspect.iscoroutinefunction(func):
+ return _inner_async
+
+ @wraps(func)
+ def _inner_sync(*args, **kwargs):
+ return asyncio.run(_inner_async(*args, **kwargs))
+
+ return _inner_sync
class Extension:
def __init__(self, agent: "Agent|None", **kwargs):
- self.agent: "Agent" = agent # type: ignore < here we ignore the type check as there are currently no extensions without an agent
+ self.agent: "Agent|None" = agent
self.kwargs = kwargs
@abstractmethod
@@ -30,10 +144,14 @@ async def call_extensions(
from python.helpers import projects, subagents, plugins
# search for extension folders in all agent's paths
- paths = subagents.get_paths(agent, "extensions", extension_point, default_root="python")
+ paths = subagents.get_paths(
+ agent, "extensions", extension_point, default_root="python"
+ )
# Add plugin backend extension paths (plugins/*/extensions/python/{extension_point})
- plugin_paths = plugins.get_enabled_plugin_paths(agent, "extensions", "python", extension_point)
+ plugin_paths = plugins.get_enabled_plugin_paths(
+ agent, "extensions", "python", extension_point
+ )
paths.extend(p for p in plugin_paths if p not in paths)
all_exts = [cls for path in paths for cls in _get_extensions(path)]
@@ -58,14 +176,14 @@ def _get_file_from_module(module_name: str) -> str:
def _get_extensions(folder: str):
- global _cache
folder = files.get_abs_path(folder)
- if folder in _cache:
- classes = _cache[folder]
- else:
- if not files.exists(folder):
- return []
- classes = extract_tools.load_classes_from_folder(folder, "*", Extension)
- _cache[folder] = classes
+ cached = cache.get(_CACHE_AREA, folder)
+ if cached is not None:
+ return cached
+
+ if not files.exists(folder):
+ return []
+ classes = extract_tools.load_classes_from_folder(folder, "*", Extension)
+ cache.add(_CACHE_AREA, folder, classes)
return classes
diff --git a/python/helpers/runtime.py b/python/helpers/runtime.py
index dc2de961e..ed5fbace4 100644
--- a/python/helpers/runtime.py
+++ b/python/helpers/runtime.py
@@ -8,6 +8,9 @@ import asyncio
import threading
import queue
import sys
+import nest_asyncio
+
+nest_asyncio.apply()
T = TypeVar("T")
R = TypeVar("R")