Tyler-R-Kendrick/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: "[email protected]"
    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.