Skip to main content

Team Manifests

Team Manifests are the foundation of composable AI teams in MeetLoyd. Think of them as "npm for AI agents" - a declarative way to define, version, and deploy complete AI team configurations.

Overview​

A Team Manifest defines:

  • Components: Agents, skills, and avatars that make up your team
  • Orchestration: How agents communicate and route tasks
  • Versioning: Lock files ensure reproducible deployments
  • Customization: Override configurations for your specific needs

Manifest Structure​

Basic Example​

{
  "$schema": "https://meetloyd.com/schemas/team.manifest.json",
  "name": "Enterprise Sales Team",
  "slug": "enterprise-sales",
  "version": "2.0.0",
  "description": "AI-powered sales team for enterprise B2B",

  "components": {
    "agents": [
      {
        "ref": "store://agents/sdr-agent",
        "version": "^1.0.0",
        "localId": "sdr",
        "skillOverrides": [
          { "ref": "store://skills/linkedin-sales-nav", "version": "^2.0.0" }
        ]
      },
      {
        "ref": "store://agents/ae-agent",
        "version": "^1.0.0",
        "localId": "ae",
        "reportsTo": "sales-manager"
      },
      {
        "ref": "local://agents/custom-demo-agent",
        "localId": "demo",
        "customizations": {
          "contextPromptTemplate": "Focus on {{industry}} use cases"
        }
      }
    ],
    "skills": [
      { "ref": "store://skills/salesforce-crm", "version": "^3.0.0" },
      { "ref": "store://skills/email-sequences", "version": "^1.2.0" }
    ],
    "avatars": [
      { "ref": "external://heygen/avatar-emma-professional", "localId": "emma" }
    ]
  },

  "orchestration": {
    "mode": "hierarchical",
    "entryAgentId": "sdr",
    "routing": {
      "intentRouting": [
        { "intent": "pricing_inquiry", "targetAgentId": "ae", "priority": 1 },
        { "intent": "demo_request", "targetAgentId": "demo", "priority": 2 }
      ]
    }
  }
}

Component References​

Components are referenced using URIs that specify their source:

Store References​

store://agents/sdr-agent@^1.0.0
store://skills/salesforce-crm@~2.1.0
store://avatars/professional-emma@1.0.0
  • ^1.0.0 - Compatible with 1.x.x (minor/patch updates allowed)
  • ~2.1.0 - Patch updates only (2.1.x)
  • 1.0.0 - Exact version (no updates)

External References​

external://heygen/avatar-id
external://elevenlabs/voice-id

For third-party avatar/voice providers.

Local References​

local://agents/my-custom-agent

For custom components defined in your tenant.

Lock Files​

When you deploy a manifest, MeetLoyd generates a lock file (team.lock.json) that records the exact resolved versions:

{
  "manifestVersion": "2.0.0",
  "resolved": "2026-01-15T10:30:00Z",
  "checksum": "sha256:abc123...",

  "agents": {
    "store://agents/sdr-agent": {
      "resolvedVersion": "1.2.3",
      "resolvedRef": "store://agents/sdr-agent@1.2.3",
      "resolvedAt": "2026-01-15T10:30:00Z",
      "checksum": "sha256:def456..."
    }
  },
  "skills": { ... },
  "avatars": { ... }
}

Lock files ensure:

  • Reproducibility: Same versions deploy every time
  • Audit trail: Track what versions are running
  • Rollback: Return to previous known-good state

Version Management​

Checking for Updates​

GET /api/components/:componentType/:componentId/updates

Response:

{
  "hasUpdate": true,
  "currentVersion": "1.2.3",
  "availableVersion": "1.3.0",
  "changelog": "Bug fixes and performance improvements"
}

Upgrading Components​

POST /api/manifests/:deployId/upgrade
Content-Type: application/json

{
  "componentIds": ["store://agents/sdr-agent"],
  "dryRun": false
}

Locking Versions​

Prevent auto-updates for specific components:

{
  "agents": [
    {
      "ref": "store://agents/sdr-agent",
      "version": "1.2.3",
      "locked": true
    }
  ]
}

Rollback​

POST /api/manifests/:deployId/rollback
Content-Type: application/json

{
  "componentId": "store://agents/sdr-agent",
  "toVersion": 2
}

Response:

{
  "success": true,
  "fromVersion": 3,
  "toVersion": 2
}

Customizations​

Override component behavior without forking:

Agent Customizations​

