# Install Supply-Y In An Agent

Supply-Y onboarding is Agent-facing. A company copies one paragraph into an existing coding or operations Agent; the Agent prepares the integration and returns a compatibility report before anything can be enabled. The prompt is an execution request, not a prose setup guide.

The stable machine starting point is [`/.well-known/supply-y`](/.well-known/supply-y). An Agent reads that one discovery document to find the digest-pinned Protocol 1.0 Release Manifest, current installation instructions, signed Skill releases, publisher-key status, conformance source and security boundary. It does not need to guess product URLs or combine mutable contract links.

The prompt is deliberately guarded. It selects and verifies an integration profile, but it cannot invent credentials, export private keys, approve disclosure or silently enable production traffic.

The Agent must return one machine-readable result, not a conversational "done." The versioned [`Agent Compatibility Report 0.5 schema`](/agent-compatibility-report/0.5/schema.json) requires every check, exact result evidence, key-custody state, missing configuration and one explicit `enable` or `do_not_enable` decision.

## Choose an integration profile

Supply-Y does not require every company Agent to run TypeScript. The installer detects the existing Agent stack and selects exactly one profile:

| Profile | Use when | What enters the company Agent |
| --- | --- | --- |
| `protocol_contract` | Any Agent; this is the public default | The digest-pinned Protocol Bundle plus approved signed Skills; no repository account or Supply-Y SDK runtime |
| `typescript_sdk` | The Agent runs TypeScript or JavaScript and the operator confirms authorized source access | A locally built archive of the restricted reference SDK plus approved signed Skills |

Both profiles first validate [`/protocol/1.0/manifest.json`](/protocol/1.0/manifest.json) against its Schema and discovery-pinned digest. They fetch the versioned OpenAPI, JSON Schemas and normative Markdown profiles only from the Manifest, verify each exact byte count and digest, and store the release binding locally.

The Manifest also pins a public [`Protocol 1.0 Agent Bundle`](/protocol/1.0/bundle.json). It contains 55 exact Base64-encoded artifacts: all normative contracts plus the fixtures, behavior cases, cryptographic vectors and compatibility contracts needed to build evidence in another Agent stack. The Agent validates the Bundle, decodes every artifact and verifies every individual byte count and digest before use. It contains fictional public test material and no customer data.

Discovery separately pins the exact bytes of the published [`Agent Conformance Profile 1.0`](/agent-conformance/1.0/profile.json). That profile fixes the same nine checks for every language, who must execute each check, the public Bundle or customer resource used as input, and every exact `result_id` the Agent must return. It is the evidence contract; repository command output is only reference evidence and cannot stand in for a test executed by the named customer Agent or customer infrastructure.

The `protocol_contract` profile keeps the customer's existing runtime and requires no GitHub access or Supply-Y SDK. It uses standard JSON Schema, JOSE, HTTP Signature and cryptographic libraries in that stack; it must not hand-roll cryptography. Both profiles must provide the same behavior:

- local Schema and Profile validation;
- Native Package encryption, signing, verification and opening;
- KMS or HSM signer and decrypter adapter boundaries;
- all 21 operations in the Agent API contract;
- stable protocol and RFC 9457 error handling.

The TypeScript SDK source is currently restricted and no public npm package exists. An Agent may select `typescript_sdk` only after the operator confirms authorized repository access. Without that access, it must remain on `protocol_contract`; it must not repeatedly try to clone the private repository or claim the SDK was installed.

The Agent also installs an operator-approved signed Skill. The current catalog contains `supply-y.core@0.1.0` and `supply-y.material-risk@0.1.0`. These are JSON rule packages, not executable plugins: they declare required fields, prohibited disclosures, ordered protocol operations, approval behavior and completion evidence.

Before enabling a Skill, the Agent must verify the release signature, fetch only its signed `artifact_url`, verify the canonical JSON digest, validate the Skill schema, resolve dependencies and show the requested capabilities to the operator. The published preview key is test-only and cannot authorize production exchange.

Before sending a Package, the Agent applies the approved Skill locally and creates a signed Policy Receipt. The receipt binds the exact encrypted content digest, policy digest, sender, recipient, Skill version, required checks and any human approval. The Agent sends that claim to `POST /v1/policy-receipts`, then sends the Package only if the response is signature-verified and `eligible`. Supply-Y sees the signed claim and encrypted Package, not the business plaintext.

## What the Agent must ask for

Installation can run without production secrets. Connection cannot. The Agent must stop and ask the operator for:

- the Supply-Y API URL;
- OAuth client configuration;
- organization and Agent IDs;
- the approved Skill ID and version;
- signing and encryption key IDs;
- the selected Native or Catena-X transport;
- any local disclosure and human-approval requirements;
- webhook or polling notification delivery.

## Customer-local connection profile

The Agent writes those decisions into a [`Customer Connection Profile`](/customer-connection-profile.schema.json) stored in the customer's environment. The strict profile binds the verified Protocol Release Manifest and covers API and OAuth metadata, organization and Agent identity, transport, customer key references, approved signed Skills, local policy and notification delivery. It rejects unknown fields, inline OAuth secrets, private JWKs, stale release digests, insecure token or webhook URLs, incomplete Catena-X settings and missing approver references.

