ADL: AI 에이전트 정의를 위한 선언적 언어

AI 에이전트, 그들의 기능(capabilities), 그리고 기술(skills)을 정의하기 위한 선언적 언어입니다. ADL은 'AI 에이전트를 위한 OpenAPI'라고 생각할 수 있습니다. 이는 플랫폼 전반에 걸쳐 일관된 에이전트 정의, 문서화, 코드 생성을 가능하게 하는 표준화된 명세입니다.

📖 전체 문서: adl.inference-gateway.com/v1

• ADL이란 무엇인가?
• 문서화
• 레이아웃
• 예시 매니페스트
• 소비자(Consumers)
• 버전 관리
• 왜 ADL을 사용해야 하는가?
• 기여하기
• 라이선스

ADL에 대한 광범위하고 탐색 가능한 문서에는 개념, 필드별 스키마 참조, 복사하여 붙여넣을 수 있는 매니페스트 예시 등이 포함되어 있으며, adl.inference-gateway.com/v1에서 확인할 수 있습니다.
사이트 소스는 docs/ 아래의 VitePress 프로젝트입니다.

.

이 README는 의도적으로 간결하게 유지됩니다. 문서 사이트가 장문의 보조 자료이며, 사용자의 프로젝트에서 링크를 걸기에 적절한 위치이기 때문입니다.

ADL(Agent Definition Language)은 AI 에이전트를 위한 공급업체 중립적이고 선언적인 명세입니다. OpenAPI가 REST 서비스를 설명하는 표준 방식을 제공하듯이, ADL은 에이전트—그들의 메타데이터, 기능, 도구(tools), 기술, 그들을 구현한 AI 제공자, 의존하는 서비스, 그리고 배포되는 런타임—를 설명하는 표준 방식을 제공합니다.

이 리포지토리는 **ADL 스키마의 진실 공급원(source of truth)**입니다. schema/v1/schema.json에 있는 JSON Schema 문서는 정식 명세입니다. ADL 매니페스트를 생성하거나 소비하는 도구들(예: adl-cli)은 이 스키마의 태그가 지정된 버전에 고정됩니다.

ADL은 에이전트가 행동할 수 있는 두 가지 방식을 구별합니다:

도구(Tools)(spec.tools[])는 함수 호출 진입점입니다. 각 도구는 입력에 대한 JSON Schema를 가지고 있으며 대상 언어로 코드로 생성됩니다. 에이전트가 결정론적 작업(데이터베이스 쿼리, 이메일 전송, API 호출)을 실행해야 할 때 도구를 사용합니다.기술(Skills)(spec.skills[])

)
은 에이전트가 런타임에 발견하는 마크다운 플레이북입니다. 각 스킬의 메타데이터(이름 및 설명)만 시작 시 시스템 프롬프트에 포함되며, 플레이북 본문은 모델이 해당 스킬을 호출할 때 지연 로드됩니다. 스킬은 스킬 레지스트리에서 가져오거나 bare: true로 빈 상태로 구성될 수 있습니다.

스킬을 사용하는 것은 에이전트에게 자연어로 워크플로우, 정책 또는 응답 패턴을 가르치고 싶을 때입니다.

schema/
└── v1/
└── schema.json # apiVersion: adl.inference-gateway.com/v1용 JSON Schema Draft-07

ADL의 새로운 주요 버전은 schema/v2/ 아래에 위치합니다.

, 등. 주요 버전 내에서는 하위 호환성 추가만 허용됩니다.

apiVersion: adl.inference-gateway.com/v1
kind: Agent
metadata:
...

metadata는 필수이며 세 가지 필수 필드(name, description, version)와, 하위 카탈로그나 레지스트리에서 제공되는 것이 아니라 매니페스트와 함께 전달되는 세 가지 선택적 필드를 포함합니다:

metadata.author

• { name (필수), email?, url? }
  . 에이전트를 게시하는 사람의 출처 및 연락처입니다.
  .metadata.license
• 에이전트가 배포되는 SPDX 식별자(또는 Proprietary)
  . Skill.license와 동일한 승인된 세트를 사용합니다.
  .metadata.tags
