Agent Definition Language (ADL)

1.1. Purpose

The Agent Definition Language (ADL) provides a standard format for describing AI agents. ADL documents are JSON objects that describe an agent's identity, capabilities, tools, permissions, and runtime requirements. This specification describes the structure of ADL documents, the semantics of their members, and conformance requirements for implementations.¶

ADL serves a similar role for AI agents that OpenAPI serves for REST APIs, AsyncAPI for event-driven architectures, and WSDL for web services. It enables:¶

• Discovery: Agents can be found and understood programmatically.¶

• Interoperability: Agents can interact with tools, resources, and other agents using a common description format.¶

• Deployment: Runtime environments can provision and configure agents based on declared requirements.¶

• Security: Permission boundaries and security requirements are explicitly declared and enforceable.¶

• Lifecycle: Agents can be versioned, tracked through operational states, and managed across their entire lifecycle from draft to retirement.¶

1.2. Goals

• Portable: ADL documents describe agents independent of any specific runtime, platform, or provider.¶

• Interoperable: ADL documents can be transformed into other formats (A2A Agent Cards, MCP configurations) and consumed by diverse tooling.¶

• Extensible: ADL supports profiles that add domain-specific requirements without changing the core specification.¶

• Secure: Permission boundaries, authentication, and security constraints are first-class concepts.¶

• Machine-readable: ADL documents are validated against JSON Schema and can be processed programmatically.¶

• Human-friendly: Clear naming conventions and structures that are easy to read and author.¶

1.3. Relationship to Other Specifications

ADL builds upon and interoperates with:¶

• **JSON [RFC8259] -- ADL documents are valid JSON.¶

• JSON Schema [JSON-SCHEMA] -- ADL documents are validated against JSON Schema; tool parameters use JSON Schema for types.¶

• A2A Protocol [A2A] -- ADL documents can generate A2A Agent Cards.¶

• Model Context Protocol (MCP) [MCP] -- ADL documents can generate MCP server configurations; tools, resources, and prompts align with MCP primitives.¶

• OpenAPI [OPENAPI] -- ADL can reference OpenAPI specifications for HTTP-based tools.¶

• W3C DIDs [W3C.DID] / Verifiable Credentials [W3C.VC] -- ADL supports DIDs for cryptographic identity and VCs for attestations.¶

4.1. Media Type

• ADL documents use the media type application/adl+json.¶

• ADL documents MUST be encoded in UTF-8.¶

• ADL documents MUST be valid JSON [RFC8259].¶

• Member names MUST use snake_case (lowercase with underscores).¶

• All timestamps MUST be ISO 8601 strings with timezone (e.g., "2026-02-15T14:30:00Z").¶

• All URIs MUST conform to [RFC3986].¶

• YAML authoring and JSON canonical form: YAML is an authoring convenience; JSON is the canonical wire format. When an ADL document is authored in YAML, implementations MUST convert it to JSON for processing and validation. The media type application/adl+json applies to the JSON canonical form.¶

4.2. Top-Level Object

An ADL document MUST be a single JSON object.¶

Required members:¶

• adl_spec (Section 5.1)¶

• name (Section 5.3)¶

• description (Section 5.4)¶

• version (Section 5.5)¶

• data_classification (Section 10.4)¶

Optional members:¶

• $schema, id, provider, cryptographic_identity, lifecycle, model, system_prompt, tools, resources, prompts, permissions, security, runtime, metadata, profiles¶

An ADL document MUST NOT contain members not defined by this specification, a declared profile, or the extension mechanism.¶

4.3. Extension Mechanism

• Profiles: Add domain-specific requirements and members; declared in profiles. See Section 13.¶

• Extension members: Custom data without a full profile. Names MUST be prefixed with x_ followed by a namespace identifier (e.g., x_acme_internal_id).¶

Implementations MUST preserve extension members when processing but MAY ignore their contents. Implementations MUST NOT reject documents containing unknown x_-prefixed members.¶

Extension members (prefixed with x_) MAY appear in any object within an ADL document, including nested objects such as lifecycle, provider, model, permissions, and security. Extension member names MUST match the pattern x_ followed by a namespace identifier using only lowercase letters, digits, and underscores (e.g., x_acme_internal_id). Extension member names MUST conform to the ext-member-name production in Appendix D.¶

Example:¶

json { "name": "Invoice Processor", "version": "2.0.0", "adl_spec": "0.1.0", "description": "Processes and routes invoices.", "data_classification": { "sensitivity": "confidential" }, "x_acme_internal_id": "inv-proc-007", "x_acme_cost_center": "engineering", "model": { "name": "acme-large-2024", "x_acme_model_tier": "premium" } } ¶

4.4. Pattern Matching

Several ADL members use patterns to specify allowed or denied values. ADL defines a minimal pattern syntax based on a subset of glob matching rules. The following constructs are supported:¶

1. Literal match. A string with no wildcard characters matches only itself. Matching is case-sensitive unless the underlying system is case-insensitive (e.g., Windows filesystem paths).¶

2. Single-segment wildcard (*). The * character matches zero or more characters within a single segment. The segment boundary depends on context:¶

   • Host patterns (Section 9.2): segments are separated by . (dot). * does not match dots. *.example.com matches api.example.com but does not match deep.sub.example.com.¶

   • Environment variable patterns (Section 9.4): * matches any characters in the variable name. APP_* matches APP_PORT and APP_HOST.¶

   • Command patterns (Section 9.5): * matches any characters in the command name.¶

