Skip to main content

USAGE

Agent Generator - Usage Guide

Quick Start

The fastest way to generate all 66 agents:

# Run the quick start script
./quick-start.sh

This will:

  1. Install dependencies
  2. Build the project
  3. List all projects
  4. Generate all OSSA manifests
  5. Generate all MCP tool definitions
  6. Validate all manifests
  7. Show summary

Output will be in /tmp/agent-generator-output/

Manual Usage

Step 1: Install and Build

# Install dependencies
npm install

# Build TypeScript
npm run build

Step 2: List Projects

See what will be generated:

# List all 66 projects
npm run dev -- list-projects

# List only 16 canonical agents
npm run dev -- list-projects --canonical

Step 3: Generate Manifests

Generate OSSA v0.3.3 manifests for all agents:

npm run dev -- generate-agents \
  --input /Volumes/AgentPlatform/wikis/blueflyio/separation-of-duties.md \
  --output ./platform-agents \
  --overwrite

This creates:

  • platform-agents/agent-name.yaml for each project
  • OSSA v0.3.3 compliant manifests
  • Proper separation of duties
  • Full metadata and extensions

Step 4: Generate MCP Tools

Generate MCP tool definitions:

npm run dev -- generate-mcp-tools \
  --input /Volumes/AgentPlatform/wikis/blueflyio/separation-of-duties.md \
  --output ./mcp-tools \
  --overwrite

This creates:

  • mcp-tools/agent-name-mcp.json for each project
  • MCP 1.0 protocol compatible
  • Tool schemas with input/output validation
  • Security configurations

Step 5: Validate

Validate all generated manifests:

npm run dev -- validate-manifests --path ./platform-agents

This checks:

  • OSSA v0.3.3 compliance
  • Schema validation with Zod
  • Required fields
  • Proper formatting

Advanced Usage

Generate Single Agent

# Parse separation-of-duties.md
npm run dev -- list-projects

# Find your agent name, then manually extract and generate
# (Full single-agent support coming in v0.2.0)

Custom Input File

Use a different separation-of-duties file:

npm run dev -- generate-agents \
  --input /path/to/custom-separation-of-duties.md \
  --output ./custom-agents

Custom Output Directory

npm run dev -- generate-agents \
  --output /Volumes/AgentPlatform/repos/bare/blueflyio/platform-agents/agents \
  --overwrite

Different Format

# YAML (default)
npm run dev -- generate-agents --format yaml

# JSON
npm run dev -- generate-agents --format json

Expected Output

Directory Structure

After running generate-agents:

platform-agents/
├── platform-agents.yaml
├── agent-buildkit.yaml
├── agent-brain.yaml
├── agent-chat.yaml
├── agent-mesh.yaml
├── agent-protocol.yaml
├── agent-router.yaml
├── agent-studio.yaml
├── agent-tracer.yaml
├── agent-tailscale.yaml
├── agentic-flows.yaml
├── compliance-engine.yaml
├── api-schema-registry.yaml
├── workflow-engine.yaml
├── foundation-bridge.yaml
├── studio-ui.yaml
...
└── [64 more agents].yaml

After running generate-mcp-tools:

mcp-tools/
├── platform-agents-mcp.json
├── agent-buildkit-mcp.json
├── agent-brain-mcp.json
...
└── [64 more agents]-mcp.json

Sample Generated Manifest

Example: platform-agents.yaml

apiVersion: ossa/v0.4.9
kind: Agent
metadata:
  name: platform-agents
  version: 1.0.0
  description: OSSA agent definitions ONLY - NO services, NO utilities
  author: BlueFly.io Platform Team
  license: Apache-2.0
  repository: https://gitlab.com/blueflyio/platform-agents/-/tree/main/agents/platform-agents
  tags:
    - core-agent-platform-projects
    - agent
    - ossa
    - bluefly
    - platform

