Agent Definition Protocol (ADP)

---

You built an agent in LangGraph. It works. Now someone asks: "Can we run this in production? Can we evaluate it in CI? Can the other team use it with AutoGen?"

Suddenly you're digging through framework internals to answer basic questions — what model does it use, what tools, how is it evaluated, how do I package it for the registry.

ADP is 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. You move the agent without rewriting glue.

ADP is a specification, not a runtime. It defines the contract; your framework implements it.

---

What it looks like

adp_version: "0.1.0"
id: "agent.acme.analytics"
conformance_class: "full"

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

flow:
  id: "agent.acme.analytics.flow"
  graph:
    nodes:
      - { id: "ingest",  kind: "input"  }
      - { id: "analyze", kind: "llm",    model_ref: "gpt4" }
      - { id: "report",  kind: "output", output_ref: "context.analyze.content" }
    edges:
      - { from: "ingest",  to: "analyze" }
      - { from: "analyze", to: "report"  }
    start_nodes: ["ingest"]
    end_nodes:   ["report"]

evaluation:
  suites:
    - id: "accuracy"
      metrics:
        - { id: "factuality", type: "llm_judge", threshold: 0.85 }

Validate it, pack it to OCI, hand it to any conformant runner — same manifest, any framework.

---

Framework support

ADP's flow graph maps directly to each framework's native model:

ADP concept	LangGraph	AutoGen	Semantic Kernel	CrewAI
flow.graph.nodes[]	StateGraph.add_node	ConversableAgent	KernelProcessStep	@listen
conditional edge	add_conditional_edges	GroupChatManager	OnEvent	@router
start_nodes[]	set_entry_point	first initiate_chat	process entry	@start
state.context[node.id]	TypedDict context field	chat_messages	step output	flow state
node.model_ref	ChatOpenAI(model=...)	llm_config	OpenAIChatCompletion	task LLM

Full mapping guides and a runnable LangGraph example: spec/framework-interop.md · examples/runners/langgraph/

---

Get started

PYTHON_BIN=python3 bash scripts/validate.sh   # validate all schemas + conformance harness

from adp_sdk.adp_model import ADP
from adp_sdk.validation import validate_adp, validate_adp_semantics

adp = ADP.from_file("examples/acme-analytics/adp/agent.yaml")
validate_adp(adp)            # schema + conformance_class check
validate_adp_semantics(adp)  # edge refs, model_ref, runtime_ref

# LangGraph round-trip — ADP → LangGraph → ADP
cd examples/runners/langgraph
pip install -r requirements.txt && pip install -e ../../../sdk/python
pytest -v

---

Where it fits

flowchart TD
    A["Authoring tools & frameworks\nLangGraph · AutoGen · CrewAI · Semantic Kernel"]
    B["ADP manifest + ADPKG\n— this spec —"]
    C["Runners · platforms · CI"]
    D["MCP · A2A · OTel · OCI"]

    A <-->|"export / import"| B
    B -->|"consumed by"| C
    B -.->|"references"| D

Loading

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

---

What's in this repo

Component	Description	Location
ADP spec	Identity, runtime, flow, evaluation, governance	spec/adp-v0.1.0.md
Execution Semantics (ESP)	Per-node state rules (D1–D7), condition expressions	spec/esp.md
Runtime-flow binding	Backend compatibility matrix, runtime_ref resolution	spec/runtime-flow-binding.md
Framework interop guide	LangGraph / AutoGen / SK / CrewAI mapping	spec/framework-interop.md
JSON Schemas	6 schemas, hosted on GitHub Pages	schemas/
SDKs	validate / pack / unpack — Python · TS · Rust · Go	sdk/
Conformance harness	7 runner scenarios, CI dry-run mode	scripts/esp-runner-harness.py
LangGraph example	ADP ↔ LangGraph round-trip pytest suite	examples/runners/langgraph/
OCI packaging	Pack agents into OCI artifacts	spec/adpkg-oci.md

---

Navigation

Spec entry point	spec/adp-v0.1.0.md
Spec index	spec/README.md
Roadmap	roadmap.md
Examples	examples/
Conformance	spec/conformance.md
Changelog	CHANGELOG.md

---

Contributing

Contributions welcome — CONTRIBUTING.md · GOVERNANCE.md · CODE_OF_CONDUCT.md