Canonical AXME protocol and public API schema repository. This is the source of truth for all contract definitions consumed by the runtime, SDKs, documentation, and conformance suite.
Alpha · Protocol and API surface are stabilizing. Not recommended for production workloads yet.
Feedback and schema proposals welcome → hello@axme.ai
AXME is a coordination infrastructure for durable execution of long-running intents across distributed systems.
It provides a model for executing intents — requests that may take minutes, hours, or longer to complete — across services, agents, and human participants.
At the core of AXME is AXP (Intent Protocol) — an open protocol that defines contracts and lifecycle rules for intent processing.
AXP can be implemented independently.
The open part of the platform includes:
- the protocol specification and schemas
- SDKs and CLI for integration
- conformance tests
- implementation and integration documentation
AXME Cloud is the managed service that runs AXP in production together with The Registry (identity and routing).
It removes operational complexity by providing:
- reliable intent delivery and retries
- lifecycle management for long-running operations
- handling of timeouts, waits, reminders, and escalation
- observability of intent status and execution history
State and events can be accessed through:
- API and SDKs
- event streams and webhooks
- the cloud console
axme-spec owns the normative contracts for the entire AXME platform. Everything else — the runtime, SDKs, docs, and conformance tests — is derived from or validated against this repository.
axme-spec/
├── schemas/
│ ├── protocol/ # AXP wire protocol definitions (envelope, frames, versioning)
│ └── public_api/ # Public REST API contracts (request/response/error schemas)
├── docs/
│ ├── diagrams/ # Schema-level visualizations
│ ├── ADR-001-protocol-name.md
│ ├── ADR-004-synapse-no-modification-policy.md
│ ├── ADR-005-matrix-transport-e2ee-rollout.md
│ ├── ADR-006-intent-lifecycle-v1.md
│ ├── idempotency-correlation-rules.md
│ ├── intent-lifecycle-v1.md
│ ├── protocol-error-status-model.md
│ ├── public-api-schema-index.md
│ └── schema-versioning-rules.md
└── scripts/
└── validate_schemas.py
Note on ADRs: ADR-001, ADR-004 through ADR-006 live here. ADR-002 (service boundaries) and ADR-003 (trust/consent model) are hosted in
axme-docsas they span the full platform rather than schema contracts specifically.
The AXP envelope wraps every intent. It carries the payload, sender identity, schema version, idempotency key, and a cryptographic signature applied at the gateway boundary.
Each field in the envelope is normatively defined here. The runtime and all SDKs must conform to these field names, types, and validation rules.
Schemas follow a three-phase lifecycle: stable → deprecated → removed. Breaking changes require a new major schema version. Additive changes are backward-compatible.
A schema version enters deprecation with a minimum 90-day notice period. Clients targeting a deprecated version receive Deprecation response headers. Removal is announced in the migration guide.
All schema changes go through a governance review before landing. The compatibility matrix ensures no existing consumer breaks across patch and minor versions.
Governance steps: proposal → impact analysis → compatibility check → reviewer sign-off → merge → changelog entry → docs sync.
Intent schemas are typed by intent_type. The payload field is a structured JSON object defined per type — not a free-form blob. This ensures every intent carries a machine-readable, versioned contract.
Businesses define their own intent_type namespaces. The platform validates the payload against the registered schema for that type. Custom fields are allowed in designated extension zones.
All error responses follow a uniform model: HTTP status + machine-readable error code + retriability hint.
4xx errors are client errors and are not retried. 5xx errors carry a Retry-After hint. Idempotency-safe operations can be safely retried with the original idempotency key.
A contract family is considered complete only when it is aligned across all five layers:
axme-spec— normative schema definition (this repo)axme-docs— OpenAPI artifact and narrative documentation- SDK clients — implemented and tested method in each of the five SDKs
axme-conformance— conformance check covering the contract- Runtime —
axme-control-planebehavior matches the schema
python -m pip install -e ".[dev]"
python scripts/validate_schemas.py
pytest| Repository | Relationship |
|---|---|
| axme-docs | Derives OpenAPI artifacts and narrative docs from these schemas |
| axme-conformance | Validates runtime and SDK behavior against these contracts |
| Control-plane runtime (private) | Runtime implementation must conform to schemas defined here |
| axme-sdk-python | Python client — API surface derived from these contracts |
| axme-sdk-typescript | TypeScript client |
| axme-sdk-go | Go client |
| axme-sdk-java | Java client |
| axme-sdk-dotnet | .NET client |
- Schema proposals and breaking-change requests: open an issue with label
schema-proposal - Quick Start: https://cloud.axme.ai/alpha/cli · Contact: hello@axme.ai
- Security disclosures: see SECURITY.md
- Contribution guidelines: CONTRIBUTING.md