3. Multi-segment wildcard (**). The ** sequence matches zero or more path segments including separators. Valid only in filesystem path patterns (Section 9.3). /data/** matches /data/, /data/foo, and /data/foo/bar/baz. ** MUST NOT appear in host patterns, environment variable patterns, or command patterns.¶

4. Restrictions. Patterns MUST contain wildcards only in the positions described above. Mid-string wildcards (e.g., foo*bar) are NOT RECOMMENDED; implementations MAY reject them. A bare * as an entire pattern (matching everything) is valid but NOT RECOMMENDED for security-sensitive domains (allowed_hosts, allowed_variables). Implementations SHOULD warn when a bare * wildcard is used in permission patterns.¶

Implementations MUST apply patterns using the rules defined in this section. Implementations MUST NOT interpret patterns as regular expressions. Formal grammar productions for pattern elements are defined in Appendix D.¶

5.1. ADL Specification

Specifies the ADL specification version the document conforms to.¶

• REQUIRED. Value MUST be a string in semantic versioning format (MAJOR.MINOR.PATCH). The format MUST conform to the semver production in Appendix D.¶

• Implementations MUST reject documents with an unsupported adl_spec version.¶

• Implementations SHOULD support documents with the same MAJOR version and lower or equal MINOR version.¶

• Pre-release suffixes (e.g., "0.1.0-draft") MUST NOT appear in adl_spec values. Only release versions are valid for conformance. Pre-release identifiers MAY appear in the agent's own version member (Section 5.5).¶

Example: "adl_spec": "0.1.0"¶

5.2. $schema

Optional. URI reference to the JSON Schema for validation. RECOMMENDED for JSON documents (enables IDE validation). Canonical schema URI for ADL 0.1: https://adl-spec.org/0.1/schema.json.¶

5.3. Name

Human-readable name for the agent. REQUIRED. Value MUST be a non-empty string. For machine identifiers, use id (Section 6.1).¶

5.4. Description

Human-readable description of the agent's purpose and capabilities. REQUIRED. Value MUST be a non-empty string. SHOULD be sufficient for users to understand what the agent does without examining tool definitions.¶

5.5. Version

Agent's version. REQUIRED. Value MUST be a string in semantic versioning format (MAJOR.MINOR.PATCH); the format MUST conform to the semver production in Appendix D. Agent version changes SHOULD follow SemVer (MAJOR: breaking; MINOR: new capabilities; PATCH: fixes, docs).¶

5.6. Lifecycle

Operational lifecycle status of the agent. OPTIONAL. When present, value MUST be an object containing at minimum a status member.¶

6.1. Id

Unique identifier for the agent. OPTIONAL. When present, value MUST be a string and MUST be a valid URI [RFC3986] or URN [RFC8141].¶

Identifier formats, in order of preference:¶

1. HTTPS URI (RECOMMENDED): https://{domain}/agents/{name} -- Provides ownership verification via TLS, direct resolution to the agent's ADL document, and natural integration with .well-known discovery (Section 6.4). The domain authority SHOULD serve the ADL document at the identifier URL with media type application/adl+json.¶

2. Decentralized Identifier: did:web:{domain}:agents:{name} -- Provides cryptographic identity binding via the DID Document. Resolution follows the did:web method specification [W3C.DID]. RECOMMENDED when cryptographic verification of agent identity is required independent of transport.¶

3. URN (offline/catalog use): urn:adl:{namespace}:{name}:{version} -- Location-independent identifier suitable for air-gapped environments, offline catalogs, and internal registries where network resolution is unavailable. URN identifiers provide naming only; they do not support ownership verification or discovery without an external resolver.¶

When an agent has both a resolvable identifier (HTTPS URI or DID) and a URN, the resolvable identifier SHOULD be used as the primary id value. The URN MAY be recorded in metadata for catalog interoperability.¶

• Note: The urn:adl: namespace identifier is used as a convention in this specification but is not yet a registered URN namespace per [RFC8141]. Formal registration with IANA will be pursued in a future revision. Implementations SHOULD NOT assume that urn:adl: URNs are globally resolvable.¶

6.2. Provider

Identifies the organization or entity that provides the agent. OPTIONAL. When present, value MUST be an object:¶

6.3. Cryptographic Identity

Cryptographic identification for the agent. OPTIONAL. When present, value MUST be an object:¶

At least one of did or public_key SHOULD be present. The public_key object, when present, MUST contain algorithm (string, REQUIRED) and value (string, Base64-encoded, REQUIRED). Implementations SHOULD reject weak algorithms (e.g., RSA below 2048 bits, DSA, ECDSA below P-256). EdDSA (Ed25519, Ed448) is RECOMMENDED.¶

Example (agent identity with DID and public key):¶

json { "id": "https://acme.example.com/agents/invoice-processor", "provider": { "name": "Acme Corp", "url": "https://acme.example.com", "contact": "ai-platform@acme.example.com" }, "cryptographic_identity": { "did": "did:web:acme.example.com:agents:invoice-processor", "public_key": { "algorithm": "Ed25519", "value": "MCowBQYDK2VwAyEAGb9ECWmEzf6FQbrBZ9w7lshQhqowtrbLDFw4rXAxZuE=" } } } ¶

6.4. Discovery

Agent discovery enables clients to locate agents published by a domain without prior knowledge of individual agent identifiers. Domains hosting ADL agents MAY publish a discovery document at the well-known URI [RFC8615]:¶

https://{domain}/.well-known/adl-agents ¶

The discovery document, when present, MUST be a JSON object served with media type application/json and MUST contain an agents array. Each entry in the array MUST be an object with at least id (string, the agent's identifier per Section 6.1) and adl_document (string, URL to the full ADL document). Entries MAY include name, version, description, and status.¶

Example discovery document:¶

json { "adl_discovery": "1.0", "agents": [ { "id": "https://acme.example.com/agents/invoice-processor", "adl_document": "https://acme.example.com/agents/invoice-processor/adl.json", "name": "Invoice Processor", "version": "2.0.0", "status": "active" }, { "id": "https://acme.example.com/agents/research-assistant", "adl_document": "https://acme.example.com/agents/research-assistant/adl.json", "name": "Research Assistant", "version": "2.1.0", "status": "active" } ] } ¶

Clients performing discovery MUST fetch the discovery document over HTTPS. Clients SHOULD validate the TLS certificate chain. The discovery document SHOULD be cacheable; servers SHOULD set appropriate Cache-Control headers.¶

• Note: Registration of .well-known/adl-agents with IANA per [RFC8615] will be pursued alongside the IETF Internet-Draft submission.¶

7.1. Model

AI model configuration. OPTIONAL. When omitted, the runtime determines the model. When present, value MUST be an object:¶

capabilities values may include: function_calling, vision, code_execution, streaming.¶

7.2. System Prompt

System prompt for the agent. OPTIONAL. Value MUST be a string or an object. When an object, it MUST contain template (string, REQUIRED) and MAY contain variables (object).¶

8.1. Tools

Array of tool objects (functions the agent can invoke). OPTIONAL. Each tool MUST contain name (string, REQUIRED) and description (string, REQUIRED). Each tool MAY contain: parameters (JSON Schema), returns (JSON Schema), examples, requires_confirmation (bool), idempotent (bool), read_only (bool), annotations, data_classification (Section 10.4). Tool names MUST be unique, MUST match ^[a-z][a-z0-9_]*$, and MUST conform to the tool-name production in Appendix D. The parameters and returns objects, when present, MUST be valid JSON Schema.¶

The examples member, when present, MUST be an array of example objects. Each example object MAY contain:¶

The annotations member, when present, MUST be an object containing implementation hints and metadata. Annotations is an open object -- implementations MAY add custom keys. Standard annotation members include:¶

See Section 15.3 for OpenAPI integration details. Implementations MUST preserve all annotation members when processing, including unrecognized keys.¶

Example:¶

json { "tools": [ { "name": "search_invoices", "description": "Search for invoices by vendor name, date range, or amount.", "parameters": { "type": "object", "properties": { "vendor": { "type": "string", "description": "Vendor name to search" }, "date_from": { "type": "string", "format": "date" }, "date_to": { "type": "string", "format": "date" } }, "required": [] }, "returns": { "type": "array", "items": { "type": "object" } }, "examples": [ { "name": "Search by vendor", "input": { "vendor": "Acme Supplies" }, "output": [{ "id": "INV-001", "amount": 1500.00 }] } ], "idempotent": true, "read_only": true, "annotations": { "openapi_ref": "https://api.acme.example.com/openapi.json", "operation_id": "searchInvoices" }, "data_classification": { "sensitivity": "confidential" } } ] } ¶

8.2. Resources

Array of resource objects (data sources the agent can access). OPTIONAL. Each resource MUST contain name (string, REQUIRED) and type (string, REQUIRED). type MUST be one of: vector_store, knowledge_base, file, api, database. Each resource MAY contain: description, uri, mime_types, schema, annotations, data_classification (Section 10.4). Resource names MUST be unique.¶

The mime_types member, when present, MUST be an array of strings. Each value MUST be a valid MIME type (e.g., "application/json", "text/plain").¶

The schema member, when present, MUST be a valid JSON Schema describing the structure of the resource's data.¶

The annotations member, when present, MUST be an object. Same semantics as tool.annotations -- an open object for implementation hints that MUST be preserved when processing.¶

Example:¶

json { "resources": [ { "name": "invoice_store", "type": "vector_store", "description": "Vector store containing indexed invoice documents for semantic search.", "uri": "https://store.acme.example.com/invoices", "mime_types": ["application/pdf", "application/json"], "data_classification": { "sensitivity": "confidential" } } ] } ¶

8.3. Prompts

Array of prompt objects (reusable prompt templates). OPTIONAL. Each prompt MUST contain name (string, REQUIRED) and template (string, REQUIRED). Each prompt MAY contain description, arguments (JSON Schema). Template arguments use {{argument_name}} and MUST conform to the template-var production in Appendix D. Prompt names MUST be unique.¶

Example:¶

json { "prompts": [ { "name": "summarize_invoice", "description": "Summarizes an invoice for a reviewer.", "template": "Summarize the following invoice for {{reviewer_role}}:\n\n{{invoice_text}}\n\nHighlight amounts over {{threshold}}.", "arguments": { "type": "object", "properties": { "reviewer_role": { "type": "string" }, "invoice_text": { "type": "string" }, "threshold": { "type": "number" } }, "required": ["reviewer_role", "invoice_text"] } } ] } ¶

9.1. Permissions Model

Permissions operate on a deny-by-default model. Runtimes MUST deny any capability not explicitly granted in the permissions member. Runtimes MUST enforce declared permissions. Runtimes that cannot enforce a specific permission domain MUST warn users before execution and SHOULD refuse to execute the agent unless the user explicitly acknowledges the limitation.¶

When the permissions member is omitted from an ADL document, no permissions are granted to the agent. Runtimes MUST treat the absence of permissions as equivalent to an empty permissions object -- the agent has no granted capabilities.¶

When a specific permission domain (e.g., network, filesystem) is omitted from the permissions object, all operations in that domain are denied. For example, if permissions is present but does not contain network, the agent MUST have no network access.¶

Runtimes MUST NOT infer, assume, or provide default permissions when permissions or a permission domain is absent.¶

9.2. Network

May contain: allowed_hosts (array of host patterns), allowed_ports, allowed_protocols, deny_private (bool). Host patterns support exact match and *.example.com.¶

Host patterns in allowed_hosts MUST conform to the pattern syntax defined in Section 4.4.¶

9.3. Filesystem

May contain: allowed_paths (array of { path, access } where access is read, write, or read_write), denied_paths.¶

Path patterns in allowed_paths[*].path and denied_paths MUST conform to the pattern syntax defined in Section 4.4. The ** multi-segment wildcard is valid in filesystem path patterns.¶

9.4. Environment

May contain: allowed_variables, denied_variables (patterns with wildcards, e.g., APP_*).¶

Variable patterns in allowed_variables and denied_variables MUST conform to the pattern syntax defined in Section 4.4.¶

9.5. Execution

May contain: allowed_commands, denied_commands, allow_shell (bool).¶

Command patterns in allowed_commands and denied_commands MUST conform to the pattern syntax defined in Section 4.4.¶

9.6. Resource Limits

May contain: max_memory_mb, max_cpu_percent, max_duration_sec, max_concurrent.¶

Example (complete permissions object):¶

json { "permissions": { "network": { "allowed_hosts": ["api.acme.example.com", "*.storage.example.com"], "allowed_ports": [443], "allowed_protocols": ["https"], "deny_private": true }, "filesystem": { "allowed_paths": [ { "path": "/data/invoices/**", "access": "read" }, { "path": "/tmp/processing/**", "access": "read_write" } ], "denied_paths": ["/tmp/processing/**/secrets"] }, "environment": { "allowed_variables": ["APP_*", "INVOICE_*"], "denied_variables": ["APP_SECRET_*"] }, "execution": { "allowed_commands": ["python3", "jq"], "allow_shell": false }, "resource_limits": { "max_memory_mb": 512, "max_cpu_percent": 25, "max_duration_sec": 300 } } } ¶

