axp-spec

Normative source of truth for all AXP protocol and public API contracts.

axme · Docs · Conformance

AXP is the open wire protocol behind AXME. This repo defines the normative contracts - everything else (runtime, SDKs, conformance suite) derives from or validates against these schemas.

What Lives Here

axp-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-docs as they span the full platform rather than schema contracts specifically.

Intent Lifecycle

Every intent follows a durable lifecycle with explicit states:

CREATED -> ACCEPTED -> PROCESSING -> COMPLETED
                          |
                          v
                       WAITING (human / agent / time / tool)
                          |
                          v
                       PROCESSING -> COMPLETED
                                        |
                                     FAILED

• CREATED - intent submitted, validated, persisted
• ACCEPTED - routed to handler agent
• PROCESSING - agent is working on it
• WAITING - paused for human approval, timeout, external signal, or sub-intent
• COMPLETED - terminal success with result
• FAILED - terminal failure with error

Waiting states are first-class. An intent can wait for hours or days and resume exactly where it left off.

Delivery Bindings

Five ways to deliver an intent to an agent:

Runtime Steps

Internal steps (no agent needed)

These run inside the AXME runtime without any external agent:

Human task types

Eight structured task types for human-in-the-loop workflows:

ScenarioBundle

The simplest way to run a workflow - one JSON file:

{
  "agents": [{"address": "my-service", "delivery_mode": "stream"}],
  "workflow": {"steps": [{"step_id": "process", "assigned_to": "my-service"}]},
  "intent": {"type": "task.v1", "payload": {"data": "..."}}
}

axme scenarios apply scenario.json --watch

This provisions agents, compiles the workflow, submits the intent, and streams lifecycle events - all in one command.

Protocol Envelope

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.

Related Repositories

python -m pip install -e ".[dev]"
python scripts/validate_schemas.py
pytest

Contributing

• Schema proposals and breaking-change requests: open an issue with label schema-proposal
• Contribution guidelines: CONTRIBUTING.md

contact@axme.ai · @axme_ai · Security · License