{
  "ref": "store://agents/sdr-agent",
  "customizations": {
    "contextPromptTemplate": "You specialize in {{industry}}",
    "memoryConfig": {
      "maxContextTokens": 8000
    }
  }
}

Skill Overrides​

{
  "ref": "store://agents/ae-agent",
  "skillOverrides": [
    {
      "ref": "store://skills/custom-crm",
      "version": "^1.0.0",
      "replaces": "store://skills/salesforce-crm"
    }
  ]
}

Orchestration​

Define how agents work together:

Hierarchical Mode​

{
  "orchestration": {
    "mode": "hierarchical",
    "entryAgentId": "sdr",
    "routing": {
      "intentRouting": [
        { "intent": "pricing", "targetAgentId": "ae", "priority": 1 }
      ],
      "fallbackAgentId": "sdr"
    }
  }
}

Parallel Mode​

{
  "orchestration": {
    "mode": "parallel",
    "agentIds": ["researcher", "writer", "reviewer"],
    "aggregation": "consensus"
  }
}

API Reference​

Validate Manifest​

POST /api/manifests/validate
Content-Type: application/json

{
  "manifest": { ... }
}

Returns validation errors and warnings without deploying.

Resolve Manifest (Dry Run)​

POST /api/manifests/resolve
Content-Type: application/json

{
  "manifest": { ... }
}

Returns the lock file that would be generated, with all versions resolved.

Deploy Manifest​

POST /api/manifests/deploy
Content-Type: application/json

{
  "manifest": { ... },
  "options": {
    "dryRun": false,
    "force": false,
    "notes": "Initial deployment"
  }
}

List Deployments​

GET /api/manifests

Returns all team deployments for your tenant.

Get Deployment​

GET /api/manifests/:deployId

Returns manifest, lock file, and component details.

Export Manifest​

GET /api/manifests/:deployId/export

Returns the manifest in portable format.

Upgrade Components​

POST /api/manifests/:deployId/upgrade
Content-Type: application/json

{
  "componentIds": ["store://agents/sdr-agent"],
  "dryRun": false
}

Rollback Component​

POST /api/manifests/:deployId/rollback
Content-Type: application/json

{
  "componentId": "store://agents/sdr-agent",
  "toVersion": 2
}

Component Version History​

GET /api/components/:componentType/:componentId/versions

Toggle Component Lock​

POST /api/components/:componentType/:componentId/lock
Content-Type: application/json

{
  "locked": true
}

Best Practices​

1. Use Semantic Versioning​

Follow semver for your custom components:

  • 1.0.0 → 1.0.1: Bug fixes
  • 1.0.0 → 1.1.0: New features (backward compatible)
  • 1.0.0 → 2.0.0: Breaking changes

2. Lock Production Deployments​

{
  "agents": [
    { "ref": "store://agents/sdr-agent", "version": "1.2.3", "locked": true }
  ]
}

3. Test in Staging First​

Deploy to a staging team before production:

loyd manifest deploy team.manifest.json --team staging-sales

4. Document Breaking Changes​

When publishing updates, include release notes:

{
  "version": "2.0.0",
  "changelog": {
    "breaking": ["Removed legacy CRM integration"],
    "added": ["New Salesforce v2 integration"],
    "fixed": ["Memory leak in long conversations"]
  }
}

5. Use Version Ranges Wisely​

  • Development: ^1.0.0 (get latest compatible)
  • Production: 1.2.3 (exact version)
  • CI/CD: ~1.2.0 (patch updates only)

Team Catalog​

MeetLoyd ships with 23 pre-built team manifests in manifests/catalog/. These YAML files are the single source of truth for all team templates, store listings, and preset deployments.

Available Catalog Teams​

TeamCategoryDescription
Sales TeamsalesComplete AI sales operations
Support TeamsupportCustomer support escalation
C-Suite TeamexecutiveExecutive leadership team
DevOps TeamengineeringInfrastructure and deployment
Marketing TeammarketingContent and campaign management
Finance TeamfinanceFinancial operations and reporting
Legal TeamlegalLegal review and compliance
Product TeamproductProduct management and roadmap
Strategy TeamstrategyStrategic planning and analysis
HR TeamhrHuman resources operations
Customer Success Teamcustomer-successCustomer retention and growth
Logistics TeamlogisticsSupply chain and logistics
Manufacturing TeammanufacturingProduction operations
Healthcare TeamhealthcareHealthcare operations (HIPAA)
Legal Services Teamlegal-servicesLaw firm operations
Insurance TeaminsuranceInsurance operations
Accounting TeamaccountingAccounting and bookkeeping
Construction TeamconstructionConstruction project management
Real Estate Teamreal-estateProperty management and sales
VC/PE TeamfinanceVenture capital and private equity
Fundraising TeamfinanceFundraising and donor management
Support Tiers TeamsupportTiered support escalation
Enterprise Deployment TeamoperationsSSO/SCIM deployment