10.1. Authentication

May contain: type (one of none, api_key, oauth2, oidc, mtls), required (bool). Type-specific members (e.g., OAuth2: scopes, token_endpoint; OIDC: issuer, audience) MAY be present.¶

10.2. Encryption

May contain: in_transit (required, min_version), at_rest (required, algorithm).¶

10.3. Attestation

May contain: type (one of self, third_party, verifiable_credential), issuer, issued_at, expires_at (ISO 8601), signature (object). Implementations SHOULD warn when expires_at is in the past or within 30 days.¶

Signature object: When present, MUST contain algorithm, value (Base64url-encoded), signed_content ("canonical" or "digest"). When signed_content is "digest", MUST also include digest_algorithm and digest_value. Supported algorithms include Ed25519 (RECOMMENDED), Ed448, ES256/384/512, RS256, PS256 (RSA >= 2048). Verification: remove signature, serialize with JCS [RFC8785], verify digest if applicable, resolve public key from cryptographic_identity, verify signature.¶

Example:¶

json { "security": { "authentication": { "type": "oauth2", "required": true, "scopes": ["invoices:read", "invoices:write"], "token_endpoint": "https://auth.acme.example.com/oauth/token" }, "encryption": { "in_transit": { "required": true, "min_version": "TLS1.3" }, "at_rest": { "required": true, "algorithm": "AES-256-GCM" } }, "attestation": { "type": "third_party", "issuer": "https://trust.acme.example.com", "issued_at": "2026-01-01T00:00:00Z", "expires_at": "2027-01-01T00:00:00Z" } } } ¶

