Generate & Run

By the end of Getting Started you have a valid, version-pinned agent.yaml. This page takes you the rest of the way: install the reference generator, turn the manifest into a project, and run the agent locally.

ADL itself ships nothing but the schema - turning a manifest into running code is the job of a consumer. The reference consumer is adl-cli. This page shows the happy path; the CLI's own repo is the source of truth for every flag and stays current as the tool evolves.

1. Install adl-cli

The quickest path is the install script, which drops an adl binary on your PATH:

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

Prefer a different route? Any of these also work:

# Go toolchain - installs a binary named adl-cli
go install github.com/inference-gateway/adl-cli@latest

# Nix - run without installing
nix run github:inference-gateway/adl-cli

The go install route names the binary after the module, so you get adl-cli, not adl - either call it as adl-cli or rename it. The install script and nix run both give you adl, which is what the commands below assume.

Just as you pinned the schema to a tag, pin the generator: production setups should install a specific adl-cli release rather than tracking main.

2. Generate from your manifest

Point adl generate at the manifest and pick an output directory:

adl generate --file agent.yaml --output ./hello-agent

Generation is non-destructive. On a re-run the CLI honours .adl-ignore (which it writes into the project) so your edited files are left alone; pass --overwrite to force regeneration of everything else.

A few flags layer on optional artifacts - they map directly to the spec blocks below:

Flag	Adds
--ci	GitHub Actions CI workflow (or set spec.scm.ci: true).
--cd	CD pipeline + semantic-release (or spec.scm.cd: true).
--deployment kubernetes	k8s/deployment.yaml (or set spec.deployment).
--deployment cloudrun	A Cloud Run deploy task (or set spec.deployment).
--deployment vercel	A Vercel project + build config (or set spec.deployment).
--deployment cloudflare	A Cloudflare Workers wrangler config - TypeScript only.

3. What you get

The generator emits only what your spec asks for. Each generated piece traces back to a block in the manifest:

spec.* block	What the generator emits
metadata + capabilities + card	.well-known/agent-card.json - the A2A discovery + capabilities manifest.
language.<lang>	Project skeleton (go.mod/Cargo.toml, main.*), Dockerfile, Taskfile.yml.
server	HTTP server wiring (listen port, debug) in the entry point.
agent	LLM provider/model wiring. Omitted entirely for a no-LLM agent.
tools[]	One stub per tool - tools/<id>.go (Go), src/tools/<id>.ts (TypeScript), src/tools/<id>.rs (Rust, only when spec.agent is set) - each with a TODO for you to implement.
skills[]	One directory per skill under .agents/skills/<id>/ (SKILL.md + assets), plus a .claude/skills symlink pointing at it. Listed on the card.
services	Typed dependency-injection interfaces and factory functions.
config	Environment-variable mapping in the always-present config/ package (Go) or src/config.ts (TypeScript).
development.sandbox	.flox/ and/or .devcontainer/ for a reproducible dev shell - dockerCompose.enabled also emits docker-compose.yaml and .env.example.
development.ai.orchestrators	CLAUDE.md / GEMINI.md / AGENTS.md for the enabled coding agents.
scm.ci / scm.cd	.github/workflows/ci.yml, cd.yml, and .releaserc.yaml.
deployment	k8s/deployment.yaml (Kubernetes), a Cloud Run deploy task, a Vercel project + build config, or - TypeScript only - a wrangler.toml plus src/worker.ts for Cloudflare Workers.

Optional blocks you leave out add nothing, but every project gets a baseline skeleton regardless. The minimal manifest from Getting Started - no tools, skills, services, config, or deployment - still yields a complete, runnable Go project:

hello-agent/
├── main.go                     # server wired from spec.server + spec.language
├── go.mod
├── config/
│   └── config.go               # always generated - spec.config adds your fields
├── internal/
│   └── logger/logger.go
├── Dockerfile
├── Taskfile.yml                # build / test / lint / run
├── .well-known/
│   └── agent-card.json         # from metadata + spec.capabilities
├── README.md
├── CONFIGURATIONS.md
├── LICENSE
└── .adl-ignore                 # plus .gitignore, .dockerignore, .editorconfig

Layer on spec.tools, spec.skills, spec.development, or spec.deployment and the corresponding tools/, .agents/skills/, .flox/, or k8s/ directories appear alongside it.

4. Run it locally

The generated Taskfile.yml is the entry point. Build, then run:

cd hello-agent
task build
task run

The server listens on the port from spec.server.port (8080 in the Getting Started manifest). Confirm it is up by fetching the agent card:

curl http://localhost:8080/.well-known/agent-card.json

If your manifest declared spec.tools, the stubs under tools/ return placeholder data until you replace each TODO with real logic - the project builds and runs before you write a line of business logic, so you can see the agent answer first and fill in behaviour incrementally.

Where to go deeper

This page is the happy path. For everything else - the interactive adl init wizard, the full flag matrix, sandbox and CI/CD details, and per-language options - see the adl-cli repository.

• Tools vs Skills - decide what belongs in tools/ (the stubs you implement) versus .agents/skills/ (the playbooks you write).
• Examples - manifests for richer shapes; generate any of them with the same two commands.