• string[]
  . 에이전트 수준의 발견 가능 태그입니다 (예: calendar, automation). 소비자들은 인덱싱 시 이러한 태그를 도구 및 스킬 수준의 태그와 병합할 수 있습니다.

세 필드 모두 선택적이며 추가적인 성격이 있습니다. 이들을 생략한 매니페스트도 유효합니다.

metadata:
name: customer-support
description: 고객 문의 처리를 위한 AI 에이전트
...

전체 spec.agent 블록은 선택 사항입니다. A2A(Agent-to-Agent) 에이전트는 LLM(Large Language Model) 없이도 배포될 수 있으며, 이 경우 단순히 agent를 생략하면 됩니다. 모델 백업 에이전트를 구성하는 경우에는 spec.agent.mcp.servers[]가 런타임에 MCP(Model Context Protocol) 서버에 연결할 수 있게 하여, 모델이 로컬에서 생성된 spec.tools와 함께 외부 기능을 발견하고 호출할 수 있도록 합니다.

MCP 설정은 spec.agent 아래에 위치합니다.

오직 에이전트를 구동하는 모델(model)이 존재할 때만 의미가 있기 때문에 최상위 수준에서라기보다는 그에 가깝습니다.

spec:
agent:
provider: openai
...

각 항목은 name (에이전트 내 고유해야 함)과 transport를 필요로 합니다:

stdio는 로컬 서브프로세스를 실행하고 stdin/stdout을 통해 통신합니다. 이는 command, args, 그리고 env로 구성할 수 있습니다.
.http와 .sse는 원격 엔드포인트에 연결합니다. 이들은 url과 선택적 headers (예: Authorization 헤더)로 구성합니다.

나머지 스키마를 반영하여, 연결 필드는 유연하게 유지됩니다. 즉, 스키마가 트랜스포트에 따른 특정 필드 조합을 강제하지 않기 때문에, 소비자(consumer)(예: adl-cli)가 이를 얼마나 엄격하게 해석할지, 그리고 어떤 환경 플레이스홀더를 해결할지는 결정합니다. 향후 마이너 버전에서 새로운 트랜스포트가 추가될 수 있으므로, 독자들은 알 수 없는 transport 값을 허용해야 합니다.

스키마가 받아들이는 범위는 소비자가 연결하는 범위보다 넓습니다. 오늘날 adl-cli는 오직 http 항목에서만 A2A_MCP_SERVERS를 가져옵니다. 위의 stdio 서버는 유효성 검사를 거친 후 경고와 함께 버려지므로 서브프로세스는 절대 실행되지 않으며, Go 에이전트에 대한 MCP 클라이언트만 생성합니다. MCP 서버 연결에 대해서는 [Connecting to MCP Servers]를 참조하십시오.

${GITHUB_MCP_TOKEN}과 같은 플레이스홀더는 스키마가 아니라 배포/실행 시점에 소비자에 의해 해결됩니다. 또한, LLM 제공업체 API 키도 매니페스트에 저장되지 않으며, 생성된 프로젝트에서 런타임 환경 변수로 공급됩니다. 전체 규칙은 [Secrets & interpolation]을 참조하십시오.

mcp.servers는 연결할 어떤 서버를 선언하는 것이고, 주변의 spec.agent.mcp 필드는 클라이언트의 런타임 구성(enable 토글 및 refresh/timeout/retry 노브)입니다. MCP 클라이언트는 기본적으로 비활성화됩니다. 즉, mcp가 생략되거나 enabled: false인 경우, servers에 서버 목록이 지정되어 있더라도 MCP 클라이언트는 생성되지 않습니다. 활성화된 경우, 각 필드는 일치하는 A2A_MCP_* 환경 변수의 기본값이 되며, 이는 런타임에 이를 재정의합니다:

spec:
agent:
mcp:
...

spec.skills[]의 각 항목은 선택적인 license 문자열을 허용합니다. 이 필드는 해당 스킬이 배포되는 라이선스를 담고 있으며, 스키마가 수락하는 SPDX 식별자 세트 중 하나를 따르거나 비공개(closed-source) 스킬의 경우 Proprietary여야 합니다.

수락된 값:

