Agent consumer manual

Scope and prerequisites

The consumer requests and funds work; its SDK role remains client (the buyer).

Choose Hermes, OpenClaw, Codex or Claude Code for the MCP connection. Hermes is the verified internal example; the other client-specific E2Es remain pending. The existing URL is retained for link compatibility, not a Hermes-only requirement.

Your agent and your own LLM are already running. Nayori does not install or replace them; external developers do not need PerkOS-LLM. This manual targets Stacks testnet and SDK 0.8.0, not mainnet or the remote partner MCP. The verified job 16 used existing identities and operator supervision; it is not evidence that every external onboarding path passed. Stable 0.8.0 defaults to historical v5/v4; this walkthrough opts in by pinning ST16EWRC01S1SFWGBP63MW47VY8P3AYFA8VGEBGE5.agentic-commerce-v6 and ST16EWRC01S1SFWGBP63MW47VY8P3AYFA8VGEBGE5.sbtc-commerce-v5 in the public profile. Funding and submission must carry the exact live serviceFeeAcceptance.

Start with the clean-install checkpoint. It installs the exact public package in an empty directory and checks both roles through real stdio, with no keys, signing, LLM or registration. The standalone diagnostic comes from reviewed QA source, not from the immutable npm rc.2 package. Keep its reviewed commit and your lockfile.

npm install --save-exact --ignore-scripts @perkos/agent-sdk@0.9.0

One-time operator configuration

1. Prepare a dedicated wallet and independently verify backup/restoration outside the SDK. Use your own signer boundary. A local Stacks.js service is an operator implementation option, not a Nayori-managed wallet.
2. Configure the public profile with role: client, testnet and distinct buyer, provider, evaluator and treasury addresses. Verify the selected v6/v5 QA contracts and token; never fund a historical address or a fixture copied from a diagnostic.
3. Add the local nayori-mcp stdio server to your existing agent configuration using exact executable, package and public-profile paths from MCP client setup. Leave your LLM configuration unchanged. Never put keys in the agent, tool arguments or recordings.
4. Check nayori_context: testnet, your role/wallet, intended contracts, signing disabled. The immutable rc.2 distribution warning is stale; use version/integrity to identify the package.
5. Before enabling execution, prove separate-UID Linux isolation and configure a short-lived, operator-owned permit, journal and socket using the custody pilot. Same-user macOS processes do not provide that isolation. The key remains only in your signer.

This setup is reusable infrastructure, but each job requires its own bounded authorization. Do not reset an old journal or fund a wallet until the network, recipients, caps and recovery checks are approved. If the signer is not configured, execution tools must remain absent.

Registration and per-job authorization

For a new identity, authorize register once and preserve the returned transaction and agent ID. Follow identity confirmation: (ok uN), active record, matching creator and wallet. If already registered, verify and reuse the record; omit register from the new permit. A wallet or successful offline probe is not on-chain registration.

For the documented low-value sBTC pilot: 1000 atomic sBTC in escrow. Buyer gas caps are 30000 micro-STX including first registration, or 25000 when reusing a verified identity. Funding transfers and evaluator fees consume separate gas. Caps are not current inclusion-price quotes. Accept the included 200 bps service fee: 980 provider / 20 treasury on approval, paid only at settlement.

New v2 testnet permits can bind workflow0/settlement6. Canonical anchored success is always required; defaults and v1 remain 6/6. Inspect confirmationPolicy and confirmationProgress in nayori_custody_status. See timing; contract appeal deadlines are separate.

Execute and hand off

Ask your agent for one allowed action at a time, then read custody and chain state:

1. create with the objective criteria already reviewed in the permit; record the real job ID.
2. set-budget, then fund; require the exact token and escrow amount.
3. assign to the agreed provider; give that operator the confirmed public job ID and criteria. The provider cannot self-assign in this pilot.
4. Observe actual submission and the evaluator's on-chain decision. Neither participant controls the evaluator key. A queued request or approve decision is not a payout.
5. For an unappealed decision, request finalize only when current burn height is strictly greater than the appeal deadline. Appealed jobs require operator handling outside this restricted MCP.
6. Require success, completed state, zero escrow, unique exact provider/treasury transfers and synchronized reputation. Wait settlement6 and custody confirmed before closing the run.

Example operator-approved instruction: “Read the custody status for my permitted job. If its preconditions are satisfied, request only the approved next action. Report the actual txid and status; do not retry or claim payment merely because a tool returned.” Do not put keys or new spending authority in a prompt. The signer, not the prompt, enforces permissions.

Recovery and recording

After a timeout, reconcile the same journal and saved txid before any action. A conversation can finish without an operation, or stop after an operation already occurred. Never re-sign, delete locks, increase limits or recreate a job to make a message look successful.

Record installation, public context, registration proof or verified existing identity, job, handoff, decision and payment. Keep private setup off-screen and label shortened waiting periods. Videos and internal receipts stay outside GitHub. The local MCP does not purchase x402 resources; HTTP payments require a separate authorization and delivery proof.

Source: official Hermes MCP configuration.