Agent Blueprint Protocol

Agent developers need a portable format for describing an agent's capabilities and connecting that description to a deployment. The Blueprint format records capabilities, ports, and bounds. A Deployment Manifest binds one Blueprint release to an environment. A Federation TaskEnvelope carries a task record between supported transports.

Every successful verification is non-authorizing: it reports protocol facts and never grants permission to act.

Artifacts

• Blueprint Core describes an agent's identity, input and output ports, capability requirements, bounds, and content digest.
• Deployment Manifest binds a Blueprint release to environment-specific descriptors and bounds.
• Federation TaskEnvelope records a task's identity, state, and terminal commitments for carriage in Agent2Agent (A2A) task metadata and Model Context Protocol (MCP) _meta.

This is the complete example from examples/echo-blueprint.json, formatted for reading:

{
  "blueprint_id": "example.demo/echo",
  "capability_requirements": [{"approval_trait":"none","argument_schema":{"type":"object"},"authority_trait":"none","classification_ceiling":"internal","impact_class":"ordinary","operation_family":"example.demo.read_shape","operation_kind":"read","result_schema":{"type":"object"}}],
  "ceilings": {"max_attempts":3,"max_concurrency":2,"max_cost":{"amount":1000,"currency":"USD"},"max_depth":8,"max_descendants":64,"max_elapsed_ms":60000,"max_fan_out":4,"max_tokens":100000},
  "classification_ceiling": "internal",
  "content_digest": "sha-256:b1Aw4cU5AbV9k8bdbZkRCsySDHGpTAwB-aQm57Wh7B8",
  "effect_intents": [{"impact_class":"ordinary","logical_operation":"record_summary","operation_kind":"mutation"}],
  "evaluation_assertions": [{"kind":"output_schema","port":"result","schema":{"type":"object"}}],
  "extensions": {"critical":{},"optional":{}},
  "input_ports": [{"classification_ceiling":"internal","name":"request","required":true,"schema":{"type":"object"}}],
  "output_contract": {"classification_ceiling":"internal","port":"result"},
  "output_ports": [{"classification_ceiling":"internal","name":"result","required":true,"schema":{"type":"object"}}],
  "producer": {"created_at":"2026-08-20T00:00:00Z","identity":"example.demo","toolchain":"example.demo.toolchain"},
  "protocol_revision": 1,
  "release_number": 1,
  "required_core_fields": [],
  "triggers": ["manual"]
}

Verification decodes bounded JSON, negotiates protocol support, binds related artifacts, reconciles host inputs, and returns evidence.

Which package?

Language	Package	Install
Elixir	Hex agent_blueprint_protocol	{:agent_blueprint_protocol, "~> 1.0.0"}
TypeScript	npm @agent-blueprint-protocol/verifier	npm install @agent-blueprint-protocol/verifier

The Elixir package requires Elixir 1.19 or newer on Erlang/OTP 27, 28, or 29. The npm package requires Node.js 24 or newer. Both implement protocol revision 1; the stability policy lists the tested combinations.

From a Mix project that depends on the package, read its shipped example:

dependency_root = Mix.Project.deps_paths()[:agent_blueprint_protocol] || File.cwd!()
example_path = Path.join(dependency_root, "examples/echo-blueprint.json")
bytes = File.read!(example_path)
{:ok, blueprint} = AgentBlueprintProtocol.decode_blueprint(bytes)
AgentBlueprintProtocol.canonical_bytes(blueprint) == {:ok, bytes} # => true

First TypeScript verification, from a checkout containing the example:

import { readFileSync } from "node:fs";
import { decodeBlueprint } from "@agent-blueprint-protocol/verifier";

const result = decodeBlueprint(readFileSync("examples/echo-blueprint.json"));
console.log(result.ok ? "valid" : result.error.code); // valid

npm view @agent-blueprint-protocol/verifier dist-tags lists the published version for each npm tag.

The conformance corpus contains 626 cases. It is a collection of inputs and expected results for implementations; see the glossary.

Documentation

• HexDocs
• Quickstart
• TypeScript guide
• Conformance guide
• Protocol specification
• Stability policy
• Livebook walkthroughs: producing artifacts, host import, extensions and federation, and conformance and attacks.

Status

The 1.0 line follows its stability promise: documented APIs remain stable within the major version, and deprecations follow the stability policy.

Contributing

See CONTRIBUTING.md for development setup and contribution guidance.