ADL v1
adl.inference-gateway.com/v1 is the current stable major version of the Agent Definition Language. A manifest opts in by setting:
apiVersion: adl.inference-gateway.com/v1
kind: AgentThe schema is JSON Schema Draft-07 and lives in the repository at schema/v1/schema.json. Its $id is https://adl.inference-gateway.com/schemas/agent/v1.
What's in v1
| Section | Purpose |
|---|---|
metadata | Name, description, version, author, license, tags |
spec.capabilities | Streaming, push notifications, extended agent card |
spec.card | Agent card surfaced to clients |
spec.agent | Provider, model, system prompt |
spec.config | Runtime configuration knobs |
spec.services | External services the agent talks to |
spec.tools | Function-call entrypoints (deterministic operations) |
spec.skills | Markdown playbooks discoverable at runtime (metadata at startup, body lazy-loaded) |
spec.server | HTTP server settings |
spec.language | Target language (Go, Rust, TypeScript) and deps |
spec.artifacts | Files emitted alongside the agent |
spec.hooks | Lifecycle hooks |
spec.scm | Source-control metadata |
spec.development | Sandbox (flox / devcontainer / dockerCompose) and AI tooling |
spec.deployment | Kubernetes / Cloud Run / Vercel / Cloudflare deployment targets |
spec.documentation | Documentation pages the generated project owns and ships |
spec.examples | Curated examples rendered into the generated README.md |
spec.acronyms | Acronyms the generator respects when producing identifiers |
spec.telemetry | OpenTelemetry traces and metrics instrumentation |
See the full field-by-field Schema Reference.
Pinning v1 in downstream tools
Pin to a specific repository tag (vX.Y.Z, cut by semantic-release and currently on the 0.x line) rather than tracking main. Tag numbers are independent of the v1 in apiVersion - the v1 lives in the URL path, not in the tag. The schema file at any released tag is immutable, so a pin is a stable contract.
vars:
ADL_SCHEMA_VERSION: v0.27.1
ADL_SCHEMA_URL: https://raw.githubusercontent.com/inference-gateway/adl/{{.ADL_SCHEMA_VERSION}}/schema/v1/schema.jsonNew optional fields land inside v1 without changing the apiVersion; breaking changes wait for v2. See Versioning for the additive contract and the rules that govern what can change inside a major version.