The OpenAPI
for AI Agents

One YAML manifest declares your agent's runtime, flow graph, evaluation criteria, and packaging metadata. Frameworks and runners consume it. Declare once, run anywhere.

Get started → Read the spec Framework or platform maintainer? Add ADP support →
agent.yaml 
adp_version: "0.3.0"
id:          "agent.acme.analytics"
conformance_class: "full"

runtime:
  execution:
    - { id: "py", backend: "python", entrypoint: "app:main" }
  models:
    - { id: "gpt4", provider: "openai", model: "gpt-4o" }

evaluation:
  suites:
    - id: "accuracy"
      metrics:
        - { type: "llm_judge", threshold: 0.85 }
What's included v0.3.0 · Stable spec · semver-versioned releases
4 SDKs Python, TypeScript, Rust, Go
8 conformance scenarios CI-ready out of the box
6 JSON Schemas Hosted on GitHub Pages, validate anywhere
4 framework guides LangGraph, AutoGen, CrewAI, Semantic Kernel
The problem

The fragmented
agent ecosystem

You built an agent in LangGraph. It works. Now someone asks: "Can we run this in production? Can the other team use it with AutoGen?" Suddenly you're digging through framework internals.

Framework lock-in

StateGraph, ConversableAgent, KernelProcessStep — every framework has its own model. Moving means rewriting all your glue code.

No portable packaging

You can't hand an agent to another team without handing them your entire runtime stack, environment config, and tribal knowledge.

Bespoke CI evaluation

Testing an agent means writing a custom harness every time. Every project reinvents the same evaluation wheel.

Observability is an afterthought

Telemetry, guardrails, and hooks aren't declared in the agent — they're duct-taped after the fact, inconsistently.

The solution

The agent harness — four layers

ADP provides portable, framework-neutral scaffolding that wraps an agent for execution, testing, and observation. Declare the harness once; your framework implements it.

Execution
runtime · pipeline · streaming

How the agent runs, processes I/O, and streams. Backend-agnostic: Python, Node, Rust, Go. Multi-backend supported.

Observation
telemetry · hooks

OTel gen_ai.* required attributes, lifecycle hooks, and structured event emission — observable execution by design, not retrofit.

Safety
guardrails · governance

Input/output filters, policy refs, mode declarations, and compliance fields (GDPR, HIPAA, EU-AI-Act). What is permitted — declared, not hardcoded.

Testing
evaluation · x_testing

LLM-judge metrics, threshold-based suites, and CI-ready conformance scenarios. Test the agent contract, not the framework internals.

One manifest

Declare once,
run anywhere

Validate it. Pack it to OCI. Hand it to any conformant runner. Same manifest — any framework. ADP is a specification, not a runtime.

  • JSON Schema validation — 6 schemas hosted on GitHub Pages
  • OCI packaging via ADPKG — pack and unpack agents as artifacts
  • Composition: extends, import, overrides across all 4 SDKs
  • 8-scenario conformance harness — CI dry-run mode included
  • GDPR · HIPAA · SOC2 · EU-AI-Act · FedRAMP compliance fields
  • Framework mapping guides: LangGraph, AutoGen, CrewAI, Semantic Kernel
agent.yaml — flow + safety 
flow:
  graph:
    nodes:
      - { id: "ingest",  kind: "input"  }
      - { id: "analyze", kind: "llm",   model_ref: "gpt4" }
      - { id: "report",  kind: "output" }
    edges:
      - { from: "ingest",  to: "analyze" }
      - { from: "analyze", to: "report"  }
    start_nodes: ["ingest"]

guardrails:
  input:
    - { provider: "openai", policy_ref: "safe-msg" }
  output:
    - { provider: "custom", mode: "block" }

governance:
  compliance: ["GDPR", "EU-AI-Act"]
Where it fits

The glue layer between
authoring and execution

ADP references existing protocols — it doesn't replace them. MCP handles tool transport. A2A handles agent-to-agent comms. OCI handles packaging. ADP is the manifest that wires them together.

ADP is the manifest layer — not another runtime or framework.

Governance & Auditability

Built for the
regulated era of AI

AI regulation is arriving — ADP makes compliance structural before it becomes mandatory.

AI regulation is arriving fast. The EU AI Act mandates automatic logging, technical documentation, and human oversight for high-risk systems — effective 2026. ADP makes compliance structural, not bolted on.

EU AI Act
Art. 11 · 12 · 14 · 2026

Technical documentation, automatic input/output logging, and human oversight checkpoints — mandatory for high-risk AI systems.

GDPR
Art. 5 · 30 · Records of Processing

Data residency declarations, purpose limitation, and records of processing activities — declared directly in the ADP manifest.

HIPAA
§164.312 · Audit Controls

PHI handling mode (de-identify · audit-log · block), audit logging flag, and access controls per agent.

NIST AI RMF
Govern · Measure · Manage

Structured governance fields, evaluation suites, and telemetry satisfy the Govern/Measure/Manage functions of the NIST AI Risk Management Framework.

EU AI Act Art. 12 → telemetry.required_attributes — OTel spans per run
EU AI Act Art. 11 → ADP manifest itself — is the technical doc
EU AI Act Art. 14 → hooks (pre/post) — human oversight gates
GDPR Art. 30 → governance.compliance[gdpr] — data residency fields
HIPAA §164.312 → compliance[hipaa].phi_handling — PHI de-identify/block
agent.yaml — governance & audit 
# Compliance posture — normative inputs to CI
governance:
  compliance:
    - standard: "eu-ai-act"
      risk_category: "limited"  # minimal|limited|high
    - standard: "gdpr"
      data_residency: ["eu-west-1", "eu-central-1"]
    - standard: "hipaa"
      phi_handling: "de-identify"
      audit_logging: true
    - standard: "soc2"
      audit_logging: true

# Audit trail — OTel gen_ai.* semantic conventions
telemetry:
  endpoint: "https://otel.acme.com/v1"
  required_attributes:
    - "gen_ai.system"
    - "gen_ai.request.model"
    - "gen_ai.usage.input_tokens"
    - "gen_ai.usage.output_tokens"

# Human oversight hooks (EU AI Act Art. 14)
hooks:
  - event: "pre_output"
    action: "human_review_gate"
    mode: "block"  # halt until approved

# Notary v2 signing + SPDX SBOM (provenance)
x_adpkg:
  sign: true
  sbom: "spdx-json"
Framework support

Works where you already build

ADP's flow graph maps directly to each framework's native model. No re-implementation — just a mapping guide and a round-trip test suite.

LangGraph
StateGraph · add_node
add_conditional_edges
AutoGen
ConversableAgent
GroupChatManager
CrewAI
@listen · @router
@start · flow state
Semantic Kernel
KernelProcessStep
OnEvent · step output
SDKs

Validate, pack, and unpack
in your language

Four SDKs — same API surface. validate · pack · unpack · resolve_adp. 100% test coverage across all four.

Python TypeScript Rust Go
Get started

Up and running in minutes

Install the Python SDK

pip install adp-sdk

Validate your manifest

PYTHON_BIN=python3 bash scripts/validate.sh

Run the LangGraph example

cd examples/runners/langgraph && pytest -v

Read the spec

open spec/adp-v0.3.0.md

Ready to standardize your agents?

ADP is open, specification-driven, and framework-neutral.
Standardization in progress. Contributions welcome.

View on GitHub → How to contribute