10.4. Data Classification

The data_classification member declares the sensitivity and categories of data the agent may access, process, or produce. REQUIRED. Value MUST be an object.¶

Data classification is required by NIST FIPS 199, NIST SP 800-60, ISO 27001:2022 Annex A.5.12, FedRAMP, SOC 2, and CMMC. It is the foundational step of security categorization across all major compliance frameworks.¶

This member is a reusable composable attribute. In addition to the required top-level declaration, it MAY also appear within individual tools[*] or resources[*] objects to classify specific capabilities. When present on both the top level and a tool or resource, the tool/resource-level classification applies to that capability.¶

11.1. Input Handling

May contain: max_input_length, content_types, sanitization.¶

The sanitization member, when present, MUST be an object describing input sanitization rules. It MAY contain:¶

The content_types member, when present, MUST be an array of strings. Each value MUST be a valid MIME type specifying an accepted input content type.¶

11.2. Output Handling

May contain: max_output_length, format, streaming (bool).¶

The format member, when present, MUST be a string specifying the default output format. Value MUST be one of: "text", "json", "markdown", "html".¶

11.3. Tool Invocation

May contain: parallel (bool), max_concurrent, timeout_ms, retry_policy.¶

The retry_policy member, when present, MUST be an object describing retry behavior for tool invocations. It MAY contain:¶

11.4. Error Handling

May contain: on_tool_error (abort, continue, or retry), max_retries, fallback_behavior.¶

The fallback_behavior member, when present, MUST be an object describing behavior when errors occur and on_tool_error does not resolve the situation. It MAY contain:¶

Example:¶

json { "runtime": { "input_handling": { "max_input_length": 32768, "content_types": ["text/plain", "application/json"], "sanitization": { "enabled": true, "strip_html": true } }, "output_handling": { "format": "json", "max_output_length": 8192, "streaming": false }, "tool_invocation": { "parallel": true, "max_concurrent": 3, "timeout_ms": 30000, "retry_policy": { "max_retries": 2, "backoff_strategy": "exponential", "initial_delay_ms": 500, "max_delay_ms": 5000 } }, "error_handling": { "on_tool_error": "retry", "max_retries": 2, "fallback_behavior": { "action": "return_error", "message": "Invoice processing temporarily unavailable." } } } } ¶

12.1. Authors

Array of author objects. Each MAY contain name, email, url.¶

12.2. License

String: SPDX license identifier or URI to license document.¶

12.3. Documentation

String: URI to documentation.¶

12.4. Repository

String: URI to source repository.¶

12.5. Tags

Array of strings. SHOULD be lowercase, alphanumeric and hyphens only. Tags SHOULD conform to the tag production in Appendix D.¶

12.6. Example

json { "metadata": { "authors": [ { "name": "Platform Team", "email": "platform@example.com", "url": "https://example.com/team/platform" } ], "license": "Apache-2.0", "documentation": "https://docs.example.com/agents/invoice-processor", "repository": "https://github.com/example/invoice-processor", "tags": ["finance", "invoice", "production"] } } ¶

14.1. Parsing

Implementations MUST parse ADL as JSON [RFC8259], MUST reject invalid JSON, and MUST reject documents where the top-level value is not a JSON object.¶

14.2. Validation

Implementations MUST validate ADL documents against the JSON Schema defined in Appendix A. Implementations MUST validate the following semantic rules:¶

Implementations MAY perform additional validation based on declared profiles.¶

14.3. Unknown Members

Implementations MUST preserve unrecognized members when round-tripping. Implementations MUST NOT reject documents containing unknown x_-prefixed members. Implementations MAY warn on unknown non-extension, non-profile members.¶

