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 ```yaml 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.