Agent Hub Restructure

Tracking issue: #1102 · Milestone: v0.22.0 — Agent Hub Platform [OSS] · Status: In Progress

Migration status

Step 1 (mixin promotion) and the registry’s installed-agent discovery are landed. Production agents are migrating to hub/agents/<id>/python/ in batches.

Agent(s)	Status	Package
`summarize`, `sd`, `docker`, `jira`, `fileio`, `blender`, `emr`	✅ Migrated	`gaia-agent-<id>` under `hub/agents/<id>/python/`
`chat` (chat/doc/file profiles + lite), `analyst` (data), `browser` (web), `docqa`, `email`, `code`, `routing`, `connectors-demo`	⏳ Pending	still in `src/gaia/agents/`

The pending set is deferred because of deeper coupling: chat/doc/file sit on the Agent UI hot path (13+ callsites), email has a large API/MCP/eval surface, code↔routing are interdependent, and docqa depends on chat.tools. They migrate once their callsites are rewired through the registry. gaia-code stays as a core console script until code moves. Migrated agents install as standalone wheels (pip install gaia-agent-<id> or pip install -e hub/agents/<id>/python) and are discovered via the gaia.agent entry-point group. The core amd-gaia wheel no longer ships them; in-core callsites lazy-import each agent and fail loudly when the wheel is absent.

Problem

Production agents (chat, code, jira, blender, etc.) currently live inside src/gaia/agents/ and ship as part of the core amd-gaia wheel. This couples every agent to the framework’s release cycle, prevents independent versioning, and gives third-party contributors no pattern to follow — their agents would have to live inside the AMD source tree.

Goal

Move production agents to hub/agents/ as standalone packages that depend on the published amd-gaia PyPI package — not the source tree. The core wheel ships only the framework. Third-party contributors follow the identical pattern AMD uses for its own agents.

Before:                          After:
src/gaia/agents/                 src/gaia/agents/        ← framework only
├── base/        (framework)     ├── base/
├── tools/       (framework)     ├── tools/              ← + promoted shared mixins
├── registry.py  (framework)     ├── registry.py
├── builder/     (framework)     ├── builder/
├── chat/        (agent) ──┐     └── __init__.py
├── code/        (agent)   │
├── jira/        (agent)   │     hub/agents/
└── ...          (agent) ──┘     ├── python/
                                 │   ├── chat/           ← standalone package
                                 │   │   ├── gaia-agent.yaml
                                 │   │   ├── pyproject.toml   (depends on amd-gaia)
                                 │   │   ├── gaia_agent_chat/
                                 │   │   ├── tests/
                                 │   │   └── README.md
                                 │   └── ...
                                 └── cpp/
                                     └── ...

Key Decisions