15.1. A2A Agent Card Generation

Implementations SHOULD support generating A2A Agent Cards from ADL (e.g., name, description, version, tools->skills, cryptographic_identity.did->id, security.authentication->authentication).¶

15.2. MCP Server Configuration

Implementations SHOULD support generating MCP server configurations (name, description, version, tools, resources, prompts).¶

15.3. OpenAPI Integration

Tools that invoke HTTP APIs MAY reference OpenAPI specs. The tool annotations object MAY contain openapi_ref (URI) and operation_id.¶

16.1. Error Format

Implementations SHOULD return errors in a consistent format, e.g.:¶

json { "errors": [ { "code": "ADL-1001", "title": "Invalid JSON", "detail": "Unexpected token at line 42, column 15", "source": { "pointer": "/tools/0/name" } } ] } ¶

The source object MAY contain: pointer (JSON Pointer to the error location), line (1-indexed), column (1-indexed).¶

16.2. Error Codes

16.3. Error Source Examples

The source.pointer member uses JSON Pointer [RFC6901] to identify the location of the error within the ADL document. The following examples illustrate source values for representative error codes from each category:¶

json // ADL-1003 (Schema): Missing required member "data_classification" { "code": "ADL-1003", "title": "Missing required member", "detail": "Required member 'data_classification' is missing", "source": { "pointer": "" } } ¶

json // ADL-2002 (Semantic): Duplicate tool name at index 2 { "code": "ADL-2002", "title": "Duplicate tool name", "detail": "Tool name 'search_documents' already defined at index 0", "source": { "pointer": "/tools/2/name" } } ¶

json // ADL-2016 (Semantic): Invalid host pattern in permissions { "code": "ADL-2016", "title": "Invalid host pattern syntax", "detail": "Pattern '**' is not a valid host pattern", "source": { "pointer": "/permissions/network/allowed_hosts/1" } } ¶

json // ADL-2023 (Semantic): High-water mark violation on a tool { "code": "ADL-2023", "title": "High-water mark violation", "detail": "Tool 'query_records' has sensitivity 'confidential' which exceeds top-level 'internal'", "source": { "pointer": "/tools/1/data_classification/sensitivity" } } ¶

json // ADL-3001 (Profile): Profile requirement not satisfied { "code": "ADL-3001", "title": "Profile requirements not satisfied", "detail": "Governance profile requires 'compliance' member", "source": { "pointer": "/profiles/0" } } ¶

json // ADL-4001 (Security): Weak key algorithm { "code": "ADL-4001", "title": "Weak key algorithm", "detail": "Algorithm 'RS256' with 1024-bit key does not meet minimum strength requirements", "source": { "pointer": "/security/attestation/public_key" } } ¶

json // ADL-5002 (Lifecycle): Successor on active agent { "code": "ADL-5002", "title": "Successor present on non-retired agent", "detail": "Member 'successor' is only valid when lifecycle.status is 'retired'", "source": { "pointer": "/lifecycle/successor" } } ¶

17.1. Media Type

This document requests IANA to register the application/adl+json media type in the "Media Types" registry in accordance with [RFC6838].¶

• Type name: application¶

• Subtype name: adl+json¶

• Required parameters: None¶

• Optional parameters:¶

  • profile -- A comma-separated list of ADL profile identifiers (URIs or registered names from the ADL Profile Registry defined in Section 17.2) that the document conforms to. Each identifier MUST be a URI conforming to [RFC3986]. Consumers that do not recognize a profile identifier MAY ignore the parameter and MUST preserve it when retransmitting the document.¶

• Encoding considerations: binary -- ADL documents are JSON text sequences encoded in UTF-8 [RFC8259]. No other character encoding is permitted. Consistent with [RFC8259], UTF-8 without a byte-order mark (BOM) is RECOMMENDED.¶

• Security considerations: ADL documents declare agent behavior including permission grants, system prompt templates, tool invocation configuration, and cryptographic identity. Processors MUST treat content from untrusted sources with appropriate caution. Template variables in system_prompt and prompt templates use a {{variable_name}} substitution syntax; processors MUST sanitize variable values before substitution to prevent prompt injection attacks that could alter agent behavior. ADL documents include URI references in fields such as $schema, openapi_ref, documentation, and repository; processors MUST NOT automatically dereference these URIs from untrusted documents, as doing so may target internal network resources and enable Server-Side Request Forgery (SSRF). Documents that declare broad permissions (e.g., a bare * wildcard in allowed_hosts) represent elevated risk and SHOULD require explicit human review before deployment. Processors SHOULD impose limits on document size, JSON nesting depth, and array lengths to prevent resource exhaustion from adversarially crafted documents. For a comprehensive treatment of all security considerations applicable to this media type, see Section 18.¶

• Interoperability considerations: ADL documents MUST be processed as JSON [RFC8259] regardless of authoring format. YAML is a common authoring convenience, but processors MUST operate on the JSON form; documents intended to be signed using JCS [RFC8785] MUST be serialized as JSON before signing. Profile declarations -- whether via the profile optional parameter or the profiles document member -- allow multiple profiles to compose within a single document; consumers that partially implement profile requirements SHOULD process the members they recognize and preserve unrecognized members per Section 14.3. Validation against the JSON Schema defined in Appendix A provides a baseline interoperability check. Implementations that generate A2A Agent Cards or MCP server configurations from ADL documents SHOULD follow the mappings defined in Section 15. Producers SHOULD include the $schema member to enable tooling-assisted validation.¶

• Published specification: [this document]¶

• Applications that use this media type: AI agent platforms, agent registries, development tools, orchestration frameworks, and runtime environments that provision and manage AI agents.¶

• Fragment identifier considerations: Fragment identifiers for resources of this type SHOULD be interpreted as JSON Pointer expressions [RFC6901] identifying a location within the ADL document object.¶

• Additional information:¶

  • Deprecated alias names for this type: N/A¶

  • Magic number(s): N/A¶

  • File extension(s): .adl.json, .adl¶

  • Macintosh file type code(s): N/A¶

  • Object Identifiers: N/A¶