The profile contains references such as `kms://`, `secret://` and `policy://`, not the secret, private key or business data itself. The complete profile is not uploaded to Supply-Y. The compatibility report carries only its version, environment, validation status and canonical SHA-256 digest so an audit can identify which local configuration passed.

## Key custody

Production private keys do not enter Supply-Y or exportable Agent configuration. The `typescript_sdk` profile implements `senderSigner` and `recipientDecrypter`; the `protocol_contract` profile implements equivalent boundaries in its own language. Those adapters call customer-controlled KMS or HSM operations and return only a signed exchange or decrypted plaintext bytes. The implementation verifies the exact Supply-Y payload, protected header, algorithm and key ID, then rechecks authenticated metadata, digest and protocol object validation.

The JWK input remains available for local tests and the committed conformance vector. It is not the recommended production key path.

## Required result

The Agent finishes with a compatibility report, not an unexplained success message. The report must state:

1. integration profile, implementation language and Protocol 1.0 release binding; include a reference SDK only when `typescript_sdk` is actually installed;
2. selected transport mode;
3. all nine required checks, their named executor, observation time and every exact result ID from the pinned Conformance Profile;
4. KMS or HSM adapter status;
5. connection-profile version, digest and missing configuration;
6. security controls confirmed;
7. verified Skill release, digest and requested capabilities;
8. Policy Receipt signing and eligibility evidence;
9. an explicit `enable` or `do not enable` recommendation.

Any failed conformance check, missing key adapter, missing credential or unresolved approval requirement produces `do not enable`.

The report decision is also checked as a protocol rule. `enable` is accepted only when all nine check IDs appear exactly once and pass, both non-exporting key adapters are verified, no configuration is missing and the decision scope matches the requested mode. Production enablement additionally requires a production API and production Skill publisher trust. A report can therefore be valid JSON while still being rejected as an unsafe decision.

The current [`production-blocked example`](/agent-compatibility-report/0.5/example.json) shows the honest result: a Java Agent can implement the public Protocol Bundle without declaring an SDK, but production exchange remains disabled until the customer Agent itself completes peer interoperability and the production API and trust root exist. A separate committed local-preview example demonstrates the narrower TypeScript case that may return `enable` without claiming production readiness.

## Machine-readable entry points

- [`/.well-known/supply-y`](/.well-known/supply-y) is the canonical discovery root for an Agent.
- [`/.well-known/supply-y/v0.5/schema.json`](/.well-known/supply-y/v0.5/schema.json) is its immutable `supply-y.net` JSON Schema contract.
- [`/agent-install/0.9/manifest.json`](/agent-install/0.9/manifest.json) and its [schema](/agent-install/0.9/schema.json) pin the current copy-paste installation contract.
- [`/protocol/1.0/manifest.json`](/protocol/1.0/manifest.json) inventories the exact immutable Protocol 1.0 artifacts, byte counts and digests.
- [`/protocol/1.0/manifest.schema.json`](/protocol/1.0/manifest.schema.json) strictly validates that release inventory.
- [`/protocol/1.0/bundle.json`](/protocol/1.0/bundle.json) contains the complete public Agent implementation and conformance material.
- [`/protocol/1.0/bundle.schema.json`](/protocol/1.0/bundle.schema.json) validates the Bundle before any embedded artifact is decoded.
- [`/agent-install.txt`](/agent-install.txt) is the complete plain-text instruction set for an Agent.
- [`/agent-install/0.8/manifest.json`](/agent-install/0.8/manifest.json) exposes versions, canonical resources, required configuration, checks and security invariants.
- [`/agent-install/0.8/schema.json`](/agent-install/0.8/schema.json) strictly validates the versioned installation manifest and rejects unknown fields.
- [`/agent-conformance/1.0/profile.json`](/agent-conformance/1.0/profile.json) fixes the cross-language checks, executors, inputs and exact result IDs.
- [`/agent-conformance/1.0/schema.json`](/agent-conformance/1.0/schema.json) strictly validates that evidence profile.
- [`/agent-compatibility-report/0.5/schema.json`](/agent-compatibility-report/0.5/schema.json) defines the required structured installation result.
- [`/agent-compatibility-report/0.5/example.json`](/agent-compatibility-report/0.5/example.json) shows the current production-blocked result.
- [`/customer-connection-profile.schema.json`](/customer-connection-profile.schema.json) defines the strict customer-local configuration.
- [`/customer-connection-profile.example.json`](/customer-connection-profile.example.json) shows references without real secrets or private keys.
- [`/docs/skills`](/docs/skills) lists signed Skill releases and the exact verification sequence.
- [`/openapi.json`](/openapi.json) is the executable API contract.

---

Canonical HTML: [Install Supply-Y In Your Agent](https://supply-y.net/docs/agent-install)
Agent documentation index: [llms.txt](https://supply-y.net/llms.txt)