# Agent Capability Manifest — Layer 3 Discovery
**Version:** 1.0.0
**Status:** Published
**Layer:** 3 — Discovery (Agent OSI Model)
**License:** CC BY 4.0
---
## 1. Purpose
The Agent Capability Manifest is a machine-readable declaration of what an AI agent can do. It's the agent equivalent of `package.json` — a self-describing document that tells other agents and orchestration systems:
- **What this agent can do** (capabilities)
- **How well it does it** (performance metrics)
- **What it needs** (resource requirements)
- **How to reach it** (endpoint)
- **Whether it's alive** (status)
---
## 2. Why This Exists
**Problem:** Before delegating work to an agent, you need to know if it CAN do the work. Today, this knowledge is hardcoded ("the SPFx builder handles SPFx builds") or convention-based. When an agent dies and a replacement spawns, nobody knows what the replacement can do without manual reconfiguration.
**Solution:** Every agent publishes a Capability Manifest at a known location. Orchestrators and other agents query the manifest to discover capabilities. The registry keeps it current via heartbeat.
---
## 3. Manifest Schema
### 3.1 Full Manifest
```yaml
manifest_version: "1.0.0-draft"
agent_id: "hermes-spfx-builder"
agent_type: "hermes"
fleet_id: "works-with-agents-fleet-1"
# What this agent can do
capabilities:
- action: "build"
target: "spfx"
description: "Build and bundle SharePoint Framework web parts"
tools_used: ["node", "gulp", "heft", "npm"]
success_rate: 0.94
avg_duration_seconds: 180
max_concurrent: 3
- action: "deploy"
target: "sharepoint"
description: "Deploy SPFx packages to SharePoint app catalog"
tools_used: ["m365-cli", "pnppm"]
success_rate: 0.87
avg_duration_seconds: 45
max_concurrent: 1
- action: "test"
target: "spfx"
description: "Run SPFx test suite"
tools_used: ["jest", "gulp"]
success_rate: 0.77
avg_duration_seconds: 60
max_concurrent: 5
- action: "fix"
target: "build"
description: "Diagnose and fix build errors"
tools_used: ["terminal", "search_files", "patch"]
success_rate: 0.91
avg_duration_seconds: 300
max_concurrent: 2
# What this agent needs
resources:
min_tokens_per_task: 5000
max_tokens_per_task: 100000
preferred_model: "qwen2.5-8b-oq4"
required_tools: ["terminal", "file", "search"]
required_skills: ["spfx-local", "spfx-heft-build-breakfix"]
# How to reach this agent
endpoint:
protocol: "acp" # Agent Coordination Protocol
address: "agent://spfx-builder.internal:8782"
health_check: "agent://spfx-builder.internal:8782/health"
# Current status
status:
state: "healthy" # healthy | degraded | busy | stuck | offline
load: 0.67 # 0.0 to 1.0
current_tasks: 2
max_tasks: 3
uptime_seconds: 86400
last_heartbeat: "2026-05-05T21:00:00Z"
trust_score: 0.92 # 0.0 to 1.0 — see Agent Trust Framework
# Performance history (rolling 7-day window)
metrics:
tasks_completed: 147
tasks_failed: 9
avg_completion_seconds: 195
pitfalls_reported: 3
skills_published: 2
peer_rating: 4.2 # 1.0 to 5.0 — from other agents
```
### 3.2 Minimal Manifest
For simple agents, only `agent_id` and `capabilities` are required:
```yaml
manifest_version: "1.0.0-draft"
agent_id: "hermes-research-basic"
capabilities:
- action: "research"
target: "general"
success_rate: 0.85
```
---
## 4. Discovery Flow
```
1. Agent A starts → publishes manifest to registry
2. Agent A sends heartbeat every 30s → updates status.load, status.current_tasks
3. Orchestrator needs "build spfx" capability
4. Orchestrator queries registry → returns [Agent A (0.94 success, 0.67 load), Agent C (0.82, 0.10)]
5. Orchestrator selects Agent C (lower load, acceptable success rate)
6. Orchestrator delegates task to Agent C via Layer 5 Coordination Protocol
7. Agent C completes task → registry updates metrics
```
---
## 5. Registry API
### 5.1 Register Agent
```
POST /v1/agents/register
Body: Full Capability Manifest YAML
Response: 201 Created + agent_id
```
### 5.2 Query by Capability
```
GET /v1/agents?action=build&target=spfx
Response:
{
"agents": [...],
"count": 2,
"recommended": "hermes-spfx-builder" // highest success + lowest load
}
```
### 5.3 Update Status (via Heartbeat)
```
POST /v1/agents/{agent_id}/heartbeat
Body: Heartbeat payload (load, current_tasks, status)
Response: 200 OK
```
### 5.4 Deregister
```
DELETE /v1/agents/{agent_id}
Response: 204 No Content
// Automatic after 3 missed heartbeats (90s)
```
---
## 6. Trust Score Calculation
The `trust_score` (0.0 to 1.0) is computed from:
| Signal | Weight | Source |
|--------|--------|--------|
| Task success rate | 30% | Capability metrics |
| Pitfall contribution count | 20% | Pitfall Registry |
| Skill quality (reuse count) | 20% | Skill Registry |
| Peer rating | 15% | Agent-to-agent feedback |
| Uptime consistency | 15% | Heartbeat history |
**Formula:**
```
trust_score = 0.30 × success_rate
+ 0.20 × min(pitfalls_reported / 10, 1.0)
+ 0.20 × min(skills_published / 5, 1.0)
+ 0.15 × (peer_rating / 5.0)
+ 0.15 × uptime_percentage
```
---
## 7. Relationship to Other Layers
| Layer | How Capability Manifest is used |
|-------|-------------------------------|
| L2 (Communication) | Manifest includes endpoint address for messaging |
| L4 (Session) | Not directly used — handoff is capability-agnostic |
| L5 (Coordination) | Work distribution uses capability matching + load + trust |
| L6 (Verification) | Success rate in manifest is updated by verification results |
| L7 (Governance) | Trust score may gate which agents can handle regulated tasks |
---
## 8. Status & Roadmap
| Component | Status |
|-----------|--------|
| Manifest schema | Draft 1.0.0 |
| Registry API | Spec written, not yet implemented |
| Trust score algorithm | Draft |
| Reference client library | Not yet built |
| Agent Registry on workswithagents.dev | Planned |
**Next:** Build the Agent Registry API on workswithagents.dev. Minimal: register, query, heartbeat, deregister.
---
*This document is part of the Agent OSI Model framework. See Layer 5 (Coordination Protocol) for how manifests are used in work distribution.*