• Person and email address to contact for further information: See the Author's Address section of this document.¶

• Intended usage: COMMON¶

• Restrictions on usage: None¶

• Author: See the Author's Address section of this document.¶

• Change controller: IETF¶

17.2. Profile Registry

IANA is requested to create and maintain a new registry titled "ADL Profile Registry" within a new "Agent Definition Language (ADL)" registry group.¶

Registration Policy: Specification Required [RFC8126]. The designated expert reviews registration requests to verify that the profile is documented in a publicly available, stable specification and that all required registration template fields are complete.¶

Registration Template: Parties wishing to register a profile MUST provide all of the following fields:¶

Initial Registry Contents:¶

All initial entries reference Appendix C of this document, target ADL compatibility 0.1.x, are active, and list the Author's Address as contact.¶

Designated Expert Criteria: The designated expert SHOULD evaluate requests against the following criteria:¶

1. Publicly available specification: The profile specification MUST be accessible at a stable, public URI. Specifications behind paywalls or access controls are not acceptable for registration.¶

2. Non-conflict with core ADL: The profile MUST NOT redefine or contradict normative requirements of the core ADL specification. Profiles MAY add new members, constrain optional members to a subset of permitted values, or require that optional core members be present.¶

3. Complete registration template: All required template fields MUST be present and non-empty. Incomplete registrations MUST be returned to the submitter.¶

4. Stable identifier: The profile URI SHOULD be dereferenceable and SHOULD remain stable over time. Ephemeral or frequently changing URIs are not acceptable.¶

5. Legitimate purpose: The profile SHOULD address a genuine domain or deployment need not already covered by an existing active registered profile.¶

17.3. URN Namespace

IANA is requested to register the adl URN namespace identifier in the "Formal URN Namespaces" registry in accordance with [RFC8141].¶

• Namespace Identifier: adl¶

• Version: 1¶

• Date: [date of publication]¶

• Registrant: See the Author's Address section of this document.¶

• Purpose: The urn:adl: namespace provides persistent, location-independent identifiers for ADL agents, profiles, and related artifacts. These identifiers are intended for use in offline catalogs, air-gapped environments, and internal registries where network resolution is unavailable. For connected environments, HTTPS URIs (Section 6.1) are the RECOMMENDED identifier format.¶

• Syntax: URNs in this namespace conform to the following structure: urn:adl:{type}:{namespace}:{name}:{version} where {type} is one of agent or profile, {namespace} is a lowercase alphanumeric organization identifier, {name} is a lowercase alphanumeric resource name with hyphens, and {version} is a semantic version string. The formal syntax is defined by the adl-urn production in Appendix D.¶

• Assignment: Sub-namespace assignment under urn:adl:profile: is governed by the ADL Profile Registry (Section 17.2). Sub-namespace assignment under urn:adl:agent: is at the discretion of the namespace holder; no central registry is required for agent URNs.¶

• Security and Privacy: URN identifiers in this namespace are opaque strings and carry no inherent security properties. Implementations MUST NOT infer ownership, trust, or authorization from a urn:adl: identifier alone. Verification of agent identity MUST rely on the mechanisms described in Section 6.3 (Cryptographic Identity) and Section 10.3 (Attestation). See Section 18 for comprehensive security considerations.¶

17.4. Well-Known URI

IANA is requested to register the adl-agents well-known URI suffix in the "Well-Known URIs" registry in accordance with [RFC8615].¶

• URI suffix: adl-agents¶

• Change controller: IETF¶

• Specification document: Section 6.4 of [this document]¶

• Status: permanent¶

• Related information: The well-known URI https://{domain}/.well-known/adl-agents returns a JSON document listing all ADL agents published by the domain authority. The document format is defined in Section 6.4. The resource MUST be served over HTTPS.¶

18.1. Document Integrity

ADL documents define agent behavior, permission grants, and security requirements. The trust model for an ADL document depends on its provenance and the integrity mechanisms applied to it. Unsigned ADL documents from untrusted or unverified sources MUST be treated as potentially malicious.¶

When a document includes a cryptographic signature in security.attestation.signature, implementations MUST verify the signature before acting on the document's permission or security declarations. Signature verification requires serializing the document (with the signature object removed) using JCS [RFC8785] to produce a canonical byte sequence, then verifying the resulting digest using the algorithm and public key declared in cryptographic_identity. Implementations MUST reject documents that claim to be signed but whose signature does not verify. Implementations SHOULD warn when processing signed documents whose attestation has expired (expires_at is in the past). An ADL document whose permissions or capabilities have been modified after signing will produce a different canonical byte sequence and fail signature verification; this is the intended behavior and provides protection against privilege escalation via document tampering.¶

18.2. Sensitive Data in ADL Documents

ADL documents SHOULD NOT contain secrets, credentials, or other sensitive data in plaintext. Fields such as system_prompt, provider.contact, metadata.authors, and tool parameter examples may inadvertently expose confidential information if documents are logged, cached, or transmitted without adequate access controls.¶

API keys, passwords, private keys, bearer tokens, and other authentication material MUST NOT appear as literal string values in ADL documents. Where agent configuration requires secret values at runtime, implementations SHOULD use environment variable references or external secret manager URIs rather than embedding values directly. Implementations SHOULD warn when string values match patterns commonly associated with credentials (e.g., values matching the format of known API key prefixes). Organizations SHOULD subject ADL documents to the same secret-scanning controls applied to source code repositories before storage or distribution.¶

18.3. Template Injection

The system_prompt member (Section 7.2) and prompts[*].template members (Section 8.3) support a template substitution syntax using {{variable_name}} placeholders. If variable values are derived from untrusted user input and substituted without sanitization, an attacker may be able to alter agent behavior by injecting malicious instructions into the rendered prompt -- including instructions that override the intended agent behavior or cause the agent to exfiltrate information.¶