spec:
  role: |
    You are the platform-agents agent for the BlueFly.io platform.
    
    PURPOSE: OSSA agent definitions ONLY - NO services, NO utilities
    
    RESPONSIBILITIES:
    - Agent manifest creation and maintenance
    - OSSA specification compliance
    - Agent metadata and configuration
    - Agent versioning and lifecycle
    
    NOT RESPONSIBLE FOR:
    - Service implementation (goes in common_npm)
    - Business logic (goes in common_npm)
    - Utility functions (goes in common_npm)
    - CLI tools (goes in agent-buildkit)
    
    CRITICAL RULES:
    - Follow separation of duties strictly
    - Delegate tasks outside your scope to appropriate agents
    - Always validate inputs and provide structured outputs
    - Log all actions for audit compliance
  
  llm:
    provider: anthropic
    model: claude-sonnet-4
    parameters:
      temperature: 0.7
      max_tokens: 4096
  
  tools:
    - type: function
      name: execute
      description: Execute platform-agents operations
      input_schema:
        type: object
        properties:
          action:
            type: string
            description: The action to perform
          parameters:
            type: object
            description: Action-specific parameters
        required:
          - action
      output_schema:
        type: object
        properties:
          success:
            type: boolean
          result:
            type: object
          error:
            type: string
    - type: function
      name: agent_manifest_creation_and_maintenance
      description: Agent manifest creation and maintenance
    - type: function
      name: ossa_specification_compliance
      description: OSSA specification compliance
  
  runtime:
    type: docker
    image: node:20-alpine
  
  dependencies:
    agents:
      - id: agent-buildkit
        version: ^1.0.0
      - id: common-npm
        version: ^1.0.0
    services:
      - type: database
        provider: postgresql
      - type: cache
        provider: redis
      - type: vector_db
        provider: qdrant
  
  extensions:
    skills_compatibility:
      enabled: true
      platforms:
        - langchain
        - crewai
        - autogen
        - gitlab-duo
    llms_txt:
      enabled: true
    agents_md:
      enabled: true

Sample MCP Tool

Example: platform-agents-mcp.json

{
  "name": "platform-agents",
  "description": "OSSA agent definitions ONLY - NO services, NO utilities",
  "version": "0.4.9",
  "protocol": "mcp/1.0",
  "tools": [
    {
      "name": "platform-agents_execute",
      "description": "Execute platform-agents operations",
      "inputSchema": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "description": "The action to perform",
            "enum": [
              "execute",
              "validate",
              "status",
              "cancel",
              "agent_manifest_creation",
              "ossa_specification_compliance"
            ]
          },
          "parameters": {
            "type": "object",
            "description": "Action-specific parameters"
          }
        },
        "required": ["action"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "data": { "type": "object" },
          "error": { "type": "string" }
        }
      }
    },
    {
      "name": "platform-agents_status",
      "description": "Get status of platform-agents operations",
      "inputSchema": {
        "type": "object",
        "properties": {
          "task_id": {
            "type": "string",
            "description": "Task ID to check status"
          }
        }
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "progress": { "type": "number" },
          "result": { "type": "object" }
        }
      }
    }
  ],
  "security": {
    "authentication": {
      "type": "oauth2",
      "provider": "gitlab"
    },
    "authorization": {
      "rbac": {
        "roles": ["admin", "user", "agent"]
      }
    }
  }
}

Validation

The tool validates:

  1. Project parsing: Ensures all sections are correctly parsed
  2. Schema compliance: Zod validation against OSSA v0.3.3 spec
  3. Required fields: All mandatory fields present
  4. Format validation: YAML/JSON syntax
  5. Naming conventions: DNS-1123 compliant names

Validation Output

Validating OSSA manifests...
✓ platform-agents.yaml
✓ agent-buildkit.yaml
✓ agent-brain.yaml
✓ agent-mesh.yaml
...

Validation Summary:
  Valid: 66
  Invalid: 0

Troubleshooting

"config.json not found"

Problem: Tool can't find config.json

Solution:

# Check config exists
ls -la /Volumes/AgentPlatform/repos/bare/blueflyio/config.json

# Or specify custom path
export CONFIG_PATH=/path/to/config.json

"Failed to parse separation-of-duties.md"

Problem: Markdown structure doesn't match expected format

Solution:

  • Ensure file has proper headers (### for project names)
  • Check RESPONSIBLE FOR and NOT RESPONSIBLE FOR sections
  • Validate markdown syntax

"Invalid manifest generated"

Problem: Generated manifest fails validation

Solution:

  • Check project has required fields (name, purpose, responsibilities)
  • Review Zod error messages for specific issues
  • Ensure responsibilities array is not empty

"Permission denied"

Problem: Can't write to output directory

Solution:

# Create directory with proper permissions
mkdir -p /path/to/output
chmod 755 /path/to/output

Integration with Platform-Agents

Once manifests are generated and validated:

  1. Review Generated Files

    ls -la ./platform-agents/

  2. Copy to Platform-Agents Repo

    cp ./platform-agents/*.yaml \
  /Volumes/AgentPlatform/repos/bare/blueflyio/platform-agents/agents/

  3. Create Worktree and Commit

    # Using buildkit
buildkit worktree create 123  # Your issue number

# Commit changes
git add agents/*.yaml
git commit -m "feat: generate all 66 OSSA agent manifests

Auto-generated from separation-of-duties.md using agent-generator tool

- OSSA v0.3.3 compliant
- Full separation of duties
- MCP tool definitions included

Closes #123"

git push

Next Steps

After generating manifests:

  1. Review each manifest for accuracy
  2. Customize LLM parameters if needed
  3. Add agent-specific tools
  4. Update repository references
  5. Deploy to agent-mesh
  6. Test with GitLab Duo
  7. Monitor in production

Support

For issues or questions: