From f29d8a91bef16869022feffab6a38cead3bfdd94 Mon Sep 17 00:00:00 2001 From: geobelsky Date: Wed, 25 Mar 2026 13:26:38 +0000 Subject: [PATCH] docs: add protocol concepts to README - delivery bindings, runtime steps, human task types, ScenarioBundle Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 216 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 145 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index cf7b65a..0e0d066 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # axme-spec -**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. +**Canonical AXME protocol and public API schema repository.** 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](mailto:hello@axme.ai) +> **Alpha** - Protocol and API surface are stabilizing. Not recommended for production workloads yet. +> Feedback and schema proposals welcome -> [hello@axme.ai](mailto:hello@axme.ai) --- @@ -11,42 +11,134 @@ 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. +It provides a model for executing **intents** - requests that may take minutes, hours, or longer to complete - across services, agents, and human participants. -## AXP — the Intent Protocol +Durable execution where agents, services, and humans coordinate as equals. -At the core of AXME is **AXP (Intent Protocol)** — an open protocol that defines contracts and lifecycle rules for intent processing. +## AXP - the Intent Protocol + +At the core of AXME is **AXP (Intent Protocol)** - an open protocol that defines contracts and lifecycle rules for intent processing. + +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. -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 +- the protocol specification and schemas (this repo) +- [SDKs](https://github.com/AxmeAI/axme-sdk-python) and [CLI](https://github.com/AxmeAI/axme-cli) for integration +- [conformance tests](https://github.com/AxmeAI/axme-conformance) +- [implementation and integration documentation](https://github.com/AxmeAI/axme-docs) + +## 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: + +| Binding | How it works | Use case | +|---|---|---| +| **stream** | SSE persistent connection - agent stays connected, intents pushed in real-time | Low-latency, always-on agents | +| **poll** | Agent pulls on its own schedule via `GET /v1/intents?status=pending` | Batch processing, cron jobs | +| **http** | Platform pushes to agent's URL (webhook with HMAC signature) | Serverless functions, existing APIs | +| **inbox** | Human-facing task queue - tasks appear in CLI (`axme tasks list`) or email | Human-in-the-loop workflows | +| **internal** | Runs inside the platform runtime - no external agent needed | Timeouts, reminders, approvals | + +## Runtime Steps + +### Internal steps (no agent needed) + +These run inside the AXME runtime without any external agent: + +| Step | What it does | +|---|---| +| **human_approval** | Pause workflow, wait for human to approve/reject via CLI, email magic link, or web form | +| **timeout** | Fail the intent if not completed within a deadline | +| **reminder** | Send a reminder after N seconds of waiting | +| **delay** | Pause workflow for a fixed duration before continuing | +| **escalation** | Chain of reminders with increasing urgency | +| **notification** | Send a one-way notification (email, webhook) without waiting | + +### Human task types + +Eight structured task types for human-in-the-loop workflows: + +| Type | Purpose | +|---|---| +| **approval** | Yes/no gate - deploys, budgets, agent actions | +| **form** | Structured input with required fields - config, onboarding data | +| **review** | Approve, request changes, or reject with comments - code review, document sign-off | +| **override** | Bypass a policy gate with mandatory justification (audit-logged) | +| **confirmation** | Confirm a real-world action was completed - deployment verified, payment sent | +| **assignment** | Route work to a person or team with structured fields | +| **clarification** | Request missing context - comment required before proceeding | +| **manual_action** | Complete a physical task and attach evidence - hardware swap, site inspection | + +## ScenarioBundle + +The simplest way to run a workflow - one JSON file: + +```json +{ + "agents": [{"address": "my-service", "delivery_mode": "stream"}], + "workflow": {"steps": [{"step_id": "process", "assigned_to": "my-service"}]}, + "intent": {"type": "task.v1", "payload": {"data": "..."}} +} +``` + +```bash +axme scenarios apply scenario.json --watch +``` + +This provisions agents, compiles the workflow, submits the intent, and streams lifecycle events - all in one command. ## AXME Cloud **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 +- Human approval, timeouts, reminders, escalation - built in +- Observability of intent status and execution history -- 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 +Quick start: [cloud.axme.ai/alpha/cli](https://cloud.axme.ai/alpha/cli) -State and events can be accessed through: +--- -- API and SDKs -- event streams and webhooks -- the cloud console +## 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. + +![AXP Protocol Envelope](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/protocol/01-protocol-envelope.svg) + +*Each field in the envelope is normatively defined here. The runtime and all SDKs must conform to these field names, types, and validation rules.* --- ## What Lives Here -`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` 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/ @@ -72,69 +164,63 @@ axme-spec/ --- -## 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. - -![AXP Protocol Envelope](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/protocol/01-protocol-envelope.svg) +## Related Repositories -*Each field in the envelope is normatively defined here. The runtime and all SDKs must conform to these field names, types, and validation rules.* +| Repository | Relationship | +|---|---| +| [axme-docs](https://github.com/AxmeAI/axme-docs) | Derives OpenAPI artifacts and narrative docs from these schemas | +| [axme-conformance](https://github.com/AxmeAI/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](https://github.com/AxmeAI/axme-sdk-python) | Python client - API surface derived from these contracts | +| [axme-sdk-typescript](https://github.com/AxmeAI/axme-sdk-typescript) | TypeScript client | +| [axme-sdk-go](https://github.com/AxmeAI/axme-sdk-go) | Go client | +| [axme-sdk-java](https://github.com/AxmeAI/axme-sdk-java) | Java client | +| [axme-sdk-dotnet](https://github.com/AxmeAI/axme-sdk-dotnet) | .NET client | --- -## Schema Versioning and Deprecation +
+Schema Governance (for contributors) + +### Schema Versioning and Deprecation -Schemas follow a three-phase lifecycle: stable → deprecated → removed. Breaking changes require a new major schema version. Additive changes are backward-compatible. +Schemas follow a three-phase lifecycle: stable -> deprecated -> removed. Breaking changes require a new major schema version. Additive changes are backward-compatible. ![Versioning and Deprecation Flow](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/protocol/02-versioning-and-deprecation-flow.svg) *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.* ---- - -## Schema Governance and Compatibility +### Schema Governance and Compatibility All schema changes go through a governance review before landing. The compatibility matrix ensures no existing consumer breaks across patch and minor versions. ![Schema Governance and Compatibility](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/protocol/04-schema-governance-compatibility.svg) -*Governance steps: proposal → impact analysis → compatibility check → reviewer sign-off → merge → changelog entry → docs sync.* +*Governance steps: proposal -> impact analysis -> compatibility check -> reviewer sign-off -> merge -> changelog entry -> docs sync.* ---- - -## Intent Payload Extensibility +### Intent Payload Extensibility -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. +Intent schemas are typed by `intent_type`. The payload field is a structured JSON object defined per type - not a free-form blob. ![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) -*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.* - ---- - -## Public API Error Model +### Public API Error Model All error responses follow a uniform model: HTTP status + machine-readable error code + retriability hint. ![Public API Error Model and Retriability](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/api/02-error-model-retriability.svg) -*`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.* - ---- - -## Integration Rule +### Integration Rule A contract family is considered complete only when it is aligned across all five layers: -1. **`axme-spec`** — normative schema definition (this repo) -2. **`axme-docs`** — OpenAPI artifact and narrative documentation -3. **SDK clients** — implemented and tested method in each of the five SDKs -4. **`axme-conformance`** — conformance check covering the contract -5. **Runtime** — `axme-control-plane` behavior matches the schema - ---- +1. **`axme-spec`** - normative schema definition (this repo) +2. **`axme-docs`** - OpenAPI artifact and narrative documentation +3. **SDK clients** - implemented and tested method in each of the five SDKs +4. **`axme-conformance`** - conformance check covering the contract +5. **Runtime** - `axme-control-plane` behavior matches the schema -## Validation +### Validation ```bash python -m pip install -e ".[dev]" @@ -142,26 +228,14 @@ python scripts/validate_schemas.py pytest ``` ---- - -## Related Repositories - -| Repository | Relationship | -|---|---| -| [axme-docs](https://github.com/AxmeAI/axme-docs) | Derives OpenAPI artifacts and narrative docs from these schemas | -| [axme-conformance](https://github.com/AxmeAI/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](https://github.com/AxmeAI/axme-sdk-python) | Python client — API surface derived from these contracts | -| [axme-sdk-typescript](https://github.com/AxmeAI/axme-sdk-typescript) | TypeScript client | -| [axme-sdk-go](https://github.com/AxmeAI/axme-sdk-go) | Go client | -| [axme-sdk-java](https://github.com/AxmeAI/axme-sdk-java) | Java client | -| [axme-sdk-dotnet](https://github.com/AxmeAI/axme-sdk-dotnet) | .NET client | +
--- -## Contributing & Contact +## Contributing and Contact - 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](mailto:hello@axme.ai) +- Quick Start: https://cloud.axme.ai/alpha/cli +- Contact: [hello@axme.ai](mailto:hello@axme.ai) - Security disclosures: see [SECURITY.md](SECURITY.md) - Contribution guidelines: [CONTRIBUTING.md](CONTRIBUTING.md)