{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://adl-spec.org/0.3/schema.json", "title": "ADL Document", "description": "Agent Definition Language v0.3.0", "$defs": { "data_classification": { "description": "Data classification (composable; profiles MAY add domain-specific sub-objects via schema composition)", "type": "object", "required": [ "sensitivity" ], "properties": { "sensitivity": { "type": "string", "enum": [ "public", "internal", "confidential", "restricted" ], "description": "Information sensitivity level (NIST FIPS 199 / ISO 27001)" }, "categories": { "minItems": 1, "description": "Broad information categories handled", "type": "array", "items": { "type": "string", "enum": [ "pii", "phi", "financial", "credentials", "intellectual_property", "regulatory" ] } }, "retention": { "additionalProperties": false, "description": "Data retention requirements", "type": "object", "properties": { "min_days": { "minimum": 0, "type": "number" }, "max_days": { "minimum": 0, "type": "number" }, "policy_uri": { "format": "uri", "type": "string" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "handling": { "additionalProperties": false, "description": "Data handling constraints", "type": "object", "properties": { "encryption_required": { "type": "boolean" }, "anonymization_required": { "type": "boolean" }, "cross_border_restricted": { "type": "boolean" }, "logging_required": { "type": "boolean" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "extensions": { "$ref": "#/$defs/extensions" } } }, "budgetDimension": { "additionalProperties": false, "description": "Per-session / per-day cap for one budget dimension", "type": "object", "properties": { "per_session": { "exclusiveMinimum": 0, "type": "number" }, "per_day": { "exclusiveMinimum": 0, "type": "number" } } }, "budget": { "additionalProperties": false, "description": "Cumulative token / cost / wall-clock budget, scoped per session and per day (enforced by Runtime Protocol §2)", "type": "object", "properties": { "tokens": { "$ref": "#/$defs/budgetDimension" }, "cost_usd": { "$ref": "#/$defs/budgetDimension" }, "wall_clock_sec": { "$ref": "#/$defs/budgetDimension" } } }, "degradationResponse": { "additionalProperties": false, "description": "Governor response to a degradation cause (Runtime Protocol §6)", "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "halt", "pause", "fallback", "continue" ] }, "value": { "description": "Value to return when action is fallback" }, "message": { "type": "string" }, "notify": { "type": "boolean" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "extensions": { "type": "object", "patternProperties": { "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "description": "Vendor-namespaced extensions. Keys are reverse-domain identifiers." } }, "type": "object", "required": [ "adl_spec", "name", "description", "version", "data_classification" ], "properties": { "adl_spec": { "pattern": "^\\d+\\.\\d+\\.\\d+$", "description": "ADL specification version (semantic versioning)", "type": "string" }, "$schema": { "format": "uri", "description": "URI to this JSON Schema", "type": "string" }, "name": { "minLength": 1, "description": "Human-readable name for the agent", "type": "string" }, "description": { "minLength": 1, "description": "Human-readable description of the agent's purpose and capabilities", "type": "string" }, "version": { "pattern": "^\\d+\\.\\d+\\.\\d+$", "description": "Agent version (semantic versioning)", "type": "string" }, "lifecycle": { "additionalProperties": false, "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "draft", "active", "deprecated", "retired" ], "description": "Lifecycle state of the agent" }, "effective_date": { "format": "date-time", "description": "ISO 8601 timestamp when current status took effect", "type": "string" }, "sunset_date": { "format": "date-time", "description": "ISO 8601 timestamp for planned or actual retirement", "type": "string" }, "successor": { "format": "uri", "description": "URI or URN of the replacement agent", "type": "string" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "id": { "description": "Unique identifier for the agent (URI or URN)", "type": "string" }, "provider": { "additionalProperties": false, "description": "Organization or entity that provides the agent", "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "type": "string" }, "url": { "format": "uri", "type": "string" }, "contact": { "format": "email", "type": "string" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "cryptographic_identity": { "additionalProperties": false, "description": "Cryptographic identification for the agent", "type": "object", "properties": { "did": { "type": "string" }, "public_key": { "additionalProperties": false, "type": "object", "required": [ "algorithm", "value" ], "properties": { "algorithm": { "type": "string" }, "value": { "type": "string" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "extensions": { "$ref": "#/$defs/extensions" } } }, "model": { "additionalProperties": false, "description": "AI model configuration", "type": "object", "properties": { "provider": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "context_window": { "minimum": 1, "type": "integer" }, "temperature": { "minimum": 0, "maximum": 2, "type": "number" }, "max_tokens": { "minimum": 1, "type": "integer" }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "function_calling", "vision", "code_execution", "streaming" ] } }, "extensions": { "$ref": "#/$defs/extensions" } } }, "system_prompt": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "object", "required": [ "template" ], "properties": { "template": { "type": "string", "minLength": 1 }, "variables": { "type": "object" }, "extensions": { "$ref": "#/$defs/extensions" } }, "additionalProperties": false } ], "description": "System prompt (string or template object)" }, "tools": { "description": "Tools (functions) the agent can invoke", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "name", "description" ], "properties": { "name": { "pattern": "^[a-z][a-z0-9_]*$", "description": "Unique tool name", "type": "string" }, "description": { "minLength": 1, "type": "string" }, "parameters": { "type": "object", "description": "JSON Schema for tool input parameters" }, "returns": { "type": "object", "description": "JSON Schema for tool return value" }, "examples": { "description": "Example invocations", "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "name": { "type": "string" }, "input": { "type": "object" }, "output": {}, "extensions": { "$ref": "#/$defs/extensions" } } } }, "requires_confirmation": { "type": "boolean" }, "idempotent": { "type": "boolean" }, "read_only": { "type": "boolean" }, "annotations": { "type": "object", "properties": { "openapi_ref": { "type": "string", "format": "uri" }, "operation_id": { "type": "string" } }, "additionalProperties": true, "description": "Implementation hints and metadata (open object)" }, "data_classification": { "$ref": "#/$defs/data_classification" }, "extensions": { "$ref": "#/$defs/extensions" } } } }, "resources": { "description": "Data sources the agent can access", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "name", "type" ], "properties": { "name": { "minLength": 1, "type": "string" }, "type": { "type": "string", "enum": [ "vector_store", "knowledge_base", "file", "api", "database" ] }, "description": { "type": "string" }, "uri": { "format": "uri", "type": "string" }, "mime_types": { "type": "array", "items": { "type": "string" } }, "schema": { "type": "object", "description": "JSON Schema describing the resource's data structure" }, "annotations": { "type": "object", "additionalProperties": true, "description": "Implementation hints and metadata (open object)" }, "data_classification": { "$ref": "#/$defs/data_classification" }, "extensions": { "$ref": "#/$defs/extensions" } } } }, "prompts": { "description": "Reusable prompt templates", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "name", "template" ], "properties": { "name": { "minLength": 1, "type": "string" }, "template": { "minLength": 1, "type": "string" }, "description": { "type": "string" }, "arguments": { "type": "object", "description": "JSON Schema for template arguments" }, "extensions": { "$ref": "#/$defs/extensions" } } } }, "permissions": { "additionalProperties": false, "description": "Agent operational boundaries (deny-by-default)", "type": "object", "properties": { "network": { "additionalProperties": false, "type": "object", "properties": { "allowed_hosts": { "description": "Host patterns (see Section 4.4)", "type": "array", "items": { "type": "string" } }, "allowed_ports": { "type": "array", "items": { "minimum": 1, "maximum": 65535, "type": "integer" } }, "allowed_protocols": { "type": "array", "items": { "type": "string" } }, "deny_private": { "type": "boolean" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "filesystem": { "additionalProperties": false, "type": "object", "properties": { "allowed_paths": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "path", "access" ], "properties": { "path": { "type": "string" }, "access": { "type": "string", "enum": [ "read", "write", "read_write" ] } } } }, "denied_paths": { "description": "Path patterns to deny (see Section 4.4)", "type": "array", "items": { "type": "string" } }, "extensions": { "$ref": "#/$defs/extensions" } } }, "environment": { "additionalProperties": false, "type": "object", "properties": { "allowed_variables": { "description": "Variable name patterns (see Section 4.4)", "type": "array", "items": { "type": "string" } }, "denied_variables": { "description": "Variable name patterns to deny (see Section 4.4)", "type": "array", "items": { "type": "string" } }, "extensions": { "$ref": "#/$defs/extensions" } } }, "execution": { "additionalProperties": false, "type": "object", "properties": { "allowed_commands": { "type": "array", "items": { "type": "string" } }, "denied_commands": { "type": "array", "items": { "type": "string" } }, "allow_shell": { "type": "boolean" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "resource_limits": { "additionalProperties": false, "type": "object", "properties": { "max_memory_mb": { "minimum": 0, "type": "number" }, "max_cpu_percent": { "minimum": 0, "maximum": 100, "type": "number" }, "max_duration_sec": { "minimum": 0, "type": "number" }, "max_concurrent": { "minimum": 1, "type": "integer" }, "budget": { "$ref": "#/$defs/budget" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "sub_agents": { "description": "Subordinate personas this agent may spawn under its own identity (no separate passport); capped at spawn by Runtime Protocol §4", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "prompt_resource": { "type": "string" }, "tools": { "type": "array", "items": { "type": "string" } }, "max_parallel": { "minimum": 1, "type": "integer" }, "budget_share": { "$ref": "#/$defs/budget" }, "extensions": { "$ref": "#/$defs/extensions" } } } }, "delegation": { "additionalProperties": false, "description": "Envelope of separately-identified peer agents this agent may engage (admitted by Runtime Protocol §4)", "type": "object", "properties": { "match": { "type": "array", "items": { "type": "string" } }, "deny": { "type": "array", "items": { "type": "string" } }, "max_depth": { "minimum": 1, "type": "integer" }, "attenuation": { "additionalProperties": false, "type": "object", "properties": { "scopes_subset": { "type": "boolean" }, "budget_subset": { "type": "boolean" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "extensions": { "$ref": "#/$defs/extensions" } } }, "extensions": { "$ref": "#/$defs/extensions" } } }, "security": { "additionalProperties": false, "description": "Security requirements", "type": "object", "properties": { "authentication": { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "api_key", "oauth2", "oidc", "mtls" ] }, "required": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } }, "token_endpoint": { "format": "uri", "type": "string" }, "issuer": { "type": "string" }, "audience": { "type": "string" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "encryption": { "additionalProperties": false, "type": "object", "properties": { "in_transit": { "additionalProperties": false, "type": "object", "properties": { "required": { "type": "boolean" }, "min_version": { "type": "string" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "at_rest": { "additionalProperties": false, "type": "object", "properties": { "required": { "type": "boolean" }, "algorithm": { "type": "string" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "extensions": { "$ref": "#/$defs/extensions" } } }, "attestation": { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string", "enum": [ "self", "third_party", "verifiable_credential" ] }, "issuer": { "type": "string" }, "issued_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "signature": { "additionalProperties": false, "type": "object", "required": [ "algorithm", "value", "signed_content" ], "properties": { "algorithm": { "type": "string" }, "value": { "type": "string" }, "signed_content": { "type": "string", "enum": [ "canonical", "digest" ] }, "digest_algorithm": { "type": "string" }, "digest_value": { "type": "string" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "extensions": { "$ref": "#/$defs/extensions" } } }, "extensions": { "$ref": "#/$defs/extensions" } } }, "data_classification": { "$ref": "#/$defs/data_classification" }, "runtime": { "additionalProperties": false, "description": "Runtime behavior configuration", "type": "object", "properties": { "input_handling": { "additionalProperties": false, "type": "object", "properties": { "max_input_length": { "minimum": 1, "type": "integer" }, "content_types": { "description": "Accepted MIME types (e.g., text/plain, application/json)", "type": "array", "items": { "type": "string" } }, "sanitization": { "additionalProperties": false, "type": "object", "properties": { "enabled": { "type": "boolean" }, "strip_html": { "type": "boolean" }, "max_input_length": { "minimum": 1, "type": "integer" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "extensions": { "$ref": "#/$defs/extensions" } } }, "output_handling": { "additionalProperties": false, "type": "object", "properties": { "max_output_length": { "minimum": 1, "type": "integer" }, "format": { "type": "string", "enum": [ "text", "json", "markdown", "html" ] }, "streaming": { "type": "boolean" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "tool_invocation": { "additionalProperties": false, "type": "object", "properties": { "parallel": { "type": "boolean" }, "max_concurrent": { "minimum": 1, "type": "integer" }, "timeout_ms": { "minimum": 0, "type": "integer" }, "max_iterations": { "minimum": 1, "type": "integer" }, "max_tool_calls_per_session": { "minimum": 1, "type": "integer" }, "loop_detection": { "additionalProperties": false, "type": "object", "properties": { "window": { "minimum": 2, "type": "integer" }, "on_detected": { "$ref": "#/$defs/degradationResponse" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "retry_policy": { "additionalProperties": false, "type": "object", "properties": { "max_retries": { "minimum": 0, "type": "integer" }, "backoff_strategy": { "type": "string", "enum": [ "fixed", "exponential", "linear" ] }, "initial_delay_ms": { "minimum": 0, "type": "integer" }, "max_delay_ms": { "minimum": 0, "type": "integer" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "extensions": { "$ref": "#/$defs/extensions" } } }, "error_handling": { "additionalProperties": false, "type": "object", "properties": { "on_tool_error": { "type": "string", "enum": [ "abort", "continue", "retry" ] }, "max_retries": { "minimum": 0, "type": "integer" }, "fallback_behavior": { "additionalProperties": false, "type": "object", "properties": { "action": { "type": "string", "enum": [ "return_error", "use_default", "skip" ] }, "default": { "description": "Default value when action is use_default" }, "message": { "type": "string" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "extensions": { "$ref": "#/$defs/extensions" } } }, "degradation": { "type": "object", "properties": { "extensions": { "$ref": "#/$defs/extensions" } }, "patternProperties": { "^on_[a-z0-9_]+$": { "$ref": "#/$defs/degradationResponse" } }, "additionalProperties": false, "description": "Behavior when an operational limit is reached or a fault occurs, keyed by cause (enforced by Runtime Protocol §6)" }, "extensions": { "$ref": "#/$defs/extensions" } } }, "metadata": { "additionalProperties": false, "description": "Additional metadata", "type": "object", "properties": { "authors": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "name": { "type": "string" }, "email": { "format": "email", "type": "string" }, "url": { "format": "uri", "type": "string" }, "extensions": { "$ref": "#/$defs/extensions" } } } }, "license": { "type": "string" }, "documentation": { "format": "uri", "type": "string" }, "repository": { "format": "uri", "type": "string" }, "tags": { "type": "array", "items": { "pattern": "^[a-z0-9][a-z0-9-]*$", "type": "string" } }, "extensions": { "$ref": "#/$defs/extensions" } } }, "profiles": { "description": "Profile identifiers (URIs or registered names)", "type": "array", "items": { "type": "string" } }, "extensions": { "$ref": "#/$defs/extensions" } } }