adl

ADL — Agent Definition Language

Overview

ADL is a vendor-neutral, declarative specification for defining AI agents — their identity, capabilities, tools, permissions, and governance metadata. It acts as a portable blueprint (like OpenAPI for APIs) that is independent of any runtime, framework, or vendor. Open-sourced by Next Moca under Apache 2.0, also adopted by Eclipse LMOS.

Purpose

ADL defines what an agent is and what it can do, not how it runs. It complements:

• MCP — how agents call tools at runtime
• A2A — how agents communicate
• Agent Skills — how capabilities are packaged

Example

adl: "1.0"

agent:
  name: research-assistant
  version: "1.0.0"
  description: "Researches topics and produces structured summaries"
  author: "team-name"
  license: MIT

  llm:
    provider: anthropic
    model: claude-sonnet-4-5-20250929
    temperature: 0.3
    max_tokens: 4096
    system_prompt: |
      You are a research assistant. Produce well-structured,
      factual summaries with cited sources.

  tools:
    - name: web-search
      type: mcp
      server: "search-server"
      description: "Search the web for information"
    - name: read-document
      type: mcp
      server: "doc-server"
      description: "Read and parse documents"

  rag:
    - name: knowledge-base
      source: "vector-store://company-docs"
      description: "Internal documentation and policies"

  permissions:
    allowed_tools:
      - web-search
      - read-document
    denied_actions:
      - file_write
      - code_execution
    boundaries:
      max_tokens_per_request: 8192
      max_requests_per_minute: 30

  dependencies:
    - name: fact-checker
      type: agent
      description: "Validates factual claims before including them"

  governance:
    owner: "research-team@company.com"
    review_status: approved
    last_reviewed: "2026-01-15"
    tags:
      - research
      - internal

Schema Sections

Agent Identity

Field	Description
name	Unique agent identifier
version	Semantic version
description	What the agent does
author	Creator or team
license	SPDX identifier

LLM Configuration

Field	Description
provider	Model provider (anthropic, openai, etc.)
model	Specific model ID
temperature	Sampling temperature
max_tokens	Maximum output tokens
system_prompt	System-level instructions

Tools

Declares which tools the agent can use, with type and connection info.

RAG

Declares knowledge sources the agent can access for retrieval-augmented generation.

Permissions & Boundaries

Defines what the agent is allowed and forbidden to do, plus rate limits and resource caps.

Dependencies

Other agents or services this agent relies on.

Governance

Ownership, review status, and audit metadata for enterprise compliance.

ADL vs Other Formats

Aspect	ADL	AGENTS.md	Agent Skills
Focus	Agent definition (identity + config)	Project-level coding guidance	Reusable capability packaging
Format	Structured YAML schema	Freeform Markdown	YAML frontmatter + Markdown
Scope	Per-agent blueprint	Per-project instructions	Per-skill instructions
Runtime	Framework-agnostic	N/A	Platform-agnostic

Best Practices

• Define permissions explicitly — principle of least privilege for tools and actions.
• Use semantic versioning so dependent systems can track agent changes.
• Include governance metadata (owner, review status) for enterprise audit trails.
• Keep system prompts in ADL rather than hardcoded in application code for portability.
• Declare dependencies on other agents explicitly so the orchestration layer knows the graph.
• Use ADL alongside MCP (tool runtime) and A2A (communication) — ADL defines the agent, the other protocols run it.