​

Agent Hub Platform

​

Overview

​

Key Design Decisions

1. Production agents live in hub/agents/. All production agents (chat, doc, file, data, web, email, jira, blender, etc.) are standalone packages in hub/agents/python/ and hub/agents/cpp/. They import gaia from the published PyPI package (amd-gaia), not from the source tree. Third-party contributors follow the identical pattern. src/gaia/agents/ retains only the framework: base classes, shared tool mixins, and the registry.
2. pip install amd-gaia ships the framework only. The core wheel provides Agent, @tool, MCPAgent, AgentConsole, LLM clients, RAG, MCP, etc. Production agents are separate wheels (gaia-agent-chat, gaia-agent-doc, etc.) published to the Hub. A meta-package amd-gaia[agents] installs all AMD production agents for convenience.
3. Manifest file is gaia-agent.yaml. Every agent has a manifest declaring its metadata, version (starting at 0.1.0), system requirements, permissions, interface modes, and Hub display info.
4. C++ agents get a Python backend subprocess launcher so they work in both Electron and web contexts via JSON-RPC over stdio.
5. Per-agent manifest files on R2 (not a single global catalog). A lightweight index.json is rebuilt from per-agent manifests by a Cloudflare Worker on publish.
6. 5-interface standard per agent: TUI, CLI, pipe, REST API server, MCP stdio server — following the pattern from the gaia-bash C++ agent (PR #985).

​

Phase 0: Restructure — hub/agents/ Directory

​

Directory structure

hub/
├── agents/
│   ├── python/
│   │   ├── chat/
│   │   │   ├── gaia-agent.yaml          # manifest (v0.1.0)
│   │   │   ├── pyproject.toml           # depends on amd-gaia
│   │   │   ├── gaia_agent_chat/
│   │   │   │   ├── __init__.py
│   │   │   │   └── agent.py             # from gaia.agents.base import Agent
│   │   │   ├── tests/
│   │   │   └── README.md
│   │   ├── doc/
│   │   ├── file/
│   │   ├── data/
│   │   ├── web/
│   │   ├── email/
│   │   ├── jira/
│   │   ├── blender/
│   │   ├── docker/
│   │   ├── summarize/
│   │   ├── sd/
│   │   ├── emr/
│   │   └── routing/
│   └── cpp/
│       ├── bash/
│       ├── health/
│       └── wifi/
└── README.md

​

What stays in src/gaia/agents/

src/gaia/agents/
├── base/          # Agent, MCPAgent, ApiAgent, @tool, AgentConsole, errors
├── tools/         # shared tool mixins (FileSearchTools, etc.)
├── registry.py    # AgentRegistry
├── builder/       # BuilderAgent (scaffolding tool)
└── __init__.py

​

Migration strategy

1. Move agent code from src/gaia/agents/<name>/ to hub/agents/python/<name>/gaia_agent_<name>/
2. Rewrite imports — agents import from the installed amd-gaia package
3. Add pyproject.toml per agent with dependencies = ["amd-gaia>={min_gaia_version}"]
4. Add gaia-agent.yaml per agent — every agent starts at version: 0.1.0
5. Update setup.py to remove agent packages from the core wheel
6. Add amd-gaia[agents] extras that installs all production agent wheels
7. Update registry — builtin agents discovered via gaia-agent.yaml scan, not hardcoded

​

Phase 1: Agent Manifest + Registry Enhancement

​

gaia-agent.yaml manifest format

id: chat
name: Chat
version: 0.1.0
description: "General conversation — fast, personality-first"
author: AMD
license: MIT

# Hub display
category: conversation
tags: [chat, general, personality]
icon: message-circle
avatar: avatar.png
screenshots: []
readme: README.md
conversation_starters:
  - "What can you help me with?"

# Technical
language: python
min_gaia_version: "0.18.0"
models: [Qwen3.5-35B-A3B-GGUF]
tools_count: 0
security_tier: verified

# System requirements
requirements:
  min_memory_gb: 8
  min_disk_gb: 2
  min_context_size: 32768
  platforms: [win-x64, linux-x64, darwin-arm64]
  npu: optional
  gpu_vram_gb: 0

# Python-specific
python:
  entry_module: gaia_agent_chat.agent
  entry_class: ChatAgent
  dependencies: []

# Permissions
permissions:
  - filesystem:read
  - network:none

# Interface modes
interfaces:
  tui: true
  cli: true
  pipe: true
  api_server: true
  mcp_server: true

​

Registry reads gaia-agent.yaml

​

C++ subprocess launcher

​

Phase 2: Versioning + Packaging

• Python wheels: gaia agent pack reads gaia-agent.yaml, generates pyproject.toml, builds .whl
• C++ binaries: Static linking via vcpkg, CI matrix for win-x64/linux-x64/darwin-arm64
• Version bumping: gaia agent version patch|minor|major
• Install isolation: uv pip install --target ~/.gaia/agents/{id}/site-packages/

​

Phase 3: R2 Distribution

• Bucket structure: Per-agent manifests at agents/{id}/manifest.json, versioned artifacts, lightweight index.json
• Cloudflare Worker: Auth per publisher, version immutability, server-side SHA-256, index rebuild
• gaia agent publish: validate → test → pack → upload
• Deprecation: gaia agent deprecate <id> --message "..."
• Security tiers: verified (AMD), community (publisher-signed), experimental (opt-in)
• Native trust: Confirmation prompt for non-verified C++ agents

​

Phase 4: Backend Install/Catalog API

• GET /api/agents/catalog — R2 index + local registry merge + per-agent compatibility check
• POST /api/agents/install — system check → native-trust gate → download → verify → install → hot-register
• DELETE /api/agents/{id} — uninstall
• POST /api/agents/{id}/rollback — restore from .backup/
• Progress polling: GET /api/agents/{id}/install-status
• Compatibility: Platform, RAM, disk, GPU/NPU, context size checks with green/yellow/red UI indicators

​

Security tiers, native trust & deprecation (#1100)

• Tiers surfaced in the catalog. Each GET /api/agents/catalog entry carries security_tier (verified | community | experimental) and a derived requires_trust flag — true for non-verified native (C++) agents that run unsandboxed.
• Native-agent trust gate. POST /api/agents/install accepts trust_native: bool. Installing a non-verified native agent without it is refused with 403 and an actionable error; the Hub shows a Trust & Install confirmation that sets the flag. The installer enforces the same rule (TrustRequiredError) as defense in depth.
• Deprecation. Deprecated agents are recorded in the R2 manifest (Worker) and excluded from the default catalog listing unless include_deprecated=true. Installing one still works but logs a loud warning. The Hub renders a Deprecated warning badge.
• Hub badges. Verified = checkmark, community = shield, experimental = flask; plus a tier filter dropdown on both Hub tabs.

​

Phase 5: Frontend — Hub as Splash Page

• Tabs: Installed (with update badges) / Available (with install buttons + download size + compatibility)
• Card states: installed, available, update_available, installing
• Install progress: Polling-based progress bar on card
• Offline: Cached catalog with banner
• Unified AgentInfo TypeScript type with status, version, compatibility, security_tier fields

​

Phase 6: CLI Commands

gaia agent list | search | info               # Discovery
gaia agent install | update | uninstall        # Management
gaia agent rollback | update --all             # Recovery
gaia agent run <id> [--prompt | --api | --mcp] # Execution
gaia agent init | test | version | pack        # Development
gaia agent publish | login                     # Distribution

​

Phase 7: Developer Experience

• gaia agent init <name> --language python|cpp — proper package structure with gaia-agent.yaml
• gaia agent test --lint (CI-safe) and --live (requires LLM)
• Full workflow: init → develop → test → version → pack → publish

​

Milestone: v0.29 — Agent Hub Platform