agent-manifest

Standard schema and CLI for declaring AI agent capabilities, inputs, outputs, and behaviors.

The Problem

As AI agents proliferate, there's no standard way to describe what an agent can do. This makes it hard to:

• Discover which agent can handle a task
• Route tasks to the right agent in multi-agent systems
• Validate that an agent meets requirements before deployment
• Compose agents that need to work together
• Document agent capabilities for humans and other systems

agent-manifest provides a JSON schema and tooling to solve this. Think of it as package.json for AI agents.

Installation

npm install -g agent-manifest

Quick Start

Create a manifest for your agent:

agent-manifest init my-agent

This creates my-agent.manifest.json:

{
  "name": "my-agent",
  "version": "1.0.0",
  "description": "Description of what this agent does",
  "capabilities": [
    {
      "name": "example-capability",
      "description": "What this capability does",
      "input": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }
        },
        "required": ["query"]
      },
      "output": {
        "type": "object",
        "properties": {
          "result": { "type": "string" }
        }
      }
    }
  ],
  "requirements": {
    "models": ["gpt-4", "claude-3"],
    "permissions": ["network:outbound"]
  },
  "behaviors": {
    "autonomy": "supervised",
    "errorHandling": "escalate"
  }
}

Validate your manifest:

agent-manifest validate my-agent.manifest.json

Schema

Core Fields

Field	Required	Description
name	Yes	Unique identifier (lowercase, hyphens allowed)
version	Yes	Semantic version
description	No	Human-readable description
capabilities	Yes	Array of capability definitions

Capabilities

Each capability describes something the agent can do:

{
  "name": "web-search",
  "description": "Search the web for information",
  "input": { "type": "object", "properties": { "query": { "type": "string" } } },
  "output": { "type": "object", "properties": { "results": { "type": "array" } } },
  "examples": [{ "input": { "query": "AI news" }, "output": { "results": [] } }],
  "reliability": 0.95,
  "latency": "fast",
  "cost": "low"
}

Requirements

Declare what your agent needs to run:

{
  "requirements": {
    "models": ["claude-3-opus", "gpt-4"],
    "tools": ["web-browser", "search-api"],
    "memory": "1GB",
    "permissions": [
      "filesystem:read",
      "filesystem:write",
      "network:outbound",
      "network:inbound",
      "shell:execute",
      "browser:control",
      "secrets:access",
      "human:approval"
    ]
  }
}

Behaviors

Describe how the agent operates:

{
  "behaviors": {
    "autonomy": "semi-autonomous",
    "errorHandling": "retry",
    "timeout": 300,
    "maxIterations": 10,
    "concurrency": 3
  }
}

Autonomy levels:

• supervised: Requires human approval for actions
• semi-autonomous: Can act independently within bounds
• autonomous: Fully self-directed (must set maxIterations)

Communication

For multi-agent scenarios, declare how your agent communicates:

{
  "communication": {
    "protocols": ["a2a", "mcp", "openai-functions", "langchain-tools"],
    "accepts": ["search-query", "summarize-request"],
    "delegates": ["deep-analysis", "data-visualization"]
  }
}

CLI Commands

validate

Check if a manifest is valid:

agent-manifest validate agent.manifest.json
agent-manifest validate agent.manifest.json -q  # suppress warnings

init

Create a new manifest template:

agent-manifest init my-agent
agent-manifest init my-agent -o custom-path.json

inspect

View manifest details:

agent-manifest inspect agent.manifest.json

Output:

my-agent v1.0.0
----------------------------------------

An AI agent that does things

Author: Your Name

Capabilities (2):
  - web-search
    Search the web for information
    Reliability: 95%
    Latency: fast
  - summarize
    Summarize text content
    Reliability: 90%
    Latency: moderate

Requirements:
  Models: claude-3-opus, gpt-4
  Permissions: network:outbound

Behaviors:
  Autonomy: semi-autonomous
  Error handling: retry
  Timeout: 300s

compare

Check compatibility between two agents:

agent-manifest compare sender.manifest.json receiver.manifest.json

Output:

Comparing: sender-agent <-> receiver-agent
--------------------------------------------------

Communication:
  Shared protocols: a2a, mcp

sender-agent -> receiver-agent:
  Can communicate
  
receiver-agent -> sender-agent:
  Cannot communicate
  Task type mismatch. Sender delegates: analysis. Receiver accepts: search.

Compatibility Scores:
  sender-agent -> receiver-agent: 85%
  receiver-agent -> sender-agent: 45%

check

Verify an agent meets specific requirements:

agent-manifest check agent.json --cap search --cap summarize --perm network:outbound

Programmatic Usage

import {
  validate,
  load,
  checkCompatibility,
  createManifest,
  findAgentsForCapability,
} from 'agent-manifest';

// Validate a manifest
const result = validate(manifestObject);
if (!result.valid) {
  console.error('Errors:', result.errors);
}

// Load from file
const manifest = load('./agent.manifest.json');

// Check compatibility
const compat = checkCompatibility(manifest, {
  capabilities: ['search', 'summarize'],
  permissions: ['network:outbound'],
  protocols: ['a2a'],
});

if (!compat.compatible) {
  console.log('Missing:', compat.missingCapabilities);
}

// Build a manifest programmatically
const newManifest = createManifest('my-agent', '1.0.0')
  .description('An agent that searches the web')
  .author('Your Name')
  .capability({
    name: 'search',
    description: 'Search the web',
    reliability: 0.95,
    latency: 'fast',
  })
  .permissions('network:outbound')
  .autonomy('supervised')
  .protocols('a2a', 'mcp')
  .build();

// Find agents for a task
const agents = findAgentsForCapability(allManifests, 'code-review');

Use Cases

Agent Discovery

Build a registry where agents publish their manifests. Query by capability:

const searchAgents = registry.filter(m =>
  m.capabilities.some(c => c.name === 'web-search')
);

Task Routing

Route tasks to agents based on capabilities and requirements:

function routeTask(task, agents) {
  const capable = findAgentsForCapability(agents, task.type);
  return capable.sort((a, b) => {
    const capA = a.capabilities.find(c => c.name === task.type);
    const capB = b.capabilities.find(c => c.name === task.type);
    return (capB.reliability || 0) - (capA.reliability || 0);
  })[0];
}

Deployment Validation

Before deploying, verify the agent has required permissions:

const result = checkCompatibility(manifest, {
  permissions: ['filesystem:write', 'shell:execute'],
});

if (!result.compatible) {
  throw new Error(`Missing permissions: ${result.missingPermissions.join(', ')}`);
}

Multi-Agent Composition

Check if agents can work together:

const score = compatibilityScore(orchestrator, worker);
if (score < 0.5) {
  console.warn('Low compatibility between agents');
}

Schema File

The full JSON Schema is available at schema/agent-manifest.schema.json. Use it for IDE autocompletion:

{
  "$schema": "./node_modules/agent-manifest/schema/agent-manifest.schema.json",
  "name": "my-agent",
  ...
}

License

MIT