arsia-protocol — Python SDK
The trust layer for AI agents. Make any agent enterprise-ready — compliant, secure, and auditable out of the box.
Python SDK for the ARSIA Protocol: the compliance-enforced communication layer for AI agents. Build, sign, verify, and validate ARSIA message envelopes over any transport — HTTP, WebSocket, gRPC, MCP, A2A, or your own.
Fully typed — works with mypy, pyright, and IDE autocompletion out of the box.
Install
pip install arsia-protocol # core SDK
pip install "arsia-protocol[cli]" # plus the `arsia` CLI
pip install "arsia-protocol[dev]" # development (tests, mypy, ruff)
Quickstart
from arsia_protocol import (
create_request, generate_ed25519_keypair, sign_message, verify_message,
)
# 1. Generate an Ed25519 keypair (developer convenience — use an HSM / KMS
# in production).
priv, pub = generate_ed25519_keypair()
kid = "agent:acme.bot#k1"
# 2. Build a signed request envelope.
envelope = create_request(
from_agent="agent:acme.bot",
to_agent="agent:other.svc",
payload_type="com.arsiaprotocol.echo",
capabilities=["com.arsiaprotocol.echo"],
args={"msg": "hello"},
)
signed = sign_message(envelope, priv, kid)
# 3. On the recipient side — verify the signature.
assert verify_message(signed, pub) is True
Validate against schema + semantics
from arsia_protocol import validate_schema, validate_semantic
l1_errors = validate_schema(signed) # L1: JSON Schema (Draft 2020-12)
l2_errors = validate_semantic(signed) # L2: timestamps, kid match, etc.
assert l1_errors == [] and l2_errors == []
Apply a compliance profile
from arsia_protocol import apply_profile
# The envelope must declare compliance.profile — apply_profile reads it
# from there and inherits the profile's defaults (retention, jurisdiction, …).
envelope["compliance"] = {"profile": "GDPR-STANDARD"}
enriched = apply_profile(envelope) # strict=False by default
Key Concepts
verify vs. validate
| Function | What it checks | Question it answers |
|---|---|---|
verify_message(envelope, pub_key) |
Ed25519/ES256 signature | "Was this signed by the claimed sender?" |
validate_schema(envelope) |
JSON Schema (Draft 2020-12) | "Does this match the ARSIA envelope structure?" |
validate_semantic(envelope) |
Cross-field rules (timestamps, kid prefix, capabilities) | "Is this envelope internally consistent?" |
validate_envelope(envelope) |
Both schema + semantic (convenience) | "Is this well-formed and consistent?" |
A typical receiver calls both: verify_message() to trust the sender, then
validate_envelope() to trust the content.
build_* vs. create_* naming
-
create_*(7 functions) — envelope-level factories that produce a complete, signable ARSIA envelope:create_request,create_response,create_error,create_event,create_pending_approval,create_approval_decision,create_rollback_request. -
build_*(49 functions) — sub-component builders that produce parts of envelopes: audit records, error details, JWKs, state operation arguments, discovery documents, etc.
Rule of thumb: if it returns a complete envelope ready to sign, it's create_*.
If it returns a component or record, it's build_*.
arsia CLI
pip install "arsia-protocol[cli]"
arsia keygen --kid agent:acme.bot#k1 # generate Ed25519 key material
arsia verify envelope.json --jwk sender.jwk # verify a signed envelope
arsia canonicalize doc.json # emit RFC 8785 canonical bytes
arsia inspect envelope.json # pretty-print with diagnostics
arsia schemas # list bundled JSON Schemas
arsia vectors # list bundled test vectors
arsia vectors run # check every vector: schema, semantics, signature
arsia profiles GDPR-STANDARD # print a compliance profile
What the SDK does NOT do
- Transport (HTTP, WebSocket, MCP, A2A) — that's
arsiactl, not the SDK. - Agent execution, planning, tool use — that's the agent framework.
- Audit trail storage — the SDK builds audit records; it does not persist them.
- OAuth2 issuance — the SDK validates tokens, does not issue them.
- Payload interpretation — the SDK signs and verifies envelopes; it never inspects payload content beyond routing-relevant fields.
Documentation
| Resource | Description |
|---|---|
| Learning Path | Step-by-step guide from install to production |
| Concepts | Mental model: envelopes, lifecycle, naming, profiles |
| Cookbook | 22 copy-pasteable recipes for common tasks |
| Examples | 14 runnable scripts (10 basic + 4 regulated use cases) |
| API Reference | Full API documentation (run mkdocs serve) |
| Demos | Production-realistic multi-agent scenarios — run any of them in under a minute |
Development
cd python
pip install -e ".[dev]"
pytest tests/ -v
mypy src/arsia_protocol/
ruff check src/
ruff format src/
Links
- Specification: https://github.com/arsialabs/arsia-protocol
- Repository: https://github.com/arsialabs/arsia-protocol-sdk
- Website: https://arsiaprotocol.org
- Issues: https://github.com/arsialabs/arsia-protocol-sdk/issues
- Changelog: CHANGELOG.md
ARSIA Protocol (arsiaprotocol.org) · by Arsia Labs · BSL 1.1
Metadata
Release files for arsia-protocol 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| arsia_protocol-1.0.1.tar.gz | 587.7 kB | Without provenance | Details for arsia_protocol-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| arsia_protocol-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for arsia_protocol-1.0.1-py3-none-any.whl |
Total release size: 1.0 MB
Release files / arsia_protocol-1.0.1.tar.gz
| Download URL | arsia_protocol-1.0.1.tar.gz |
|---|---|
| Size | 587.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0771c951abab5c8373afbc2739e3e1ef50e57454d67ccd385a39941f7822edab
|
|
BLAKE2b-256 checksum How to use checksums |
3bf4d5f0aabb0bb94e64026ba39e72382d4dd8b0731a1e9afdd75e61af16b503
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / arsia_protocol-1.0.1-py3-none-any.whl
| Download URL | arsia_protocol-1.0.1-py3-none-any.whl |
|---|---|
| Size | 453.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
175097588a6450971b3df6e01b89039c8ca12e30bce0fddc87d2c051890b88b5
|
|
BLAKE2b-256 checksum How to use checksums |
49422fd937ee82c35f65fcfbd47608bde6cf60501c0448234d81f1b437449a9e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Security for arsia-protocol 1.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.