이 값은 스킬의 SKILL.md 프런트매터(frontmatter)에 있는 license 필드와 동일하며, 따라서 라이선스는 플레이북이 사용되는 장소에 관계없이 함께 이동합니다. 별도의 LICENSE 파일을 SKILL.md 옆에 배포하는 것은 선택 사항이며 스키마가 강제하지는 않습니다. 소비자는 (consumers) 배포 채널에서 기대하는 경우 스킬의 소스 디렉터리에 이를 포함할 수 있습니다.

추가 식별자는 향후 마이너 버전의 스키마에서 추가될 수 있으며, SPDX 표현식(예: MIT OR Apache-2.0)은 현재 허용되지 않습니다.

spec.language.<lang> 아래의 모든 언어 설정은 선택적인 vendor 블록을 허용합니다. 이 블록을 사용하면 생성기(generator)가 기본값 외에 프로젝트로 가져와야 할 추가 패키지를 매니페스트에서 선언할 수 있습니다. 이는 테스트 라이브러리, 린터(linter), 목업 생성기(mock generators) 또는 생성된 스캐폴딩이 기본적으로 제공하지 않는 모든 런타임 패키지에 유용합니다.

vendor.deps - 런타임/프로덕션 의존성(runtime/production dependencies).
vendor.devdeps - 개발 전용 및 테스트 전용 의존성(development- and test-only dependencies).

각 항목은 대상 언어의 네이티브 패키지 및 버전 구문을 사용하는 <패키지>@<버전> 형태의 문자열입니다. 소비자들(예: adl-cli)은 이를 해당 언어의 락파일/매니페스트 형식(go.mod 등)으로 변환합니다.

