01 · Install the SDK
Create an isolated environment and install the published package from PyPI.
python3 -m venv .venv
source .venv/bin/activate
python -m pip install arsia-protocolOn Windows, activate with .venv\Scripts\activate. For the command-line tools, install "arsia-protocol[cli]".
02 · Create, sign and validate
Save this as first_message.py. It runs in memory: nothing is sent and no action is executed.
from arsia_protocol import (
create_request, generate_ed25519_keypair,
sign_message, validate_envelope, verify_message,
)
private_key, public_key = generate_ed25519_keypair()
message = create_request(
from_agent="agent:acme.assistant",
to_agent="agent:acme.reviewer",
payload_type="com.acme.echo",
capabilities=["com.acme.echo"],
args={"message": "Hello, ARSIA"},
)
signed = sign_message(message, private_key, "agent:acme.assistant#key-1")
assert verify_message(signed, public_key)
assert validate_envelope(signed) == []
print("Signature verified. Envelope validated.")03 · Run it
python first_message.pyYou created a request envelope, signed it with Ed25519, verified the signature, and checked its structure and semantics.
What did you check?
| Check | What it tells you |
|---|---|
verify_message | The signature matches the supplied public key over the canonical envelope (JCS, RFC 8785). |
validate_envelope | Runs both layers: validate_schema (L1, JSON Schema 2020-12) and validate_semantic (L2, cross-field rules). An empty list means no errors. |
| Your application | Still needed: resolve trust in the key, check authorization, enforce oversight, and store the audit evidence. |
Apply a compliance profile
Name a profile when you create the envelope, then call apply_profile to fill in its defaults. Do this before signing: changing a signed envelope invalidates the signature.
envelope = create_request(
from_agent="agent:acme.advisor",
to_agent="agent:acme.executor",
payload_type="com.acme.trade.execute",
capabilities=["com.acme.trade.execute"],
args={"portfolio_id": "PF-2847"},
compliance={"profile": "MIFID-II"},
)
envelope = apply_profile(envelope)
signed = sign_message(envelope, private_key, "agent:acme.advisor#key-1")The resulting compliance block, as the SDK produces it:
{
"profile": "MIFID-II",
"audit_required": true,
"retention_days": 1827,
"human_oversight": "required_before_execution",
"explainability_required": true,
"pii_involved": true,
"legal_basis": "contract",
"data_residency": "EU",
"clock_skew_seconds": 60
}See all seven profiles and their defaults on the compliance profiles page.
Ask for human approval
When a profile requires oversight before execution, the executing agent answers the request with create_pending_approval and waits. The reviewer’s answer is built with create_approval_decision, approved or denied, with a justification. Rollback of an executed action is a request built with create_rollback_request.
The SDK’s oversight flow example (opens in a new tab) walks through the full exchange.
Encrypt the payload
encrypt_payload encrypts the payload as a compact JWE, with ECDH-ES key agreement and A256GCM content encryption by default. The receiver uses decrypt_and_verify. Routing fields stay readable, so intermediaries can deliver the envelope without seeing its content.
Command-line tools
With pip install "arsia-protocol[cli]", the arsia command is available.
| Command | What it does |
|---|---|
arsia keygen | Generate an Ed25519 key pair, as PEM, JSON or JWK (--kid sets the key identifier). |
arsia verify | Verify the signature on an envelope file against the sender’s JWK (--jwk). |
arsia inspect | Pretty-print an envelope with basic diagnostics. |
arsia canonicalize | Emit the JCS canonical bytes (RFC 8785) of a JSON document. |
arsia profiles | List the bundled compliance profiles, or print one by name. |
arsia schemas | List the bundled JSON Schemas, or show one. |
arsia vectors | List the bundled test vectors, or run them and report passed, failed and skipped separately. |
arsia version | Print the SDK version and the wire protocol version. |
Before connecting real agents
Keep private keys in managed storage, publish public keys through discovery, and resolve trust on the receiving side. Enforce authorization and oversight in your runtime, and store audit records for the retention the profile requires.