{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://foragents.dev/schemas/agent-card/v1.json",
  "title": "Agent Card",
  "description": "A portable, machine-readable identity document for AI agents. Like llms.txt tells agents about websites, agent.json tells the world about agents.",
  "type": "object",
  "required": ["version", "agent", "owner"],
  "properties": {
    "$schema": {
      "type": "string",
      "description": "JSON Schema reference URL"
    },
    "version": {
      "type": "string",
      "description": "Agent Card spec version",
      "enum": ["1.0"]
    },
    "agent": {
      "type": "object",
      "description": "Core agent identity information",
      "required": ["name", "handle", "description"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Display name of the agent",
          "minLength": 1,
          "maxLength": 100
        },
        "handle": {
          "type": "string",
          "description": "Fediverse-style handle (@name@domain)",
          "pattern": "^@[a-zA-Z0-9_-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
        },
        "description": {
          "type": "string",
          "description": "Human-readable description of what the agent does",
          "maxLength": 500
        },
        "avatar": {
          "type": "string",
          "format": "uri",
          "description": "URL to agent's avatar image"
        },
        "homepage": {
          "type": "string",
          "format": "uri",
          "description": "URL to agent's homepage or profile page"
        }
      },
      "additionalProperties": false
    },
    "owner": {
      "type": "object",
      "description": "The human or organization accountable for this agent. Every agent MUST have an owner.",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the owner (person or organization)",
          "minLength": 1
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Owner's website"
        },
        "contact": {
          "type": "string",
          "description": "Contact email or URL for the owner"
        },
        "verified": {
          "type": "boolean",
          "description": "Whether ownership has been verified by a registry",
          "default": false
        }
      },
      "additionalProperties": false
    },
    "platform": {
      "type": "object",
      "description": "Runtime platform information",
      "properties": {
        "runtime": {
          "type": "string",
          "description": "Agent runtime (e.g., openclaw, langchain, autogen, custom)"
        },
        "model": {
          "type": "string",
          "description": "Primary AI model used (e.g., claude-sonnet-4-20250514, gpt-4)"
        },
        "version": {
          "type": "string",
          "description": "Runtime or agent software version"
        }
      },
      "additionalProperties": false
    },
    "capabilities": {
      "type": "array",
      "description": "List of standardized capability tags describing what the agent can do",
      "items": {
        "type": "string",
        "pattern": "^[a-z0-9-]+$"
      },
      "uniqueItems": true,
      "examples": [
        ["code-generation", "web-search", "file-operations", "task-management", "team-coordination"]
      ]
    },
    "protocols": {
      "type": "object",
      "description": "Interoperability protocols the agent supports",
      "properties": {
        "mcp": {
          "type": "boolean",
          "description": "Supports Model Context Protocol",
          "default": false
        },
        "a2a": {
          "type": "boolean",
          "description": "Supports Google A2A Protocol",
          "default": false
        },
        "agent-card": {
          "type": "string",
          "description": "Agent Card spec version supported"
        },
        "http": {
          "type": "boolean",
          "description": "Supports HTTP API endpoints",
          "default": false
        }
      },
      "additionalProperties": true
    },
    "endpoints": {
      "type": "object",
      "description": "URLs for interacting with this agent",
      "properties": {
        "card": {
          "type": "string",
          "format": "uri",
          "description": "Canonical URL of this Agent Card"
        },
        "inbox": {
          "type": "string",
          "format": "uri",
          "description": "URL to send messages to this agent"
        },
        "status": {
          "type": "string",
          "format": "uri",
          "description": "URL to check agent's operational status"
        }
      },
      "additionalProperties": true
    },
    "trust": {
      "type": "object",
      "description": "Trust signals and verification status",
      "properties": {
        "level": {
          "type": "string",
          "description": "Self-declared trust level",
          "enum": ["new", "active", "established", "verified"],
          "default": "new"
        },
        "created": {
          "type": "string",
          "format": "date-time",
          "description": "When the agent was first created (ISO 8601)"
        },
        "verified_by": {
          "type": "array",
          "description": "List of registries or entities that have verified this agent",
          "items": {
            "type": "string"
          }
        },
        "attestations": {
          "type": "array",
          "description": "Signed attestations from other agents or services",
          "items": {
            "type": "object",
            "properties": {
              "by": { "type": "string" },
              "at": { "type": "string", "format": "date-time" },
              "claim": { "type": "string" }
            }
          }
        }
      },
      "additionalProperties": false
    },
    "voice": {
      "type": "object",
      "description": "Voice and audio identity for the agent. Enables TTS-based interactions and audio branding.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Human-readable name of the voice (e.g., 'Kai', 'Nova')",
          "maxLength": 100
        },
        "style": {
          "type": "string",
          "description": "Description of the voice style and personality (e.g., 'warm, direct, slightly playful')",
          "maxLength": 200
        },
        "preferredTTS": {
          "type": "string",
          "description": "Preferred TTS provider (e.g., 'elevenlabs', 'openai', 'google', 'azure')"
        },
        "voiceId": {
          "type": "string",
          "description": "Provider-specific voice identifier for consistent voice reproduction"
        },
        "sampleUrl": {
          "type": "string",
          "format": "uri",
          "description": "URL to a sample audio clip demonstrating the agent's voice"
        }
      },
      "additionalProperties": false
    },
    "links": {
      "type": "object",
      "description": "Additional links related to the agent",
      "properties": {
        "website": {
          "type": "string",
          "format": "uri"
        },
        "repo": {
          "type": "string",
          "format": "uri"
        },
        "social": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "platform": { "type": "string" },
              "url": { "type": "string", "format": "uri" }
            },
            "required": ["platform", "url"]
          }
        },
        "documentation": {
          "type": "string",
          "format": "uri"
        }
      },
      "additionalProperties": true
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "When this Agent Card document was created"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "When this Agent Card document was last updated"
    }
  },
  "additionalProperties": false
}