Implementations MUST sanitize template variable values before substitution. At minimum, implementations SHOULD escape or reject values that contain the template delimiter sequence {{ or }}, and SHOULD apply length limits to variable values. Applications that allow end users to supply template variable values SHOULD treat such values as untrusted and apply content validation appropriate to the deployment context. Runtimes operating on agents with data_classification.sensitivity of confidential or restricted SHOULD log rendered prompts (after variable substitution) to enable post-incident review, subject to applicable privacy constraints.¶

18.4. Information Disclosure

ADL documents may reveal infrastructure details that are useful to attackers. The name, description, and tool description fields may disclose the existence of internal services or system architecture. The permissions.network.allowed_hosts list may reveal internal hostname patterns, private IP ranges, or internal service naming conventions. The permissions.filesystem.allowed_paths list may reveal sensitive directory structures. The provider.url, metadata.documentation, and metadata.repository fields may reference internal systems not intended for public visibility.¶

ADL documents intended for public distribution SHOULD be reviewed to remove or generalize infrastructure-specific information. Host patterns SHOULD use registered domain names rather than IP addresses or internal hostnames. Path patterns SHOULD avoid exposing sensitive directory names. Documents with data_classification.sensitivity of confidential or restricted SHOULD only be distributed to parties with appropriate access authorization and SHOULD NOT be published to public registries without thorough review.¶

18.5. Resource Exhaustion

Implementations that parse and validate ADL documents are susceptible to resource exhaustion from adversarially crafted inputs. Specific attack vectors include: deeply nested JSON Schema in parameters and returns members (including circular $ref chains or exponentially expanding allOf/anyOf combinators); documents with very large numbers of tools, resources, or prompts; and documents with excessively long string values in system_prompt, description fields, or pattern arrays.¶

Implementations SHOULD enforce and document limits on: total document size (recommended maximum: 1 MB); JSON nesting depth (recommended maximum: 32 levels); number of entries in tools, resources, and prompts arrays (recommended maximum: 1000 each); string length for system_prompt and description fields (recommended maximum: 1 MB per field); and number of entries in any permission pattern array (recommended maximum: 500 patterns per domain). Implementations SHOULD terminate processing with an appropriate error code when any of these limits is exceeded rather than continuing to consume resources.¶

18.6. Pattern Matching Abuse

The permission pattern syntax (Section 4.4) governs access grants across network, filesystem, environment variable, and execution domains. Overly permissive patterns undermine the deny-by-default permission model; patterns that are expensive to evaluate can enable denial-of-service.¶

A bare * as the sole value of an entry in allowed_hosts grants access to all hostnames and effectively disables network permission enforcement. Implementations MUST warn when a bare * wildcard is used in any security-sensitive permission pattern, including allowed_hosts and allowed_variables. Implementations SHOULD require explicit user acknowledgment -- or refuse to deploy -- agents that use bare * patterns in these domains. Pattern evaluation SHOULD be bounded in time and space: implementations that use backtracking pattern matchers SHOULD reject or normalize patterns that would require exponential backtracking (e.g., consecutive wildcards such as ***). The ** multi-segment wildcard MUST NOT appear in host, environment, or command patterns, and implementations MUST reject documents in which it does.¶

18.7. URI Reference Attacks (SSRF)

Multiple ADL fields accept URI values: $schema, id, provider.url, metadata.documentation, metadata.repository, resource.uri, tool.annotations.openapi_ref, lifecycle.successor, security.attestation.issuer, and others defined by profiles. If an implementation automatically dereferences these URIs when processing a document from an untrusted source, an attacker may cause the implementation to issue requests to arbitrary endpoints, including internal services not reachable from the public internet -- a class of vulnerability known as Server-Side Request Forgery (SSRF).¶

Implementations MUST NOT automatically dereference URI values from ADL documents received from untrusted sources without explicit operator or user consent. Implementations that fetch external schema documents (e.g., via $schema) for validation purposes SHOULD use an allowlist of trusted schema hosts and MUST NOT follow redirects that leave the trusted set. When fetching openapi_ref documents for tool description or validation, implementations SHOULD verify that the target URI matches a pre-approved allowlist. Implementations SHOULD validate that URI values in ADL documents conform to [RFC3986] and SHOULD reject URIs with schemes other than https, http, or urn unless the deployment context explicitly allows them.¶

18.8. Canonicalization Attacks

ADL supports document integrity verification via cryptographic signatures using JCS canonicalization [RFC8785]. The security of this mechanism depends on all conforming implementations producing identical canonical byte sequences for the same logical document. Subtle differences in JCS implementations -- such as incorrect handling of Unicode escape sequences, floating-point number serialization, or object member ordering -- could cause a legitimate signature to fail verification, or, more critically, allow an attacker to construct a document where different implementations produce different canonical forms, potentially enabling a signature verification bypass.¶

Implementations MUST use a conformant JCS [RFC8785] implementation for both signing and verification. Implementations SHOULD validate their JCS implementation against the test vectors provided in RFC 8785 before use in a production environment. Implementations MUST NOT verify signatures against non-canonical serializations such as pretty-printed JSON or YAML. Implementations that process ADL documents containing IEEE 754 floating-point values in signed content SHOULD be aware that platform-specific floating-point representation differences may affect canonicalization and SHOULD avoid floating-point values in fields that will be signed when possible.¶

18.9. Privacy Considerations

ADL documents may contain personal information subject to applicable privacy regulations. The provider.contact field (Section 6.2) contains a contact email address. The metadata.authors array (Section 12.1) may contain author names, email addresses, and URLs. The system_prompt member may contain information about intended user roles, user populations, or organizational context. When ADL documents are published to public registries or shared broadly, this information becomes publicly accessible.¶

Publishers SHOULD review ADL documents for personally identifiable information (PII) before public distribution and SHOULD use organizational or role-based contact addresses rather than personal email addresses. Implementations that log ADL document contents for debugging or auditing SHOULD redact or omit provider.contact, metadata.authors, and system_prompt fields from logs unless there is a documented operational requirement to retain them. Users SHOULD be informed when their ADL documents are transmitted to third-party services for validation, indexing, or registry queries.¶

