Skip to content

fix(hub): report file-based custom agents' real health, not always 'error'#2277

Merged
kovtcharov merged 1 commit into
mainfrom
autofix/issue-2268
Jul 18, 2026
Merged

fix(hub): report file-based custom agents' real health, not always 'error'#2277
kovtcharov merged 1 commit into
mainfrom
autofix/issue-2268

Conversation

@github-actions

Copy link
Copy Markdown
Contributor

Every file-based custom agent (~/.gaia/agents/<id>/agent.py) reported HEALTH: error in gaia agent status, even when it ran perfectly — the first thing a user sees after authoring an agent told them their working agent was broken. Now gaia agent status reports a custom agent's health from whether it can actually be loaded: a working agent shows healthy, and a genuinely broken one (e.g. one that never implements _register_tools) still shows error with a cause that names the real failure.

Closes #2268

Test plan

  • python -m pytest tests/unit/test_hub_lifecycle.py -x passes
  • python util/lint.py --all passes
  • Create a working custom agent at ~/.gaia/agents/<id>/agent.py (with AGENT_ID, AGENT_NAME, and a _register_tools implementation) and confirm gaia agent status reports it healthy
  • Remove that agent's _register_tools and confirm gaia agent status reports it error with a cause naming _register_tools
🔍 Technical details

Root cause. _default_loader() in src/gaia/hub/lifecycle.py knew only two probes: builtin (presence in the registry) and installed-wheel (gaia.agent setuptools entry point). File-based custom agents (source == "custom_python") are exec'd directly from disk and have no entry point by construction, so the loader always fell through to the wheel branch and raised "installed on disk but exposes no 'gaia.agent' entry point" — reporting error for all of them unconditionally.

Health signal — discoverable, hardened to concrete. For custom_python the signal is the registry's own successful discovery (module imported, Agent subclass found), the same way a registered builtin is proof it loaded. Discovery alone isn't enough, though: an agent that never implements the abstract _register_tools imports and registers fine but can never be constructed. So the new branch also inspects cls.__abstractmethods__ and raises (→ error) naming the unimplemented method(s). This deliberately does not construct the agent — per the issue's constraint, gaia agent status must not trigger constructor side effects. (gaia agent run/#2242 remains the "constructible" test; this is the lighter "discoverable + concrete" one.)

Changes.

  • src/gaia/hub/lifecycle.py_default_loader gains a custom_python branch before the wheel probe; builtin and wheel paths are untouched.
  • src/gaia/agents/registry.pyAgentRegistration gains an optional agent_class field, populated in _load_python_agent from the already-imported class. This surfaces the discovered class to the health check with no re-import/no construction; it stays None for builtins/installed wheels (lazy-import factories), which the branch never reads.
  • tests/unit/test_hub_lifecycle.py — covers concrete custom agent → healthy, abstract custom agent → error naming _register_tools, the class-absent defensive fallback, plus builtin and installed-wheel regression probes.

Verified. tests/unit/test_hub_lifecycle.py (23 passed) and tests/unit/agents/test_registry.py pass; python util/lint.py --all --fix clean.

…rror'

gaia agent status ran the installed-wheel entry-point probe against every
custom_python agent, which have no entry point by construction, so all of
them reported HEALTH: error even when they run fine. Add a custom_python
branch to _default_loader: the registry's own successful discovery is the
health signal (same as builtin), hardened by an __abstractmethods__ check so
an agent that never implements _register_tools still reports error naming the
real cause — without constructing the agent.

Closes #2268
@kovtcharov
kovtcharov added this pull request to the merge queue Jul 18, 2026
Merged via the queue into main with commit 4f888b7 Jul 18, 2026
28 checks passed
@kovtcharov
kovtcharov deleted the autofix/issue-2268 branch July 18, 2026 23:45
kovtcharov added a commit that referenced this pull request Jul 18, 2026
@itomek itomek mentioned this pull request Jul 22, 2026
9 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug] Every file-based custom agent reports HEALTH: error in gaia agent status, even when it works

2 participants