Agent Manifest: declarative metadata system for agent capabilities and requirements

[kovtcharov]

Summary

Introduce a structured manifest system so every agent declaratively specifies its capabilities, model requirements, dependencies, and CLI interface. This manifest becomes the single source of truth — CLI registration, API exposure, MCP listing, installer profiles, and onboarding recommendations all derive from it.

Problem

Today, agent metadata is scattered across 5+ files with no central definition:

• CLI args: hardcoded in cli.py via subparsers.add_parser()
• API models: hardcoded in api/agent_registry.py AGENT_MODELS dict
• MCP agents: hardcoded imports in mcp/mcp_bridge.py
• Install profiles: hardcoded in installer/init_command.py INIT_PROFILES
• Capabilities: not declared anywhere — implicit in code

Adding a new agent requires modifying all of these files.

Design

Each agent directory contains either an agent.yml file or a class-level AgentManifest:

# src/gaia/agents/chat/agent.yml
name: chat
display_name: Chat Assistant
description: "Interactive chat with document Q&A via RAG"
version: 0.16.0
category: productivity    # productivity, development, creative, system, medical

capabilities:
  - document_qa
  - rag_search
  - file_operations
  - shell_commands

models:
  - name: Qwen3-Coder-30B-A3B-Instruct-GGUF
    type: llm
    required: true
    size_gb: 18
    min_context: 32768
  - name: nomic-embed-text-v2-moe-GGUF
    type: embedding
    required: true
    size_gb: 0.5
  - name: Qwen3-VL-4B-Instruct-GGUF
    type: vlm
    required: false
    size_gb: 3

python_extras: [rag]
external_tools: []
env_vars: []
platforms: [windows, linux]
min_ram_gb: 8
min_disk_gb: 22

cli:
  command: chat
  aliases: [c]
  help: "Interactive chat with document Q&A"
  flags:
    - name: --ui
      help: "Launch desktop web UI"
    - name: --model
      help: "Override default model"
    - name: --interactive / -i
      help: "Interactive terminal mode"

api:
  model_id: gaia-chat
  expose: true

mcp:
  expose: true
  tools: [query_documents, index_document, search_files]

Python Dataclass

@dataclass
class AgentManifest:
    name: str
    display_name: str
    description: str
    version: str
    category: str
    capabilities: List[str]
    models: List[ModelRequirement]
    python_extras: List[str]
    external_tools: List[ToolRequirement]
    env_vars: List[EnvVarRequirement]
    platforms: List[str]
    min_ram_gb: float
    min_disk_gb: float
    cli: Optional[CLIDefinition]
    api: Optional[APIDefinition]
    mcp: Optional[MCPDefinition]
    
    @classmethod
    def from_yaml(cls, path: str) -> "AgentManifest": ...
    
    @classmethod
    def from_agent_class(cls, agent_cls: type) -> "AgentManifest": ...

Files to Create

• src/gaia/agents/base/manifest.py — AgentManifest, ModelRequirement, ToolRequirement, CLIDefinition dataclasses + YAML loader
• src/gaia/agents/*/agent.yml — Manifest for each of the 10 existing agents (Phase 1 can start with just the dataclass; Issue Catch unsupported platform early #12 backfills all agents)

Acceptance Criteria

• AgentManifest dataclass with all fields defined
• YAML loader parses agent.yml files
• Class-level manifest alternative via AgentManifest.from_agent_class()
• Validation: required fields, model types, platform values
• Unit tests for manifest parsing, validation, and edge cases
• At least one agent (ChatAgent) has a complete agent.yml as reference implementation

Depends On

None — this is the foundation.

Enables

• Use public Lemonade hybrid installer #2 (Dynamic Registry), Update Driver Check #3 (Orchestrator), Documentation update from v0.7.2 tag. #4 (Lifecycle Manager), Catch unsupported platform early #12 (Migration)