ADL

Appearance

Getting Started ​

This page walks through writing your first ADL manifest and validating it against the schema.

Prerequisites ​

Validation runs against a local clone of the schema repo. You need either:

  • Node.js 24 (matches CI), plus the validator installed in the clone:

    sh
    git clone https://github.com/inference-gateway/adl
cd adl
npm install --no-save ajv@8 ajv-cli@5 ajv-formats@3

    These are the same packages CI installs. There is no package.json on purpose - the install is one-off and local to your working tree.

  • flox - flox activate in the schema repo runs that same npm install for you.

1. Write a minimal manifest ​

Create agent.yaml:

yaml
apiVersion: adl.inference-gateway.com/v1
kind: Agent
metadata:
  name: hello-agent
  description: Smallest valid ADL manifest
  version: "0.1.0"
spec:
  capabilities:
    streaming: true
    pushNotifications: false
  server:
    port: 8080
  language:
    go:
      module: github.com/example/hello-agent
      version: "1.26"

Every field above is required by the schema. We'll layer on the optional ones later.

2. Validate it ​

Both commands below run from the root of the schema repo clone and need the validator installed there first - the npm install from Prerequisites, or flox activate. The ajv executable ships in the ajv-cli package, and -c ajv-formats has to resolve from the working tree, so neither command works on a fresh clone without it.

If you have go-task installed:

sh
task validate -- ./agent.yaml

Otherwise, run the locally installed ajv directly:

sh
npx ajv validate \
  --spec=draft7 \
  -c ajv-formats \
  -s schema/v1/schema.json \
  -d agent.yaml

A valid manifest prints agent.yaml valid. An invalid one prints the specific path, expected type, and offending value.

3. Pin the schema version ​

Once your manifest passes validation, decide which tag of the schema you want to pin against. Released schema tags are immutable - once vX.Y.Z is cut, the schema file at that tag never changes. Consumers (including adl-cli) pin to a specific tag in their Taskfile.yml or equivalent, so your manifests stay valid for the lifetime of the consumer's pin.

yaml
# Example: pinning in a Taskfile
vars:
  ADL_SCHEMA_VERSION: v0.27.1
  ADL_SCHEMA_URL: https://raw.githubusercontent.com/inference-gateway/adl/{{.ADL_SCHEMA_VERSION}}/schema/v1/schema.json

4. Generate and run a project ​

A valid manifest is the input to a consumer - a tool that turns ADL into something runnable. The reference consumer is adl-cli, which emits a complete agent project (server, tool stubs, skills, sandbox, CI, and deployment manifests) in the language you set under spec.language. The short version:

sh
# install the generator
curl -fsSL https://raw.githubusercontent.com/inference-gateway/adl-cli/main/install.sh | bash

# manifest -> project
adl generate --file agent.yaml --output ./hello-agent

# build and run
cd hello-agent && task build && task run

For the full walkthrough - what each generated file maps back to in your spec, and how to run the agent locally - continue to Generate & Run.