Framework-only core wheel. pip install amd-gaia provides Agent, @tool, MCPAgent, AgentConsole, registry, LLM clients, RAG, MCP. No production agents.
Agents are separate wheels. gaia-agent-chat, gaia-agent-jira, gaia-agent-code, etc. — installable via gaia agent install <id>, pip install gaia-agent-{id}, or amd-gaia[agents] for all of them. One wheel per codebase, not per registry ID: the chat package ships multiple prompt profiles (doc, file, data, web) and model presets (lite variants) selectable via config — they are not separate wheels (see #1162).
Shared tool mixins promoted to framework. RAG, FileIO, Shell, CodeIndex mixins move into src/gaia/agents/tools/ so agents don’t depend on each other for tools.
Entry-point discovery. Agents register via the gaia.agent entry point group. The registry discovers installed agent wheels at startup — no hardcoded agent list.
Framework-provided generic server. src/gaia/agents/base/server.py wraps any Agent into an OpenAI-compatible REST API + MCP stdio server. Agents don’t implement server logic.
Inherited init. An agent declares what it needs — a model id, a minimum backend version — and the framework serves GET/POST /v1/<id>/init for it. Agents don’t hand-write readiness or provisioning endpoints. See Inherited init.

Pre-requisite: Promote shared tool mixins

The current codebase has cross-agent tool dependencies that block independent packaging:

Mixin	Currently in	Used by	New location
`RAGToolsMixin`	`agents/chat/tools/rag_tools.py`	ChatAgent, DocQAAgent	`agents/tools/rag_tools.py`
`FileIOToolsMixin`	`agents/code/tools/file_io.py`	ChatAgent, CodeAgent, DocQA, FileIO	`agents/tools/file_io_tools.py`
`ShellToolsMixin`	`agents/chat/tools/shell_tools.py`	ChatAgent, FileIOAgent	`agents/tools/shell_tools.py`
`CodeIndexToolsMixin`	`agents/code_index/tools/mixin.py`	CodeAgent	`agents/tools/code_index_tools.py`

After promotion, every KNOWN_TOOLS entry in registry.py points to gaia.agents.tools.*. No agent-specific tool paths remain. Old paths get deprecated re-exports for backward compatibility.

Package Format

`gaia-agent.yaml`

id: chat
name: Chat
type: agent                         # agent | app | component — defaults to agent when omitted
                                    # (`skill` is a catalog lane too, but a skill is published
                                    #  from its SKILL.md, not from a gaia-agent.yaml)
version: 0.1.0                      # independent of framework version
description: "General conversation — fast, personality-first"
author: AMD
license: MIT

category: conversation
tags: [chat, general, personality]
icon: message-circle
tools_count: 0

language: python                    # python | cpp | go | typescript
min_gaia_version: "0.18.0"
models: [Qwen3.5-35B-A3B-GGUF]

requirements:
  min_memory_gb: 8
  min_lemonade_version: "10.2.0"   # optional; SemVer. The backend floor a
                                   # readiness check compares against.
  platforms: [win-x64, linux-x64, darwin-arm64]

interfaces:
  tui: true
  cli: true
  pipe: true
  api_server: true
  mcp_server: true

Non-agent packages

Not every hub package is an agent. type discriminates them, and two ship today:

Package	`type`	`language`	What it is
`terminal-hub`	`component`	`go`	The `gaia tui` binary — six platform builds
`agent-ui`	`app`	`typescript`	The Electron desktop app installers

Their manifests live in hub/components/<id>/gaia-agent.yaml and publish through the same POST /publish path as an agent — release_components.yml builds (or collects) the per-platform artifacts and posts them with the manifest. Both host or drive agents rather than being one, so they declare tools_count: 0 and no models. A catalog consumer that lists agents must filter on type; treating every entry as an agent would offer gaia agent install terminal-hub, which is not how either is installed.

The skills lane

skill is a fourth type (#2467) — a reusable capability any agent composes, not a package that runs on its own. It is the one lane that is not published from a gaia-agent.yaml: a skill’s manifest is the YAML front matter of its SKILL.md (Skill Format), so it goes to POST /publish/skill instead, and a gaia-agent.yaml that declares type: skill is rejected with a pointer to that route. Skill artifacts live under their own R2 prefix (skills/<name>/…) and are served at GET /skills/<name>/manifest.json. Everything else is shared: skills appear in the same index.json agents array, carry the same security_tier / permissions keys, and are versioned and made immutable by the same rules. Ids are one namespace across every lane — a skill may not shadow an agent id, and vice versa (409 id_conflict). The same filtering rule applies, harder: a skill installs with gaia skill install <name> into ~/.gaia/skills/, so a consumer that renders every entry as an installable agent would offer an install path that cannot work.

`pyproject.toml`

[project]
name = "gaia-agent-chat"
version = "0.1.0"
dependencies = ["amd-gaia>=0.18.0"]

[project.entry-points."gaia.agent"]
chat = "gaia_agent_chat.agent:ChatAgent"

Agents with cross-agent dependencies (e.g. RoutingAgent uses CodeAgent) declare them as package dependencies: dependencies = ["amd-gaia>=0.18.0", "gaia-agent-code>=0.1.0"].

Inherited init

An agent that needs a model before it can answer anything should not have to hand-write a readiness endpoint to say so. It declares the requirement and AgentServer serves both verbs at /v1/<id>/init:

Verb	Effect	Status
`GET`	Read-only readiness probe. Reports backend reachability, version compatibility, and whether the declared model is downloaded — with an actionable `hint` per failure.	`200` ready · `503` not ready, same body either way
`POST`	Provisioning. Tells an already-running backend to download the declared model, streaming newline-terminated progress.	`503` before streaming if the backend is down · otherwise a committed `200`

Declare requirements in gaia-agent.yaml (models: and requirements.min_lemonade_version), or pass them explicitly:

from gaia.agents.base.readiness import AgentRequirements
from gaia.agents.base.server import AgentServer

server = AgentServer(
    MyAgent(),
    agent_id="my-agent",
    requirements=AgentRequirements(
        model_id="Gemma-4-E4B-it-GGUF",
        min_backend_version="10.2.0",
    ),
)

An agent that declares nothing gets no init routes — a readiness endpoint that reports “ready” without having checked anything is worse than a 404, because a consumer would trust it.

Where the boundary sits

Inherited init makes this agent’s requirements ready: its model, against a backend that is already running. Installing the backend stays with gaia init. An agent process cannot bootstrap the server it depends on, so when Lemonade is unreachable both verbs fail loudly and name whose job the fix is rather than hanging or half-succeeding:

✗ The local Lemonade Server is not reachable at http://127.0.0.1:9099/api/v1.
✗ Start it with `lemonade-server serve` (or run `gaia init`), then POST to this path again.
✗ My Agent can't install the backend itself — that's a host prerequisite.

Reading a provisioning result

Once a streamed 200 is committed the HTTP status can no longer change, so a pull that fails half-way still arrives as 200 OK. The final line is the verdict — ✓ success, ✗ failure, ⚠ succeeded-but-unverified. Consumers must read it rather than the status code; the TUI’s preflight gate (tui/internal/ui/preflight) already does. Two distinctions the contract preserves deliberately, because each has a different remedy:

“Could not tell” is not “missing.” If the backend answers /health but its model list cannot be read, present:false means unknown — reporting it as missing would send the user to re-download a model they may already have.
Indeterminate is not a pass. A backend that advertises no version yields compatible: null, never true.

Implementation Steps

Promote shared tool mixins (#1396)

Move RAG, FileIO, Shell, CodeIndex mixins to src/gaia/agents/tools/. Update all imports and KNOWN_TOOLS. Add deprecated re-exports. Run full test suite — no behavior change.

Create agent package skeletons

For each of the 16 agents, create hub/agents/{id}/python/ with gaia-agent.yaml, pyproject.toml, gaia_agent_{id}/ package dir, tests/, and README.md.

Move first agent (summarize)

Start with summarize — simplest, fewest dependencies. Proves the pattern end-to-end before bulk migration.

Move remaining agents in batches

Migrate the other 15 agents. Rewrite internal imports (gaia.agents.{name} → gaia_agent_{name}). Framework imports stay. Cross-agent deps become package deps.

Strip the core wheel

Remove agent packages from setup.py. Remove gaia-emr/gaia-code console scripts. Add amd-gaia[agents] and per-agent extras.

Update the registry

_register_builtin_agents() keeps only builder. Add _discover_installed_agents() using the gaia.agent entry point group.

Update CLI / UI / API callsites

Replace ~16 direct agent imports in cli.py, ui/_chat_helpers.py, ui/agent_loop.py, and apps with registry.create_agent(id).

Add framework generic server

src/gaia/agents/base/server.py wraps any Agent into REST API + MCP server. Enables gaia agent run <id> --api and --mcp, and serves the agent’s inherited init routes.

Add CI/CD workflow

.github/workflows/build_agents.yml matrix-builds the C++ agent binaries; .github/workflows/publish_agents.yml matrix-builds every Python agent wheel (matrix derived from setup.py’s agents extra via util/list_agent_packages.py) and publishes it to PyPI on a v* tag using pypa/gh-action-pypi-publish with skip-existing: true (PyPI-native version immutability). R2 publishing is handled at author time by gaia agent publish.

Relocate tests

Move agent-specific tests to hub/agents/{id}/python/tests/. Framework tests stay in tests/.

Legacy Agent Modernization

Several agents predate the Agent UI and the connectors framework. They work only via standalone CLI/app entry points, aren’t in the registry, lack the modern class attributes, and have no web UI presence. Moving them to hub/agents/ is not enough — they must also be modernized to the Agent Hub package standard.

Agent	Registered?	Standalone CLI/app	Modern class attrs	Status
chat, analyst, browser	✅ (factory)	—	factory-based	Modern
email, connectors-demo	✅	email has `cli.py`	✅ full attrs + connectors	Modern
builder	✅ (hidden)	—	factory-based	Modern
jira	❌	—	❌	Legacy
docker	❌	— (MCPAgent base)	❌	Legacy
blender	❌	`app.py`	❌	Legacy
sd	❌	—	❌	Legacy
emr	❌	`cli.py` + `gaia-emr`	❌	Legacy
code	entry_points only	`cli.py` + `gaia-code`	❌	Partial
docqa, fileio, summarize	❌	—	❌	Example/util
routing	❌	—	not an `Agent` subclass	Utility (keep as-is)

Modernization per legacy agent (tracked in #1397):

Add modern class attributes: AGENT_ID, AGENT_NAME, AGENT_DESCRIPTION, CONVERSATION_STARTERS, and REQUIRED_CONNECTORS where applicable (e.g. jira → Atlassian OAuth).
Author the gaia-agent.yaml manifest (category, icon, tags, requirements, interfaces) so the agent renders as a Hub card.
Register via the gaia.agent entry point — discoverable in the web UI, not just standalone CLI.
Adopt the conversational/streaming response mode so the agent works in the chat surface.
Keep the standalone CLI/app as a thin wrapper over the registry-created agent (no duplicate logic).
docker inherits MCPAgent — confirm it composes with the framework server (Step 8) or document why it diverges.

Not modernized: routing stays a utility dispatcher (not user-discoverable). docqa/fileio/summarize are example/building-block agents — summarize becomes the migration pilot (Step 3); docqa/fileio may collapse into the chat profiles (see #1162).

Cross-Agent Dependencies

The exploration found these agent-to-agent couplings that must be resolved:

Dependency	Resolution
RoutingAgent → CodeAgent	`gaia-agent-routing` declares `gaia-agent-code` dependency
ChatAgent → FileIOToolsMixin (from code)	Resolved by mixin promotion (Step 1)
DocQAAgent → RAG + FileIO mixins	Resolved by mixin promotion (Step 1)
FileIOAgent → Shell + FileIO mixins	Resolved by mixin promotion (Step 1)
code/cli.py → RoutingAgent, CodeAgent	Internal to code package, no external visibility

Risks

Risk	Mitigation
252 import references across the codebase break	Promote mixins first (Step 1), then migrate one agent at a time
`pip install amd-gaia` no longer ships agents (breaking change)	`amd-gaia[agents]` extras preserves the “everything” install; document migration
Editable dev workflow friction	`pip install -e hub/agents/{id}/python/` registers via entry points
Registry can’t find agents	Entry-point discovery + `~/.gaia/agents/` scan; fail loudly if an agent’s `min_gaia_version` is unmet

Verification

# Step 1 — mixin promotion, no regressions
python -m pytest tests/ -x

# Step 3 — first agent works as standalone package
pip install -e hub/agents/summarize/python/
gaia agent run summarize --prompt "Summarize this text"
python -m pytest hub/agents/summarize/python/tests/ -xvs

# Step 5 — core wheel is framework-only
pip install -e ".[dev]"        # framework
pip install -e ".[agents]"     # framework + all agents

# Step 8 — generic server
gaia agent run chat --api --port 8080
curl http://localhost:8080/v1/chat/completions \
  -d '{"messages":[{"role":"user","content":"hello"}]}'

# Full integration
gaia agent list
gaia agent run chat --prompt "hello"

Agent Hub UI — the display + distribution platform plan
Agent Hub — original hub vision
#1091 — gaia-agent.yaml manifest parser (unblocked by this restructure)
#1162 — consolidate regular/lite agent variants

What's Next

Agent UI

Ecosystem

Infrastructure

Agents

Agent Hub Restructure

Migration status

Problem

Goal

Key Decisions

Pre-requisite: Promote shared tool mixins

Package Format

`gaia-agent.yaml`

Non-agent packages

The skills lane

`pyproject.toml`

Inherited init

Where the boundary sits

Reading a provisioning result

Implementation Steps

Legacy Agent Modernization

Cross-Agent Dependencies

Risks

Verification

​Migration status

​Problem

​Goal

​Key Decisions

​Pre-requisite: Promote shared tool mixins

​Package Format

​gaia-agent.yaml

​Non-agent packages

​The skills lane

​pyproject.toml

​Inherited init

​Where the boundary sits

​Reading a provisioning result

​Implementation Steps

​Legacy Agent Modernization

​Cross-Agent Dependencies

​Risks

​Verification

​Related

Migration status

Problem

Goal

Key Decisions

Pre-requisite: Promote shared tool mixins

Package Format

`gaia-agent.yaml`

Non-agent packages

The skills lane

`pyproject.toml`

Inherited init

Where the boundary sits

Reading a provisioning result

Implementation Steps

Legacy Agent Modernization

Cross-Agent Dependencies

Risks

Verification

Related