Using Catalog Teams​

Deploy a catalog team via the CLI:

npx tsx scripts/deploy-manifest.ts \
  --manifest manifests/catalog/sales-team.yaml \
  --tenant tenant_abc123 \
  --deployer user_admin

Or reference them in app manifests:

teams:
  - type: preset
    ref: preset://sales-team

Model Aliases​

Instead of hardcoding model IDs like claude-sonnet-4-20250514, you can use human-friendly aliases that are automatically resolved at deploy-time:

agents:
  - slug: sales-director
    model: claude-sonnet-latest

Available Aliases​

AliasResolves To
claude-opus-latestclaude-opus-4-6
claude-sonnet-latestclaude-sonnet-4-20250514
claude-haiku-latestclaude-haiku-4-5-20251001
gpt-latestgpt-4o
gpt-mini-latestgpt-4o-mini
gemini-latestgemini-2.5-pro
gemini-flash-latestgemini-2.5-flash
mistral-latestmistral-large-latest
deepseek-latestdeepseek-r1-distill-70b
llama-latestllama-3.3-70b

Aliases are resolved both at deploy-time and as a safety net at runtime, so agents always route to the correct LLM provider.

Agent Authorization​

Declare per-agent resource permissions directly in your manifest. Permissions are provisioned as OpenFGA authorization tuples at deploy-time.

agents:
  - slug: crm-agent
    name: CRM Agent
    model: claude-sonnet-latest
    authorization:
      - resource: "crm_object_type:hubspot/contacts"
        relation: editor
      - resource: "crm_object_type:hubspot/deals"
        relation: reader
      - resource: "drive_folder:shared/reports"
        relation: writer

Resource Format​

Resources use {type}:{id} format. Common resource types:

TypeExampleDescription
crm_object_typehubspot/contactsCRM object access
git_repositorygithub/acme/websiteGit repo permissions
drive_foldershared/reportsDrive folder access
email_domainacme.comEmail sending scope

Relations​

Common relations: reader, writer, editor, committer, admin.

Authorization is non-blocking — if OpenFGA is not configured in your environment, deployment continues with a warning.

Agent Identity (SPIFFE)​

Agents automatically receive a SPIFFE identity at deploy-time. You can optionally configure SVID (SPIFFE Verifiable Identity Document) parameters:

agents:
  - slug: api-agent
    name: API Integration Agent
    model: claude-sonnet-latest
    identity:
      spiffe:
        audiences:
          - "https://api.partner.com"
          - "https://internal.example.com"
        svidTTL: 7200   # 2 hours (default: 3600s)

Each agent's SPIFFE ID follows the pattern:

spiffe://meetloyd.com/tenant/{tenantId}/agent/{agentId}

This enables:

  • Cross-service authentication — Agents can authenticate to external services using JWT-SVIDs
  • Token exchange — Agents can request scoped tokens for partner APIs
  • Trust verification — External services can verify agent identity via the MeetLoyd trust bundle

Catalog Validation​

All catalog YAML manifests are validated against a strict schema when loaded. Validation is informational — errors are logged as warnings but don't prevent the catalog from loading.

Validated fields include:

  • Agent definitions (slug, name, model, tools)
  • Orchestration configuration (mode, routing, settings)
  • Interaction rules (type, trigger, agents)
  • Extended fields (ROI calculator, marketplace metadata, event billing)
  • Authorization grants and identity config

If you see validation warnings in your logs, review the flagged fields:

[catalog] Validation error in my-team.yaml at agents.0.model: Required

Development Hot-Reload​

When developing locally, the catalog loader watches manifests/catalog/ for changes and automatically refreshes the cache. Edit a YAML file and your next API request uses the updated version — no restart needed.

[catalog] Cache invalidated — sales-team.yaml changed

Hot-reload is:

  • Automatic — starts on first catalog load, no configuration needed
  • Debounced — rapid saves are coalesced (300ms window)
  • Production-safe — disabled when NODE_ENV=production

See Also​