Getting Started

Start with an account-free evaluation: inspect one Package in the interactive demo, validate real fixtures in the browser-local Protocol Playground, then ask the company Agent to prepare through Install Supply-Y In Your Agent. No API key, repository access or customer data is required for those steps, and they do not enable production traffic.

This detailed guide explains the shortest path from an existing company Agent to one verified Supply-Y exchange. Supply-Y Protocol 1.0 is the stable interoperability contract: its contracts and implementation evidence are available from the public Agent Bundle without repository access. Hosted credentials and production SLAs are separate implementation concerns and are not yet generally available.

For machine onboarding, copy the one-message installer from Install Supply-Y In Your Agent into the company Agent. That instruction starts at one stable URL, /.well-known/supply-y, and discovers the current contracts, Skills, publisher status and conformance evidence from there.

1. Pin Protocol 1.0

Version text is not enough for a reproducible implementation. Read the Protocol 1.0 Release, fetch its machine Manifest from /protocol/1.0/manifest.json, verify the exact Manifest bytes against the digest published in discovery, then verify every selected artifact digest before use. For one-fetch Agent onboarding, use the Manifest-pinned Protocol Bundle, validate it and verify all 55 decoded artifacts. Store the verified Manifest URL and digest in the customer-local Connection Profile. This prevents an Agent from silently mixing contracts from different releases.

Then fetch the discovery-pinned Agent Conformance Profile 1.0. It gives every implementation language the same nine checks, names who must execute them and fixes the exact result IDs that the customer Agent must report. Reference repository results can help diagnose an implementation, but they cannot certify that customer's Agent.

2. Choose an integration path

Your environment	Recommended path	What stays the same
Your Agent runs any supported language	Use the public protocol_contract profile and Protocol Bundle	No GitHub account, Node runtime or Supply-Y SDK is forced into your environment
Your Agent runs TypeScript or JavaScript and you have authorized source access	Optionally use typescript_sdk plus the same signed Skills	Your Agent, data access and private keys remain under your control
You do not operate an Agent	Use a customer-isolated Jenae deployment with the same Skills	The exchanged Package contract is identical
Both parties already use Catena-X EDC	Use Catena-X transport mode	Supply-Y objects, thread semantics and audit references remain identical

No Supply-Y Gateway needs to be installed inside the customer network. The Agent makes outbound HTTPS calls and connects to ERP, MES, QMS, PLM or approved data products through customer-controlled connectors.

3. Pick one business loop

Start with one narrow scenario and two companies. Material risk is the recommended first loop because it demonstrates the full protocol without requiring a large shared data model.

The sender shares:

• the affected material and part family;
• a bounded risk range and time window;
• confidence and evidence references;
• the action requested from the recipient;
• fields deliberately not disclosed.

The sender does not share raw ERP rows, exact inventory, customer names, contract prices or allocation formulas.

4. Produce the Package locally

The scenario Skill transforms approved local facts into a small network Package. The Package below is abbreviated; the complete executable example is available in the Reference section.

{
  "id": "pkg_material_constraint_001",
  "object_type": "reasoning_package",
  "protocol_version": "supply-y/1.0",
  "thread_id": "thread_material_constraint_01",
  "package_type": "material_constraint_reasoning",
  "facts": [
    {
      "statement": "Material family availability is constrained",
      "value": { "min": 20, "max": 30, "unit": "percent_constraint" },
      "evidence_refs": ["ev_supplier_signal_001"],
      "sensitivity": "confidential"
    }
  ],
  "confidence": { "score": 0.78, "basis": "multiple supplier signals" },
  "intent": { "recipient_request": "separate critical and non-critical demand" },
  "boundaries": {
    "not_disclosed": ["customer names", "contract prices", "exact capacity"],
    "retention_days": 30,
    "forwarding_allowed": false
  }
}

5. Validate before exchange

The sending implementation must validate the object against the JSON Schema and the selected Skill rules before encryption. A valid schema proves that the object is structurally interoperable; it does not prove that the business statement is true.

An external Agent runs the valid and invalid fixtures embedded in the Protocol Bundle through its own implementation. With authorized repository access, the reference suite can also be run with:

npm run validate:protocol

The expected result is checked=24 passed_expectation=24 failed_expectation=0.

This reference command uses a standard JSON Schema Draft 2020-12 validator and the Supply-Y domain conformance profile. A customer does not need repository access to reproduce the same outcomes from the Bundle in its own stack.

For a TypeScript customer implementation, call validateProtocolObject from the TypeScript SDK. Other implementations validate with a Draft 2020-12 JSON Schema library and reproduce the published domain cases and cryptographic vectors in their existing runtime. The browser-local Protocol Playground remains useful while exploring fixtures, but it is not a production integration dependency.

6. Encrypt, sign and send

The sender encrypts the Package payload with a one-time data key, wraps that key for both sender and recipient, signs the encrypted payload plus routing metadata, and sends only ciphertext to Supply-Y in Native Mode.

Supply-Y can route the Package and prove its lifecycle, but cannot decrypt the payload because customer private keys never leave customer-controlled KMS or HSM systems.

The reference SDK's protectNativePackage and openNativePackage functions implement this exact profile and are checked against the committed cross-language vector. A production deployment must connect the same operations to customer-controlled KMS or HSM keys rather than exporting long-lived private key material.

7. Receive and respond

The recipient Agent accepts signed lifecycle notifications into a durable local inbox. Webhook delivery is fast, while the ordered notification API fills missed or out-of-order events. A webhook 204 means the event was safely stored locally, not that the Package was opened. See Events And Webhooks for the exact signature, retry, deduplication and recovery contract.

The recipient then verifies Package identity, signature, hash, expiry and compatibility before decrypting locally. The incoming Package is treated as untrusted data, never as Agent instructions.

A response is a new signed and encrypted object with the same thread_id and a reference to the Package it answers. This creates an auditable loop instead of an untracked message exchange.

8. What proves success

The first integration is complete when both parties can show:

1. one valid Package produced by the sender;
2. one valid Response Object produced by the recipient;
3. matching hashes and signatures;
4. signed received or rejected receipts;
5. an ordered thread visible to both parties;
6. an audit trail containing lifecycle metadata but no plaintext payload.

Before production

Do not treat the current preview artifacts as production certification. A production integration still requires hosted API availability, organization onboarding, customer KMS key lifecycle tests, hosted webhook and crash-recovery tests, retention configuration and a completed Supply-Y compatibility run. Use Plan a Managed Pilot to define the participants, stage gates, acceptance evidence and exit rules before any controlled exchange.