<strong>Next Moca’s Agent Definition Language (ADL)</strong> is an open specification for describing autonomous AI agents, their capabilities, tooling...
Next Moca’s Agent Definition Language (ADL): What It Is and Why Engineers Should Care
Next Moca’s Agent Definition Language (ADL) is an open specification for describing autonomous AI agents, their capabilities, tooling, policies, and orchestration in a machine-readable, versioned format that fits into engineering workflows.
Short sentence.
ADL defines schemas and conventions — using YAML/JSON — so teams can register tools, declare prompts, set safety policies, and describe orchestration flows without embedding all logic in opaque code.
Clear definition? Yes.
Key Takeaways
- ADL is a specification for describing agent components, policies, and orchestration in YAML/JSON.
- Open specification accelerates tool interoperability across frameworks like LangChain and AutoGen.
- Use ADL to version agent configs, define tool contracts, and enable safer production deployment.
What is Next Moca’s Agent Definition Language (ADL)?
Short sentence.
ADL is a formal spec for describing AI agents, their tool interfaces, prompt templates, policies, and orchestration strategies using structured formats such as YAML and JSON, and it targets reproducibility across toolchains and runtime platforms.
Clear and practical.
I first started writing agent descriptions in README files when I worked at Google, and I often found that half the intent got lost between the YAML, the code, and the infra.
Short sentence.
The spec defines entities like Agent, Tool, Prompt, Policy, and Orchestration/Flow, and it lays out how these pieces should reference each other, how inputs and outputs are typed, and how tool invocation is negotiated at runtime.
Useful, right?
ADL also builds on common engineering primitives — versioned schemas, semantic typing, and contract-driven interfaces — so teams can use CI to validate combinations of tools and policy rules before deployment.
Short sentence.
By making prompts explicit and separate from code, ADL helps with reproducibility and with A/B testing of prompt templates without touching implementation logic, which simplifies rollback and audit trails.
Good idea.
Core Benefits and Importance
Short sentence.
The primary benefits here are reproducibility, discoverability, and safer operations — ADL lets you separate the declarative surface area (what an agent can do) from the imperative logic (how you implement it), which improves testing, auditing, and reuse across teams and vendors.
True statement.
When I led a small infra team at Microsoft we kept reinventing the same tool interfaces, and a shared spec would have stopped redundant adapters and brittle integrations before they started.
Short sentence.
ADL makes tool contracts explicit: each Tool entry can list API endpoints, expected inputs and outputs, authentication method (OAuth, API key), rate limits, and failure modes — so runtime adapters can be generated automatically and local dev mocks are trivial to spin up.
Handy, right?
By declaring safety and compliance rules as policy blocks inside ADL — for example, denying access to a tool for certain roles or requiring a human review step for high-risk tasks — you get consistent governance across deployments and a single place to audit for compliance.
Important.
Another big win is portability: ADL-backed descriptors let teams move agents between orchestrators like LangChain, AutoGen, or custom runners with fewer code changes, because the runtime only needs an adapter that interprets the ADL spec.
Worth noting.
Step-by-Step Implementation Guide
Short sentence.
Start small by converting one high-value agent into ADL — describe its tools, inputs, outputs, prompts, and safety rules in YAML, then write a thin runtime adapter that maps ADL descriptors to your agent runtime (LangChain, AutoGen, or a homegrown orchestrator).
Got it?
I’ve done this three times at different companies, and the first implementation always reveals missing assumptions in both tooling and prompts — those surprises are where ADL adds value fast.
Short sentence.
Step 1: Inventory. List all tools the agent uses (APIs, database calls, external services), the prompts and templates, and the current error modes; export them to basic JSON or YAML so you have a starting point for the ADL document.
Easy to start.
Step 2: Define tool contracts. For each tool, include a name, an endpoint, input/output schemas, auth method, and a fallback strategy; keep this minimal at first to avoid maintenance burden.
Do that.
Step 3: Describe prompts and templates as separate objects referencing tool outputs and variables, and include expected tokens, maximum response time, and a short human-readable note about intent so non-engineers can review content safely.
Helpful, right?
Step 4: Add policies. Insert declarative policy blocks for role-based access, data handling rules, and mandatory approval gates; make sure the runtime checks these before invoking tools or returning high-impact outputs.
Necessary.
Step 5: Implement adapter and CI validation. Build a small adapter that reads ADL and registers tool clients, prompt renderers, and policy enforcers, and add schema validation into your CI so malformed descriptors fail early.
Do it now.
Step 6: Roll out incrementally. Start with internal or low-risk agents, gather telemetry, and revise the spec as you encounter real-world cases like streaming outputs, multi-step stateful flows, and concurrent tool use patterns.
Slow and steady.
Comparison Table
Short sentence.
Here is a concise comparison between Next Moca ADL and the common alternative of ad-hoc or in-code agent configurations, showing why a spec yields long-term gains in clarity and governance.
Look it over.
| Feature | Next Moca ADL | Biggest Competitor (ad-hoc configs) |
|---|---:|---:|
| Format | YAML/JSON schema | Unstandardized files or in-code config |
| Tool discovery | Explicit tool contracts and endpoints | Implicit, often undocumented |
| Versioning | Spec-friendly, versioned | Varies widely |
| Safety policies | Declarative policy blocks | Scattered controls |
| Reuse | High due to standardization | Low due to coupling |
Common Mistakes to Avoid
Short sentence.
Treat ADL like a spec, not a silver bullet — people copy entire business logic into the spec or they leave policies buried in code, which defeats the purpose of clarity and auditability.
Simple point.
Don’t use ADL as an excuse to avoid writing tests; instead use the spec to generate tests — validate prompt templates, mock tool outputs, and run end-to-end checks in CI so you catch runtime drift early.
Sensible.
Also avoid over-modeling; a massive ADL file with every optional parameter defined becomes an orphan artifact quickly, because developers avoid updating it when things change.
Common trap.
A better approach is to model for the common case and add extensibility primitives for rare options; keep policy blocks explicit and tightly scoped so reviewer responsibilities are clear and human oversight is enforceable.
Works well.
Another mistake is assuming runtime adapters are trivial; you must handle auth, rate limits, retries, schema evolution, and error mapping — plan for those in your adapter design and in your ADL tool contract definitions.
Don’t forget.
Frequently Asked Questions
Short sentence.
Q1: Is ADL compatible with LangChain and AutoGen? A: Yes — the goal is to be runtime-agnostic and to make mapping to LLM wrappers and tool runners straightforward; see LangChain agents and Microsoft AutoGen for examples of runtimes that can consume structured descriptors.
Good to know.
Q2: Do I need to rewrite my agents to use ADL? A: No — you can incrementally map existing artifacts into ADL and write adapters that interpret the descriptors at runtime; start with a single agent and expand from there.
Practical answer.
Q3: How does ADL help with safety and compliance? A: By making policy rules and approval gates declarative and part of the agent descriptor, you centralize control and improve audit trails, which makes reviews and compliance verification much easier.
Helpful.
Q4: Is ADL open source? A: Yes — Next Moca released the specification to be an open standard so that tool authors, platform vendors, and engineering teams can interoperate without vendor lock-in.
Important.
Final Thought
Short sentence.
Open specs like ADL are not flashy; they’re a modest form of stewardship that treats engineering talent and time as a shared good, which preserves the dignity of work and reduces repeated toil across teams.
Amen.
When I look back at slack threads and 3 AM debugging sessions from my stints at Amazon and Zulily, the recurring root causes are poor interfaces and undocumented assumptions — ADL helps fix those problems at the source by making contracts explicit and reviewable.
Experienced view.
Use ADL to make your agents testable, auditable, and portable, and always keep human review gates for high-risk actions so policy is part of the codebase, not an afterthought.
Wise move.
Ermenildo V Castro
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "Is ADL compatible with LangChain and AutoGen?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Yes — ADL aims to be runtime-agnostic and maps to LLM wrappers and tool runners; see LangChain and Microsoft AutoGen for example runtimes."
}
},
{
"@type": "Question",
"name": "Do I need to rewrite my agents to use ADL?",
"acceptedAnswer": {
"@type": "Answer",
"text": "No — you can incrementally map existing agents to ADL and add adapters that interpret the descriptors at runtime. Start with a single agent."
}
},
{
"@type": "Question",
"name": "How does ADL help with safety and compliance?",
"acceptedAnswer": {
"@type": "Answer",
"text": "By declaring policy blocks and approval gates in the agent descriptor, ADL centralizes governance and improves auditability for compliance reviews."
}
},
{
"@type": "Question",
"name": "Is ADL open source?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Yes — Next Moca released ADL as an open specification to encourage interoperability and reduce vendor lock-in."
}
}
]
}