Skip to content

Agent Zero AI framework

Overlap embedding warm-up with startup watchdogs

Alessandrobea0c16d50d4
diff --git a/AGENTS.md b/AGENTS.md
index c149fc113..b9fc089ac 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,7 +22,7 @@
- Native function calls use canonical call content for history and combine public response text with calls for repeat comparison. The canonical history content passes through the normal history template/masking hook; provider output metadata remains intact.
- `initialize.py` owns framework initialization.
- `models.py` owns model-provider configuration and LiteLLM integration. `get_api_key_raw()` reads the stored key or key list for settings/editing; `get_api_key()` selects a runtime key and runs provider extension hooks.
-- Local sentence-transformers load only on an embedding cache miss, not when importing `models`. `run_ui.init_a0` starts the deferred preload before chat restoration and then allows up to ten seconds for it to finish before later startup hooks compete for CPU. This caps only the extra preload wait; chat restoration and extension hooks are outside that deadline. Timeout leaves preload running, so a first chat can still wait for an uncached model. Waiting is best-effort: timeout or task failure does not prevent HTTP startup, and extensions may disable preload. Initialization extension hooks remain in control. `preload.py` constructs the configured local embedding model in a worker thread; it must not import unused speech runtimes or block the shared background event loop.
+- Local sentence-transformers load only on an embedding cache miss, not when importing `models`. `run_ui.init_a0` starts deferred preload before chat restoration and returns a completion callback so its end hooks (including watchdog registration) overlap warmup. `run` invokes that callback, allowing up to ten additional seconds for preload before starting MCP and the job loop, then HTTP. Chat restoration and extension hooks are outside this wait limit. Timeout leaves preload running, so a first chat can still wait for an uncached model. Waiting is best-effort: timeout or task failure does not prevent HTTP startup. Initialization hooks may disable preload or suppress completion; disabled preload still allows MCP/jobs, while a skipped initializer skips them. `preload.py` constructs the configured local embedding model in a worker thread; it must not import unused speech runtimes or block the shared background event loop.
- `models._merge_provider_defaults` merges YAML-declared `extra_body` defaults with legacy top-level values for those declared fields and explicit nested overrides, in that order; unrelated kwargs and original-provider API-key selection remain intact.
- `models.apply_rate_limiter` skips token counting and returns no limiter when all request, input, and output limits are unset; any configured limit retains normal accounting.
- `requirements.txt` includes HTTPX's SOCKS extra so framework clients support SOCKS proxy environment variables before plugin setup.
diff --git a/run_ui.py b/run_ui.py
index 0e91c0748..59ad553de 100644
--- a/run_ui.py
+++ b/run_ui.py
@@ -16,7 +16,9 @@ def run():
server_runtime, host, port = prepare_web_runtime()
PrintStyle().print("Initializing Agent Zero components...")
- init_a0()
+ finish_init = init_a0()
+ if callable(finish_init):
+ finish_init()
PrintStyle().print("Starting UI/API server...")
start_web_server(server_runtime, host, port)
@@ -77,17 +79,21 @@ def init_a0():
init_chats = initialize.initialize_chats()
init_chats.result_sync()
- # Give the first chat a warm model without waiting indefinitely on downloads.
- if init_preload:
- try:
- init_preload.result_sync(timeout=10)
- except TimeoutError:
- pass
- except Exception as e:
- PrintStyle().error(f"Error waiting for preload: {e}")
-
- initialize.initialize_mcp()
- initialize.initialize_job_loop()
+ def finish_init():
+ # Give the first chat a warm model without waiting indefinitely on downloads.
+ if init_preload:
+ try:
+ init_preload.result_sync(timeout=10)
+ except TimeoutError:
+ pass
+ except Exception as e:
+ PrintStyle().error(f"Error waiting for preload: {e}")
+
+ initialize.initialize_mcp()
+ initialize.initialize_job_loop()
+
+ # Let end hooks run during warmup before waiting and starting MCP/jobs.
+ return finish_init
if __name__ == "__main__":
diff --git a/tests/test_embedding_model_preload.py b/tests/test_embedding_model_preload.py
index c9582727b..e716f1cfb 100644
--- a/tests/test_embedding_model_preload.py
+++ b/tests/test_embedding_model_preload.py
@@ -39,13 +39,26 @@ def _clear_local_embedding_models():
models._LOCAL_EMBEDDING_MODELS.clear()
+def startup_runtime(monkeypatch):
+ import run_ui
+
+ monkeypatch.setattr(run_ui, "configure_process_environment", lambda: None)
+ monkeypatch.setattr(run_ui, "run_migration_checks", lambda: None)
+ monkeypatch.setattr(run_ui, "prepare_web_runtime", lambda: (None, "localhost", 0))
+ monkeypatch.setattr(run_ui, "start_web_server", lambda *_args: None)
+ return run_ui
+
+
@pytest.mark.parametrize("skip_init", [False, True])
-def test_runtime_preload_overlaps_chat_restoration_within_extension_hooks(monkeypatch, skip_init):
+def test_runtime_preload_overlaps_chat_restoration_within_extension_hooks(monkeypatch, skip_init, startup_runtime):
import run_ui
calls = []
def extension_hook(point, agent, data):
+ if not point.startswith("_functions/run_ui/init_a0/"):
+ return
calls.append(point.rsplit("/", 1)[-1])
if skip_init and point.endswith("/start"):
data["result"] = None
@@ -68,15 +81,15 @@ def test_runtime_preload_overlaps_chat_restoration_within_extension_hooks(monkey
monkeypatch.setattr(run_ui.initialize, "initialize_mcp", lambda: calls.append("mcp"))
monkeypatch.setattr(run_ui.initialize, "initialize_job_loop", lambda: calls.append("jobs"))
- run_ui.init_a0()
+ run_ui.run()
assert calls == (["start", "end"] if skip_init else [
- "start", "preload", "chats", "preload_ready", "mcp", "jobs", "end",
+ "start", "preload", "chats", "end", "preload_ready", "mcp", "jobs",
])
@pytest.mark.parametrize("error", [None, TimeoutError(), RuntimeError("preload failed")])
-def test_runtime_preload_wait_remains_best_effort(monkeypatch, error):
+def test_runtime_preload_wait_remains_best_effort(monkeypatch, error, startup_runtime):
import run_ui
calls = []
@@ -97,16 +110,16 @@ def test_runtime_preload_wait_remains_best_effort(monkeypatch, error):
)
monkeypatch.setattr(run_ui.initialize, "initialize_mcp", lambda: calls.append("mcp"))
monkeypatch.setattr(run_ui.initialize, "initialize_job_loop", lambda: calls.append("jobs"))
- monkeypatch.setattr(run_ui, "PrintStyle", lambda: SimpleNamespace(error=errors.append))
+ monkeypatch.setattr(run_ui, "PrintStyle", lambda: SimpleNamespace(print=lambda _: None, error=errors.append))
- run_ui.init_a0()
+ run_ui.run()
assert calls == ["chats", "mcp", "jobs"]
assert errors == (["Error waiting for preload: preload failed"] if isinstance(error, RuntimeError) else [])
@pytest.mark.parametrize("blocked_stage", ["construction", "encoding"])
-def test_startup_continues_after_ten_seconds_with_model_still_loading(monkeypatch, blocked_stage, record_property):
+def test_startup_continues_after_ten_seconds_with_model_still_loading(monkeypatch, blocked_stage, record_property, startup_runtime):
import preload
import run_ui
from helpers import persist_chat
@@ -152,13 +165,13 @@ def test_startup_continues_after_ten_seconds_with_model_still_loading(monkeypatc
monkeypatch.setattr(run_ui.initialize, "initialize_mcp", lambda: later_startup.append("mcp"))
monkeypatch.setattr(run_ui.initialize, "initialize_job_loop", lambda: later_startup.append("jobs"))
monkeypatch.setattr(preload, "PrintStyle", lambda: SimpleNamespace(print=lambda _: None, error=errors.append))
- monkeypatch.setattr(run_ui, "PrintStyle", lambda: SimpleNamespace(error=errors.append))
+ monkeypatch.setattr(run_ui, "PrintStyle", lambda: SimpleNamespace(print=lambda _: None, error=errors.append))
_clear_local_embedding_models()
# Release blocked work even if a regression removes the startup timeout.
with ThreadPoolExecutor(max_workers=1) as pool:
started = time.monotonic()
- startup = pool.submit(run_ui.init_a0)
+ startup = pool.submit(run_ui.run)
try:
assert blocked.wait(3)
assert chats_loaded.wait(3)
@@ -186,7 +199,7 @@ def test_startup_continues_after_ten_seconds_with_model_still_loading(monkeypatc
@pytest.mark.parametrize("scenario", ["cached", "missing", "broken", "remote", "busy_restoration"])
-def test_real_preload_startup_handles_ready_or_unavailable_models(monkeypatch, scenario, record_property):
+def test_real_preload_startup_handles_ready_or_unavailable_models(monkeypatch, scenario, record_property, startup_runtime):
import preload
import run_ui
from helpers import persist_chat
@@ -234,14 +247,14 @@ def test_real_preload_startup_handles_ready_or_unavailable_models(monkeypatch, s
monkeypatch.setattr(run_ui.initialize, "initialize_mcp", lambda: calls.append("mcp"))
monkeypatch.setattr(run_ui.initialize, "initialize_job_loop", lambda: calls.append("jobs"))
monkeypatch.setattr(preload, "PrintStyle", lambda: SimpleNamespace(print=lambda _: None, error=errors.append))
- monkeypatch.setattr(run_ui, "PrintStyle", lambda: SimpleNamespace(error=errors.append))
+ monkeypatch.setattr(run_ui, "PrintStyle", lambda: SimpleNamespace(print=lambda _: None, error=errors.append))
_clear_local_embedding_models()
if scenario == "cached":
models.get_embedding_model(config.provider, config.name)
with ThreadPoolExecutor(max_workers=1) as pool:
started = time.monotonic()
- startup = pool.submit(run_ui.init_a0)
+ startup = pool.submit(run_ui.run)
try:
assert chats_started.wait(2)
if scenario == "busy_restoration":
@@ -484,3 +497,68 @@ async def test_preload_skips_remote_models_and_contains_local_failures(monkeypat
else:
assert calls == []
assert errors == []
+
+
+def test_watchdog_setup_overlaps_real_warmup_before_mcp_and_http(monkeypatch, startup_runtime):
+ import preload
+ import run_ui
+ from helpers import persist_chat
+ from helpers.defer import EventLoopThread
+ from plugins._model_config.helpers import model_config
+
+ model_started = threading.Event()
+ release_model = threading.Event()
+ preload_done = threading.Event()
+ calls = []
+ config = models.ModelConfig(
+ models.ModelType.EMBEDDING, "huggingface", "sentence-transformers/overlap-test"
+ )
+
+ class Model:
+ def __init__(self, *_args, **_kwargs):
+ model_started.set()
+ assert release_model.wait(5)
+
+ def encode(self, inputs, **_kwargs):
+ calls.append("model_warmed")
+ return [[1.0] for _ in inputs]
+
+ def extension_hook(point, agent, data):
+ if point.endswith("/initialize_preload/end"):
+ data["result"].add_done_callback(lambda _: preload_done.set())
+ if point.endswith("/init_a0/end"):
+ assert model_started.wait(2)
+ assert not preload_done.is_set()
+ calls.append("watchdogs_start")
+ release_model.set()
+ assert preload_done.wait(2)
+ calls.append("watchdogs_end")
+
+ monkeypatch.setitem(sys.modules, "sentence_transformers", SimpleNamespace(SentenceTransformer=Model))
+ monkeypatch.setattr(model_config, "get_embedding_model_config_object", lambda: config)
+ monkeypatch.setattr(models, "get_provider_config", lambda *_args: None)
+ monkeypatch.setattr(models, "get_api_key_raw", lambda *_args: "None")
+ monkeypatch.setattr(run_ui.extension, "call_extensions_sync", extension_hook)
+ monkeypatch.setattr(persist_chat, "load_tmp_chats", lambda: calls.append("chats"))
+ monkeypatch.setattr(run_ui.initialize, "initialize_mcp", lambda: calls.append("mcp"))
+ monkeypatch.setattr(run_ui.initialize, "initialize_job_loop", lambda: calls.append("jobs"))
+ monkeypatch.setattr(run_ui, "start_web_server", lambda *_args: calls.append("http"))
+ _clear_local_embedding_models()
+ try:
+ run_ui.run()
+ assert calls == ["chats", "watchdogs_start", "model_warmed", "watchdogs_end", "mcp", "jobs", "http"]
+ finally:
+ release_model.set()
+ assert preload_done.wait(2)
+ EventLoopThread().terminate()
+ _clear_local_embedding_models()
+
+
+def test_runtime_accepts_extension_skip_result(monkeypatch, startup_runtime):
+ import run_ui
+
+ calls = []
+ monkeypatch.setattr(run_ui, "init_a0", lambda: True)
+ monkeypatch.setattr(run_ui, "start_web_server", lambda *_args: calls.append("http"))
+ run_ui.run()
+ assert calls == ["http"]