Skip to content

Commit 5fe5ee2

Browse files
George-iamclaude
George-iam
and
claude
authored
docs: add protocol concepts to README - delivery bindings, runtime steps, human task types, ScenarioBundle (#35)
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent c8b1de0 commit 5fe5ee2

1 file changed

Lines changed: 145 additions & 71 deletions

File tree

‎README.md‎

Lines changed: 145 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,144 @@
11
# axme-spec
22

3-
**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.
3+
**Canonical AXME protocol and public API schema repository.** Source of truth for all contract definitions consumed by the runtime, SDKs, documentation, and conformance suite.
44

5-
> **Alpha** · Protocol and API surface are stabilizing. Not recommended for production workloads yet.
6-
> Feedback and schema proposals welcome → [hello@axme.ai](mailto:hello@axme.ai)
5+
> **Alpha** - Protocol and API surface are stabilizing. Not recommended for production workloads yet.
6+
> Feedback and schema proposals welcome -> [hello@axme.ai](mailto:hello@axme.ai)
77
88
---
99

1010
## What Is AXME?
1111

1212
AXME is a coordination infrastructure for durable execution of long-running intents across distributed systems.
1313

14-
It provides a model for executing **intents** — requests that may take minutes, hours, or longer to complete — across services, agents, and human participants.
14+
It provides a model for executing **intents** - requests that may take minutes, hours, or longer to complete - across services, agents, and human participants.
1515

16-
## AXP — the Intent Protocol
16+
Durable execution where agents, services, and humans coordinate as equals.
1717

18-
At the core of AXME is **AXP (Intent Protocol)** — an open protocol that defines contracts and lifecycle rules for intent processing.
18+
## AXP - the Intent Protocol
19+
20+
At the core of AXME is **AXP (Intent Protocol)** - an open protocol that defines contracts and lifecycle rules for intent processing.
21+
22+
AXP is not RPC. An intent is not a function call that returns immediately. It is a durable request with a tracked lifecycle - created, processed, waited on, completed or failed - across time, across machines, across trust boundaries.
1923

20-
AXP can be implemented independently.
2124
The open part of the platform includes:
2225

23-
- the protocol specification and schemas
24-
- SDKs and CLI for integration
25-
- conformance tests
26-
- implementation and integration documentation
26+
- the protocol specification and schemas (this repo)
27+
- [SDKs](https://github.com/AxmeAI/axme-sdk-python) and [CLI](https://github.com/AxmeAI/axme-cli) for integration
28+
- [conformance tests](https://github.com/AxmeAI/axme-conformance)
29+
- [implementation and integration documentation](https://github.com/AxmeAI/axme-docs)
30+
31+
## Intent Lifecycle
32+
33+
Every intent follows a durable lifecycle with explicit states:
34+
35+
```
36+
CREATED -> ACCEPTED -> PROCESSING -> COMPLETED
37+
|
38+
v
39+
WAITING (human / agent / time / tool)
40+
|
41+
v
42+
PROCESSING -> COMPLETED
43+
|
44+
FAILED
45+
```
46+
47+
- **CREATED** - intent submitted, validated, persisted
48+
- **ACCEPTED** - routed to handler agent
49+
- **PROCESSING** - agent is working on it
50+
- **WAITING** - paused for human approval, timeout, external signal, or sub-intent
51+
- **COMPLETED** - terminal success with result
52+
- **FAILED** - terminal failure with error
53+
54+
Waiting states are first-class. An intent can wait for hours or days and resume exactly where it left off.
55+
56+
## Delivery Bindings
57+
58+
Five ways to deliver an intent to an agent:
59+
60+
| Binding | How it works | Use case |
61+
|---|---|---|
62+
| **stream** | SSE persistent connection - agent stays connected, intents pushed in real-time | Low-latency, always-on agents |
63+
| **poll** | Agent pulls on its own schedule via `GET /v1/intents?status=pending` | Batch processing, cron jobs |
64+
| **http** | Platform pushes to agent's URL (webhook with HMAC signature) | Serverless functions, existing APIs |
65+
| **inbox** | Human-facing task queue - tasks appear in CLI (`axme tasks list`) or email | Human-in-the-loop workflows |
66+
| **internal** | Runs inside the platform runtime - no external agent needed | Timeouts, reminders, approvals |
67+
68+
## Runtime Steps
69+
70+
### Internal steps (no agent needed)
71+
72+
These run inside the AXME runtime without any external agent:
73+
74+
| Step | What it does |
75+
|---|---|
76+
| **human_approval** | Pause workflow, wait for human to approve/reject via CLI, email magic link, or web form |
77+
| **timeout** | Fail the intent if not completed within a deadline |
78+
| **reminder** | Send a reminder after N seconds of waiting |
79+
| **delay** | Pause workflow for a fixed duration before continuing |
80+
| **escalation** | Chain of reminders with increasing urgency |
81+
| **notification** | Send a one-way notification (email, webhook) without waiting |
82+
83+
### Human task types
84+
85+
Eight structured task types for human-in-the-loop workflows:
86+
87+
| Type | Purpose |
88+
|---|---|
89+
| **approval** | Yes/no gate - deploys, budgets, agent actions |
90+
| **form** | Structured input with required fields - config, onboarding data |
91+
| **review** | Approve, request changes, or reject with comments - code review, document sign-off |
92+
| **override** | Bypass a policy gate with mandatory justification (audit-logged) |
93+
| **confirmation** | Confirm a real-world action was completed - deployment verified, payment sent |
94+
| **assignment** | Route work to a person or team with structured fields |
95+
| **clarification** | Request missing context - comment required before proceeding |
96+
| **manual_action** | Complete a physical task and attach evidence - hardware swap, site inspection |
97+
98+
## ScenarioBundle
99+
100+
The simplest way to run a workflow - one JSON file:
101+
102+
```json
103+
{
104+
"agents": [{"address": "my-service", "delivery_mode": "stream"}],
105+
"workflow": {"steps": [{"step_id": "process", "assigned_to": "my-service"}]},
106+
"intent": {"type": "task.v1", "payload": {"data": "..."}}
107+
}
108+
```
109+
110+
```bash
111+
axme scenarios apply scenario.json --watch
112+
```
113+
114+
This provisions agents, compiles the workflow, submits the intent, and streams lifecycle events - all in one command.
27115

28116
## AXME Cloud
29117

30118
**AXME Cloud** is the managed service that runs AXP in production together with **The Registry** (identity and routing).
31119

32-
It removes operational complexity by providing:
120+
- Reliable intent delivery and retries
121+
- Lifecycle management for long-running operations
122+
- Human approval, timeouts, reminders, escalation - built in
123+
- Observability of intent status and execution history
33124

34-
- reliable intent delivery and retries
35-
- lifecycle management for long-running operations
36-
- handling of timeouts, waits, reminders, and escalation
37-
- observability of intent status and execution history
125+
Quick start: [cloud.axme.ai/alpha/cli](https://cloud.axme.ai/alpha/cli)
38126

39-
State and events can be accessed through:
127+
---
40128

41-
- API and SDKs
42-
- event streams and webhooks
43-
- the cloud console
129+
## Protocol Envelope
130+
131+
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.
132+
133+
![AXP Protocol Envelope](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/protocol/01-protocol-envelope.svg)
134+
135+
*Each field in the envelope is normatively defined here. The runtime and all SDKs must conform to these field names, types, and validation rules.*
44136

45137
---
46138

47139
## What Lives Here
48140

49-
`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.
141+
`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.
50142

51143
```
52144
axme-spec/
@@ -72,96 +164,78 @@ axme-spec/
72164
73165
---
74166

75-
## Protocol Envelope
76-
77-
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.
78-
79-
![AXP Protocol Envelope](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/protocol/01-protocol-envelope.svg)
167+
## Related Repositories
80168

81-
*Each field in the envelope is normatively defined here. The runtime and all SDKs must conform to these field names, types, and validation rules.*
169+
| Repository | Relationship |
170+
|---|---|
171+
| [axme-docs](https://github.com/AxmeAI/axme-docs) | Derives OpenAPI artifacts and narrative docs from these schemas |
172+
| [axme-conformance](https://github.com/AxmeAI/axme-conformance) | Validates runtime and SDK behavior against these contracts |
173+
| Control-plane runtime (private) | Runtime implementation must conform to schemas defined here |
174+
| [axme-sdk-python](https://github.com/AxmeAI/axme-sdk-python) | Python client - API surface derived from these contracts |
175+
| [axme-sdk-typescript](https://github.com/AxmeAI/axme-sdk-typescript) | TypeScript client |
176+
| [axme-sdk-go](https://github.com/AxmeAI/axme-sdk-go) | Go client |
177+
| [axme-sdk-java](https://github.com/AxmeAI/axme-sdk-java) | Java client |
178+
| [axme-sdk-dotnet](https://github.com/AxmeAI/axme-sdk-dotnet) | .NET client |
82179

83180
---
84181

85-
## Schema Versioning and Deprecation
182+
<details>
183+
<summary><strong>Schema Governance (for contributors)</strong></summary>
184+
185+
### Schema Versioning and Deprecation
86186

87-
Schemas follow a three-phase lifecycle: stable → deprecated → removed. Breaking changes require a new major schema version. Additive changes are backward-compatible.
187+
Schemas follow a three-phase lifecycle: stable -> deprecated -> removed. Breaking changes require a new major schema version. Additive changes are backward-compatible.
88188

89189
![Versioning and Deprecation Flow](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/protocol/02-versioning-and-deprecation-flow.svg)
90190

91191
*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.*
92192

93-
---
94-
95-
## Schema Governance and Compatibility
193+
### Schema Governance and Compatibility
96194

97195
All schema changes go through a governance review before landing. The compatibility matrix ensures no existing consumer breaks across patch and minor versions.
98196

99197
![Schema Governance and Compatibility](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/protocol/04-schema-governance-compatibility.svg)
100198

101-
*Governance steps: proposal → impact analysis → compatibility check → reviewer sign-off → merge → changelog entry → docs sync.*
199+
*Governance steps: proposal -> impact analysis -> compatibility check -> reviewer sign-off -> merge -> changelog entry -> docs sync.*
102200

103-
---
104-
105-
## Intent Payload Extensibility
201+
### Intent Payload Extensibility
106202

107-
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.
203+
Intent schemas are typed by `intent_type`. The payload field is a structured JSON object defined per type - not a free-form blob.
108204

109205
![Intent Payload Extensibility and Semantic Schemas](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/intents/09-intent-payload-extensibility-and-semantic-schemas.svg)
110206

111-
*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.*
112-
113-
---
114-
115-
## Public API Error Model
207+
### Public API Error Model
116208

117209
All error responses follow a uniform model: HTTP status + machine-readable error code + retriability hint.
118210

119211
![Public API Error Model and Retriability](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/api/02-error-model-retriability.svg)
120212

121-
*`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.*
122-
123-
---
124-
125-
## Integration Rule
213+
### Integration Rule
126214

127215
A contract family is considered complete only when it is aligned across all five layers:
128216

129-
1. **`axme-spec`** — normative schema definition (this repo)
130-
2. **`axme-docs`** — OpenAPI artifact and narrative documentation
131-
3. **SDK clients** — implemented and tested method in each of the five SDKs
132-
4. **`axme-conformance`** — conformance check covering the contract
133-
5. **Runtime** — `axme-control-plane` behavior matches the schema
134-
135-
---
217+
1. **`axme-spec`** - normative schema definition (this repo)
218+
2. **`axme-docs`** - OpenAPI artifact and narrative documentation
219+
3. **SDK clients** - implemented and tested method in each of the five SDKs
220+
4. **`axme-conformance`** - conformance check covering the contract
221+
5. **Runtime** - `axme-control-plane` behavior matches the schema
136222

137-
## Validation
223+
### Validation
138224

139225
```bash
140226
python -m pip install -e ".[dev]"
141227
python scripts/validate_schemas.py
142228
pytest
143229
```
144230

145-
---
146-
147-
## Related Repositories
148-
149-
| Repository | Relationship |
150-
|---|---|
151-
| [axme-docs](https://github.com/AxmeAI/axme-docs) | Derives OpenAPI artifacts and narrative docs from these schemas |
152-
| [axme-conformance](https://github.com/AxmeAI/axme-conformance) | Validates runtime and SDK behavior against these contracts |
153-
| Control-plane runtime (private) | Runtime implementation must conform to schemas defined here |
154-
| [axme-sdk-python](https://github.com/AxmeAI/axme-sdk-python) | Python client — API surface derived from these contracts |
155-
| [axme-sdk-typescript](https://github.com/AxmeAI/axme-sdk-typescript) | TypeScript client |
156-
| [axme-sdk-go](https://github.com/AxmeAI/axme-sdk-go) | Go client |
157-
| [axme-sdk-java](https://github.com/AxmeAI/axme-sdk-java) | Java client |
158-
| [axme-sdk-dotnet](https://github.com/AxmeAI/axme-sdk-dotnet) | .NET client |
231+
</details>
159232

160233
---
161234

162-
## Contributing & Contact
235+
## Contributing and Contact
163236

164237
- Schema proposals and breaking-change requests: open an issue with label `schema-proposal`
165-
- Quick Start: https://cloud.axme.ai/alpha/cli · Contact: [hello@axme.ai](mailto:hello@axme.ai)
238+
- Quick Start: https://cloud.axme.ai/alpha/cli
239+
- Contact: [hello@axme.ai](mailto:hello@axme.ai)
166240
- Security disclosures: see [SECURITY.md](SECURITY.md)
167241
- Contribution guidelines: [CONTRIBUTING.md](CONTRIBUTING.md)

0 commit comments

Comments
 (0)