, package.json`

, Cargo.toml

, ...).

spec:
language:
go:
...

TypeScript와 Rust는 동일한 vendor 형태를 허용합니다. 각 언어별 필드는 spec.language 참조 섹션을 참고하세요.

두 필드 모두 선택 사항이며 기본값은 비어 있습니다. 스키마는 <package>@<version> 형태만 검증하며, 패키지나 버전 구문 자체를 추가로 제한하지 않습니다. 따라서 각 언어의 네이티브 규칙(Go 모듈 경로, npm 범위 지정 패키지, semver 범위 등)을 모두 수용합니다.

spec.development는 에이전트 프로젝트의 로컬 개발자 경험과 관련된 모든 것을 그룹화합니다:

• spec.development.sandbox: 재현 가능한 개발 환경(flox, devcontainer, 또는 dockerCompose)을 선택합니다. 각 항목은 독립적으로 활성화/비활성화할 수 있으며, adl-cli와 같은 소비자들은 이 플래그들을 사용하여 해당 환경 파일을 스캐폴딩(scaffold)하는 데 사용합니다.
• spec.development.ai: AI 어시스턴트 문서(CLAUDE.md, AGENTS.md) 생성을 구성하고 샌드박스 내에 코딩 에이전트 오케스트레이터 프로비저닝을 담당합니다. 이 오케스트레이터들은 spec.development.ai.orchestrators 아래에 위치하며, 지원되는 모든 오케스트레이터는 자체 하위 섹션을 통해 독립적으로 활성화/비활성화할 수 있으며, 기본적으로 모든 오케스트레이터는 비활성화되어 있습니다:
  • 필드 오케스트레이터 orchestrators.claudecode.enabled
  • Anthropic Claude Code orchestrators.codex.enabled
  • OpenAI Codex orchestrators.gemini.enabled
  • Google Gemini orchestrators.opencode.enabled
  • OpenCode orchestrators.infer.enabled
  • Inference Gateway infer

프로젝트가 여러 개의 구성을 배포하려는 경우, 여러 오케스트레이터를 한 번에 활성화할 수 있습니다.

claudecode와 infer 오케스트레이터는 추가적으로 appIdSecret과 appPrivateKeySecret을 허용합니다. 이는 생성된 워크플로우가 사용하는 GitHub App 클라이언트 ID 및 개인 키를 보관하는 리포지토리 시크릿의 이름입니다. 기본값은 각각 CLAUDE_APP_ID/CLAUDE_APP_PRIVATE_KEY와 INFER_APP_ID/INFER_APP_PRIVATE_KEY입니다.

각각; 조직에서 다른 비밀 이름(secret names)을 사용하는 경우 설정하십시오. -
spec.development.deps

개발 샌드박스 자체에 설치할 추가 패키지들을 선언합니다 (flox, devcontainer, dockerCompose). 이는 생성기가 기본적으로 가져오는 것에 더해지는 것입니다. 프로젝트의 언어와 연결되지 않은 교차 영역 도구(cross-cutting tools)에 사용하십시오. 예: deno가 필요하면서도 Go 서비스이거나, 빠른 스크립팅을 위해 kubectl이 개발 셸(dev shell)에서 사용되기를 원하는 TypeScript 에이전트.

각 항목은 spec.language.<lang>.vendor.deps와 동일한 <패키지>@<버전> 형태를 따릅니다.

:spec: development: sandbox: flox: enabled: true deps: - [email protected] - [email protected] - [email protected]

이 스키마는 <패키지>@<버전> 형태만 검증합니다. 소비자(예: adl-cli)가 샌드박스의 네이티브 패키지 소스에 따라 각 항목을 해결할 책임이 있습니다 - flox의 경우 Nixpkgs, devcontainer의 경우 apt/apk 패키지 또는 devcontainer 기능, dockerCompose의 경우 이미지 레이어입니다. 이 필드는 선택 사항이며 기본값은 비어 있습니다.

spec.telemetry

생성된 에이전트에 대한 OpenTelemetry 계측(instrumentation)을 구성합니다. enabled는 마스터 스위치입니다:

true일 경우, 소비자(예: adl-cli)가 프로젝트에 OpenTelemetry 종속성을 가져오고, 내장 도구 호출에 스팬(spans)으로 계측하여 각 호출이 얼마나 오래 걸리는지 확인할 수 있게 하며, ADK의 텔레메트리/메트릭 서버를 켭니다.

가장 간단한 매니페스트는 여전히 단일 스위치입니다:

spec:
  telemetry:
    enabled: true

선택적으로, traces와 metrics 블록은 OpenTelemetry SDK의 선언적 구성 모델을 따르는 **신호별(per-signal) 내보내기(exporter)**를 선택합니다. 이 내보내기는 각 신호 아래에 중첩되어 있으며, exporter 아래 단일 키가 이를 지정합니다 (otlp는 푸시용, prometheus는 풀용). 따라서 별도의 내보내기 열거형(enum)이 없습니다:

spec:
  telemetry:
    enabled: true
... 

모든 필드는 표준 OTEL_* 환경 변수와 1:1로 매핑되며, 이는 adl-cli가 A2A_ 접두사로 작성합니다.

접두사(prefix)를 사용해야 합니다. ADK는 해당 접두사 아래의 전체 구성을 읽기 때문입니다. 신호(signal) 또는 그 exporter 블록을 생략하면 비활성화됩니다 - A2A_OTEL_TRACES_EXPORTER=none

/ A2A_OTEL_METRICS_EXPORTER=none.

. traces는 otlp를 수용하고, ; metrics는 otlp 또는 prometheus를 수용합니다. Go는 항상 OTLP를 공유된 A2A_OTEL_EXPORTER_OTLP_ENDPOINT / _PROTOCOL 쌍으로 병합하는 반면, TypeScript는 두 신호가 모두 일치하지 않는 한 개별 신호 이름을 사용합니다. prometheus 호스트/포트 변수는 Go 전용이며 Rust 프로젝트에는 아직 원격 측정(telemetry) 변수가 없습니다.

spec.telemetry는 선택 사항이며, 원격 측정은 기본적으로 비활성화됩니다 - 이 블록을 생략하거나 enabled: false로 설정하여 비활성 상태를 유지할 수 있습니다. 헤더, 자격 증명(credentials), 샘플링은 의도적으로 매니페스트에서 제외되며 런타임에 환경을 통해 해결됩니다. enabled을 넘어서는 모든 것은 추가적(additive)이므로, 기존의 telemetry: { enabled: true } 매니페스트는 유효하게 유지됩니다. spec.telemetry를 참조하십시오.