Integrate Hub Agent

Integrating a GAIA Hub Agent

This repo's hub/ ships pre-built agents, each packaged for a developer to drop into their own application. The work: learn the layout and the two integration shapes, pin down which agent they mean, then hand off to that agent's own guidance — where the real, current, agent-specific steps live.

The recipe is agent-agnostic. Any agent named below (e.g. npm agent-email) is a labeled example of its shape, never the subject. Discover the real agent set live — never trust a hardcoded list.

Step 1 — Discover the current agents

Hub agents are one directory per agent, with a runtime subdir inside: hub/agents/<name>/<runtime>/. List the tree now rather than assuming — the set changes:

ls hub/agents/                 # one dir per agent (e.g. gaia, chat, email, …)
ls hub/agents/email/           # an agent's runtimes (e.g. python, npm; cpp when present)

Treat whatever the listing returns as authoritative. A missing runtime subdir just means the agent doesn't ship that shape today. hub/agents/README.md is a useful catalog of the python set and the example agents (hello-world, word-count, connectors-demo) if the developer is unsure what's available.

Step 2 — Identify which agent the developer wants

Pin down a single <name>/<runtime> before integrating:

• If the developer named an agent ("the email agent", "GAIA"), match it against the listing. Several names can diverge — watch for it: the friendly name, the directory (<name>), the registry id in gaia-agent.yaml, and the package/module names (the flagship's python module is gaia_agent, not gaia_agent_gaia; its npm package is @amd-gaia/gaia). The directory is how you find the package; the id is what you pass when invoking a python agent (Step 3).
• The same capability can ship in more than one runtime (the email agent is npm agent-email and python email). Confirm the runtime, since it picks the shape: a JS/TS/Electron app wants the npm package; a Python app wants the python package.
• If they described a capability ("triage my inbox", "analyze a CSV"), skim candidate agents' gaia-agent.yaml description/tags (python) or package.json description (npm) to find the match, then confirm with the developer.

Step 3 — Know the two integration shapes

They are genuinely different. Use the shape to set expectations, but the agent's own docs (Step 4) are the source of truth for exact calls.

npm agents (hub/agents/<name>/npm/)

The package is a client for a local native sidecar. Shape:

1. npm install the package (it is typically ESM-only — import, not require).
2. Fetch + SHA-256-verify the platform binary (a build-time step), then spawn it as a local HTTP sidecar and wait for health.
3. Call the package's typed TypeScript client methods against the running sidecar.
4. Shut the sidecar down on exit (packages may also auto-reap on process exit).

No Python, no separate GAIA install — the frozen binary carries the agent. The sidecar usually serves same-origin only, so an Electron renderer drives it via main-process IPC, not a cross-origin fetch. The agent still needs a local model backend (Lemonade Server) for inference. Reference example: npm agent-email.

python agents (hub/agents/<name>/python/)

The package is a GAIA framework plugin, not a sidecar. Shape:

1. pip install gaia-agent-<id> (it depends on the published amd-gaia wheel).
2. Installing auto-registers the agent into the GAIA registry via the gaia.agent entry-point group (declared in pyproject.toml) — no hardcoded list, no manual wiring. The registry discovers it on import.
3. Invoke it through GAIA per the agent's gaia-agent.yaml manifest and README.md. The manifest declares the id, the models it expects, and which interfaces it exposes (cli / api_server / mcp_server / pipe) — drive it through whichever the app uses, plus any required env/config. For in-process embedding, the base Agent entry point is process_query(text) -> dict; construct the agent directly (its package exports the class + a *Config) or resolve it by id with the registry — which must be populated first: r = AgentRegistry(); r.discover(); r.create_agent("<id>") (discover() scans the gaia.agent entry points; without it the registry is empty and create_agent raises ValueError). Confirm the exact entry against the agent's own source (Step 4) rather than assuming — config knobs vary per agent.

The npm sidecar/binary lifecycle (fetch-binary, spawn, shutdown, typed HTTP client) does not apply here — don't describe a python agent as a sidecar. Depth varies by agent; describe only what the agent's own artifacts support rather than padding it to match npm's lifecycle.