18.10. Privilege Escalation

An ADL document that has been modified -- whether by a malicious actor during transmission or by a compromised storage or distribution system -- could grant an agent permissions or capabilities beyond those that were reviewed and approved for deployment. This risk is the primary motivator for the integrity mechanisms described in Section 10.3.¶

Implementations SHOULD verify document integrity (Section 10.3) before enforcing the permissions declared in a document, particularly when documents are retrieved from network locations, shared storage systems, or public registries. Runtimes that cannot verify document integrity SHOULD apply compensating controls -- such as mandatory human review -- before deploying agents that declare elevated permissions or sensitive data access. When a document's data_classification.sensitivity is confidential or restricted, runtimes SHOULD require a verified signature or a verified supply chain (e.g., document retrieved from a trusted registry over an authenticated and integrity-protected channel) before provisioning. Organizations SHOULD maintain an inventory of approved ADL documents along with their expected signatures or cryptographic digests, and SHOULD treat any discrepancy between the recorded and observed document as a potential security incident.¶

18.11. Cross-Origin and Supply Chain Concerns

ADL documents may be fetched from remote sources: registries, source control systems, artifact stores, or agent marketplaces. A document tampered with in transit or at the origin could cause a runtime to provision a malicious agent without the operator's knowledge.¶

ADL documents SHOULD be fetched over authenticated, integrity-protected channels (HTTPS with full certificate validation). Implementations SHOULD verify document signatures (Section 10.3) when documents are retrieved from remote or third-party sources. Implementations SHOULD validate that the signing identity declared in cryptographic_identity matches an expected, trusted identity for the document's declared provider.¶

Supply chain integrity requires attention at every reference boundary: the ADL document itself, referenced OpenAPI specifications (openapi_ref), and external JSON Schemas ($schema). Implementations that automatically resolve external references during provisioning SHOULD pin or verify all such references. When accepting ADL documents from third-party sources, implementations SHOULD apply an allowlist of trusted providers (based on provider.name or id URI authority), verify attestation signatures from trusted issuers, and treat documents from unverified sources with the same caution applied to untrusted executable code.¶

18.12. Permission Model and Defense in Depth

The deny-by-default permission model (Section 9.1) is a foundational security property of ADL: an agent can only access resources and capabilities that its ADL document explicitly permits. However, the effectiveness of this model depends entirely on the runtime correctly enforcing declared permissions. No permission model is a substitute for defense in depth.¶

Runtimes MUST enforce declared permissions and MUST NOT allow agents to exceed those permissions under any circumstances, including error conditions or fallback behaviors. Runtimes that cannot enforce a specific permission domain (e.g., because the underlying platform lacks the required isolation primitives) MUST warn users before execution and SHOULD refuse to execute the agent unless the user explicitly acknowledges the limitation.¶

Beyond permission enforcement, runtimes SHOULD monitor agent behavior during execution: logging tool invocations, recording network destinations contacted, and alerting on anomalous activity such as repeated attempts to access resources outside declared permissions. The ADL document represents intended access boundaries at definition time; runtime monitoring ensures actual behavior remains within those boundaries in production.¶

Runtimes SHOULD validate tool inputs and outputs against the declared JSON Schema (Section 8.1) before passing them to or from the agent. Malformed responses from external tool implementations could inject unexpected data into agent reasoning; runtime-level schema validation provides a defense against malfunctioning or malicious tool backends. Tools annotated with requires_confirmation: true MUST receive explicit user confirmation before invocation; runtimes MUST NOT invoke such tools autonomously regardless of other configuration.¶

Lifecycle status MUST be enforced as a security boundary. Runtimes MUST NOT provision or execute agents with lifecycle.status of retired. Retired agents may have revoked credentials, unpatched vulnerabilities, or stale permission configurations. Agents with lifecycle.status of deprecated SHOULD trigger warnings to operators, who SHOULD migrate to the agent identified by lifecycle.successor before the sunset_date is reached.¶

19.1. Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC3986]

Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, <https://www.rfc-editor.org/rfc/rfc3986>.

[RFC6838]

Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, <https://www.rfc-editor.org/rfc/rfc6838>.

[RFC6901]

Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013, <https://www.rfc-editor.org/rfc/rfc6901>.

[RFC8126]

Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, <https://www.rfc-editor.org/rfc/rfc8126>.

[RFC8141]

Saint-Andre, P. and J. Klensin, "Uniform Resource Names (URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017, <https://www.rfc-editor.org/rfc/rfc8141>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8259]

Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/rfc/rfc8259>.

[RFC8615]

Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, <https://www.rfc-editor.org/rfc/rfc8615>.

19.2. Informative References

[A2A]

A2A Protocol Working Group, "Agent-to-Agent Protocol Specification", 2025, <https://a2a-protocol.org/specification>.

[JSON-SCHEMA]

Wright, A., "JSON Schema: A Media Type for Describing JSON Documents", 2020, <https://json-schema.org/draft/2020-12/json-schema-core>.

[MCP]

Anthropic, "Model Context Protocol Specification", 2024, <https://modelcontextprotocol.io/specification>.

[OPENAPI]

OpenAPI Initiative, "OpenAPI Specification", 2024, <https://spec.openapis.org/oas/v3.1.0>.

[RFC8785]

Rundgren, A., Jordan, B., and S. Erdtman, "JSON Canonicalization Scheme (JCS)", RFC 8785, DOI 10.17487/RFC8785, June 2020, <https://www.rfc-editor.org/rfc/rfc8785>.

[W3C.DID]

Sporny, M., "Decentralized Identifiers (DIDs) v1.0", 2022, <https://www.w3.org/TR/did-core/>.

[W3C.VC]

Sporny, M., "Verifiable Credentials Data Model v1.1", 2022, <https://www.w3.org/TR/vc-data-model/>.

C.1. Available Profiles

See the profiles/ directory for the full profile index and contribution guidelines.¶

D.1. Cross-Reference Summary