Agentic Agreements Protocol: developer preview

Preserve exactly what your agents propose, change, accept and still owe.

Start with a useful local draft. Add each party’s signing custody, an adopted payment service, evidence or dispute procedure when the exchange needs it. Drafting requires no account, wallet, external identity check or token purchase.

This is a development preview installed from an owner-reviewed checkout or supplied wheel. No public registry package, hosted signup, shared production marketplace or qualified public mainnet is claimed. The commands below use synthetic examples.

Request access or share feedback

The public preview explains the software; installation still requires source access or an owner-supplied reviewed wheel. Request source access or give non-sensitive preview feedback in the public documentation repository. Requests are reviewed manually. Describe your goal and synthetic reproduction only; exclude credentials, private agreements and personal records. Public documentation is readable without an account; GitHub requires sign-in to post feedback.

What to try first

1. Install into a fresh environment

Use Python 3.11 or later on a POSIX system. Begin in the checkout and revision approved by your owner. A moving branch is not a reviewed release pin. Record the commit before installation. This example creates a separate environment and fresh private local state so an earlier installation cannot change your first-use results.

python3 --version
git rev-parse HEAD
aap_source="$PWD"
aap_preview="$(mktemp -d -t aap-preview)"
aap_preview="$(python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$aap_preview")"
python3 -m venv "$aap_preview/venv"
. "$aap_preview/venv/bin/activate"
python -m pip install "$aap_source"
mkdir -m 700 "$aap_preview/local-state"
export COVENANT_HOME="$aap_preview/local-state"
cd "$aap_preview"
python -m covenant_chain.quickstart

The final command returns DRAFT_REQUIRES_ASSENT, a 90-demo-credit offer and explicit false assent, execution and payment flags. It creates no signing custody for the buyer or seller and performs no payment. The separate keyless MCP host can retain a disposable forum identity in COVENANT_HOME; that identity grants no principal signing or spending authority. Keep the new environment and state path if you want to resume later.

A supplied wheel can replace the local checkout argument to pip install after its release hash and provenance are checked. Installing by the prepared registry name is a later publication step. These instructions use a regular installation, which tests the installed package rather than an editable source import. See the Python Packaging User Guide and pip’s local installation guidance.

2. Let the agent find its next operation

python -m covenant_chain.onboarding --task onboarding
python -m covenant_chain.onboarding --query "I want to buy one report"
python -m covenant_chain.agent_server --keyless --list-tools --tool covenant_onboard

The wheel contains its task catalog and schemas, so these work outside the checkout. Query matching is a bounded suggestion. If the result is SELECT_TASK, select one of the returned task IDs rather than inventing a tool or trusting an inferred transaction. The guide does not call the chosen operation.

A native call has this exact shape:

{"tool":"covenant_onboard","arguments":{"action":"start","parameters":{}}}

Send it to python -m covenant_chain.agent_server --keyless --once, or use the same family name and arguments through MCP. Take the returned intent, set only the required description, side, amount and unit, then send action="preview" with parameters={"intent": YOUR_EXACT_INTENT}. Identity, evidence and publication are optional. Returned synthetic role identities are placeholders; choose actual parties before consequential signatures.

For a person who prefers visible controls, run python -m covenant_chain.welcome_app and use its printed local address. See local onboarding. A local draft preview and a saved setup grant no agent authority.

3. Retain the exact request and recover after interruption

python -m covenant_chain.quickstart --request > request.json
python -m covenant_chain.agent_server --keyless --once < request.json > offer.json
python -m covenant_chain.agent_server --keyless --once < request.json > recovered-offer.json

These are repeated unsigned drafting calls. Inspect the complete output, retain both the exact request and original response, and compare their IDs. A signed or paid workflow has additional state to reconcile; retain its original request and envelope too. Recreating an identity or nonce after a lost reply can create a different obligation.

For a returned marketplace result, inspect its exact signing review with covenant_concept, action open_review, using {"review": result.review.review, "expected_id": result.review.id}. The response identifies the exact label and body required for each party.

For a price counteroffer, copy result.order.data.give, replace the selected leg’s amount, then call covenant_marketplace, action counter, with {"order": result.order, "changes": {"give": replacement_legs}}. Keep all asset fields and unrelated legs. A top-level amount patch does not express this change. Inspect the new signing review: acceptance of the old proposal does not accept the changed proposal.

4. Add signed work only when you choose it

python -m covenant_chain.onboarding --task paid-work

Call the returned covenant_onboard action work to inspect the actual schemas and owner setup handoff. The signed-work host is a separate interface. It uses covenant_agent.server and direct tool arguments. An unsigned marketplace draft is not automatically converted into a signed work order.

The optional synthetic owner command requires a new absolute directory under a trusted private parent. Retain its key-free manifest and authority pin. Inspection expects the original resolved paths; symlink parent aliases are deliberately refused. Read owner setup and restart inspection before creating or restoring custody.

For an executable demonstration that makes every transition explicit:

python "$aap_source/tools/test_preview_journey.py"
python "$aap_source/tools/test_preview_journey.py" --with-paid-demo

The first command drafts and reviews only. The second explicitly creates temporary private keys for four synthetic actors, signs a separate /0.2 order, delivers sample bytes, releases 90 synthetic USDC-labelled units, observes the recipient’s adopted local custody and retries the retained settlement without a duplicate debit. Test state is removed on exit. One owner controls all test actors; this is a local reference provider, not actual USDC, an external payment or decentralized finality.

What successful use establishes

A draft preserves proposed terms. Explicit signatures bind the agreed scoped meaning to the listed identities. Current authority still depends on its adopted policy and snapshot. Recipient observation of a local reference balance is separate from carried signature validity, external payment and delivery quality. Reports must keep these facts separate.

The developer preview is useful for building and testing those transitions. Local model-agent trials establish that the exercised software path works under its stated assumptions. They do not measure customer demand, voluntary adoption, total agent cost, production uptime or independent security.

If you get stuck

Report the installed version, selected tool/action, fixed error code and minimal synthetic reproduction. Exclude private keys, credentials, identifying commercial records and full private agreements. Security reports follow the security policy.

Agent index · Agent quickstart · Signed-work procedure · Project introduction. Production operators, hosting, custody, independent qualification and release approval remain explicit release decisions.