Skip to content

Redesign README: direct structure, example tables first #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
George-iam merged 2 commits into from
Mar 28, 2026
Merged

Redesign README: direct structure, example tables first #37

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f993842
redesign README: direct structure, remove AXME intro, prioritize exam…
George-iam Mar 28, 2026
d75d2b7
fix: rename axme-spec -> axp-spec across all references
George-iam Mar 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
271 changes: 136 additions & 135 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,80 @@
# AXME Examples

AXME is a coordination infrastructure for durable execution - submit once, track lifecycle, complete later. These examples show every capability in runnable form.
Production-ready examples for the AXME platform - every delivery binding, human approval flow, internal runtime, durability scenario, and multi-agent orchestration. Each example runs in 5 languages: Python, TypeScript, Go, Java, .NET.

Production-ready examples for the AXME platform - all delivery bindings, human approval flows, internal runtime, durability scenarios, and multi-agent orchestration.
[![Alpha](https://img.shields.io/badge/status-alpha-orange)](https://cloud.axme.ai/alpha/cli)
[![License](https://img.shields.io/badge/license-see%20LICENSE-blue)](LICENSE)

Each example is available in **5 languages**: Python, TypeScript, Go, Java, .NET.
[Quick Start](#quick-start) · [axme](https://github.com/AxmeAI/axme) · [Docs](https://github.com/AxmeAI/axme-docs) · [Spec](https://github.com/AxmeAI/axp-spec)

## Related Repositories
---

| Repository | Description |
|------------|-------------|
| [axme](https://github.com/AxmeAI/axme) | Main project and overview |
| [axme-spec](https://github.com/AxmeAI/axme-spec) | Protocol specification |
| [axme-docs](https://github.com/AxmeAI/axme-docs) | Documentation |
| [axme-cli](https://github.com/AxmeAI/axme-cli) | CLI tool |
| [axme-sdk-python](https://github.com/AxmeAI/axme-sdk-python) | Python SDK |
| [axme-sdk-typescript](https://github.com/AxmeAI/axme-sdk-typescript) | TypeScript SDK |
| [axme-sdk-go](https://github.com/AxmeAI/axme-sdk-go) | Go SDK |
| [axme-sdk-java](https://github.com/AxmeAI/axme-sdk-java) | Java SDK |
| [axme-sdk-dotnet](https://github.com/AxmeAI/axme-sdk-dotnet) | .NET SDK |
## Examples

### Delivery Bindings

| Example | Pattern | Agent needed? |
|---------|---------|:------------:|
| `delivery/stream` | SSE persistent connection - real-time delivery | Yes |
| `delivery/poll` | Periodic polling - batch/serverless friendly | Yes |
| `delivery/http` | AXME POSTs to agent's callback URL | Yes (HTTP server) |
| `delivery/inbox` | reply_to inbox - disconnect-safe | Yes |

### Human-in-the-Loop (8 Task Types)

All human task examples send an email with a magic link to a web task page. The page renders task-specific UI based on `task_type`.

| Example | Task type | What the human does |
|---------|-----------|-------------------|
| `human/cli` | `approval` | Approve/reject from CLI (`axme tasks approve`) |
| `human/email` | `approval` | Approve/reject via email magic link |
| `human/form` | `form` | Fill structured form with required fields |
| `human/confirmation` | `confirmation` | Confirm a real-world action was completed |
| `human/assignment` | `assignment` | Assign work to a person (with form fields) |
| `human/review` | `review` | Review and approve, request changes, or reject |
| `human/clarification` | `clarification` | Provide clarification (comment required) |
| `human/manual-action` | `manual_action` | Complete a physical task, attach evidence |
| `human/override` | `override` | Override a policy gate (comment required) |

### Internal Runtime

| Example | What it demonstrates |
|---------|---------------------|
| `internal/delay` | Step deadline (120s) - agent must respond in time |
| `internal/notification` | Built-in notification to service owner |
| `internal/escalation` | Reminders + timeout escalation chain |
| `internal/human_approval` | Pure human gate, no agent (scenario-only) |
| `internal/timeout` | Step timeout demo (scenario-only) |
| `internal/reminder` | Reminder email demo (scenario-only) |

### Durability

| Example | What it demonstrates |
|---------|---------------------|
| `durability/retry-failure` | Delivery retry exhaustion - FAILED |
| `durability/timeout` | Step deadline - TIMED_OUT |
| `durability/reminder-escalation` | Human SLA breach - reminders - escalation |

### Full Workflows

| Example | What it demonstrates |
|---------|---------------------|
| `full/multi-agent` | Compliance check - risk assessment - CAB human approval |
| `full/multi-binding` | SSE + HTTP push in one workflow (scenario-only) |

### Model A (Manual Lifecycle)

| Example | Pattern |
|---------|---------|
| `model-a/simple-request` | Create intent - observe - wait for completion |
| `model-a/fire-and-forget` | Create intent - disconnect - check status later |
| `model-a/manual-multi-step` | Chain 2 agents sequentially via initiator code |

---

## Quick Start

```bash
# 0. Get access - install the CLI and log in
# curl -fsSL https://raw.githubusercontent.com/AxmeAI/axme-cli/main/install.sh | sh
# (open a new terminal after install)
# Contact: hello@axme.ai

# 1. Install the CLI + SDK
pip install axme

Expand All @@ -39,53 +86,9 @@ axme login
axme scenarios apply examples/delivery/stream/scenario.json --watch
```

## Repository Structure
Alpha access: [cloud.axme.ai/alpha/cli](https://cloud.axme.ai/alpha/cli) - Install: `curl -fsSL https://raw.githubusercontent.com/AxmeAI/axme-cli/main/install.sh | sh`

```
axme-examples/
├── examples/
│ ├── delivery/
│ │ ├── stream/ # SSE persistent connection
│ │ ├── poll/ # Periodic polling
│ │ ├── http/ # AXME pushes to callback URL
│ │ └── inbox/ # reply_to inbox pattern
│ ├── human/
│ │ ├── cli/ # CLI approval (axme tasks approve)
│ │ ├── email/ # Email magic link approval
│ │ ├── form/ # Structured form with required fields
│ │ ├── confirmation/ # Confirm real-world action completed
│ │ ├── assignment/ # Assign work to a person or team
│ │ ├── review/ # Code/document review with approve/reject
│ │ ├── clarification/ # Request clarification (comment required)
│ │ ├── manual-action/ # Physical/manual action (evidence required)
│ │ └── override/ # Override policy gate (comment required)
│ ├── internal/
│ │ ├── delay/ # Step deadline enforcement
│ │ ├── notification/ # Owner notification + ack
│ │ ├── escalation/ # Reminder chain + escalation
│ │ ├── human_approval/ # Pure human gate (scenario-only)
│ │ ├── timeout/ # Timeout demo (scenario-only)
│ │ └── reminder/ # Reminder demo (scenario-only)
│ ├── durability/
│ │ ├── retry-failure/ # Delivery retry exhaustion → FAILED
│ │ ├── timeout/ # Step deadline → TIMED_OUT
│ │ └── reminder-escalation/ # Human SLA → reminders → escalation
│ ├── full/
│ │ ├── multi-agent/ # 2 agents + human approval in one workflow
│ │ └── multi-binding/ # SSE + HTTP in one workflow (scenario-only)
│ └── model-a/
│ ├── simple-request/ # Initiator waits for agent response
│ ├── fire-and-forget/ # Send intent, disconnect, check later
│ └── manual-multi-step/ # Chain 2 agents sequentially
├── protocol/ # AXP protocol-only examples (runtime-agnostic)
├── runner/ # Python handler library (used by axme CLI)
├── tests/ # Unit tests for handlers
├── lang/ # Language-specific build configs
│ ├── typescript/ # package.json, tsconfig.json
│ ├── java/ # pom.xml, SseHelper.java
│ └── dotnet/ # AxmeExamples.csproj, SseHelper.cs
└── docs/ # Supporting documentation
```
---

## Per-Example Layout

Expand All @@ -102,14 +105,14 @@ examples/delivery/stream/
└── dotnet/StreamAgent.cs # .NET (dotnet run)
```

---

## Running Examples

### Model B - ScenarioBundle (recommended)

Model B uses a declarative `scenario.json` file that the CLI provisions end-to-end: agents, intents, and lifecycle - no manual API calls needed.

Most examples use `scenario.json` + the AXME CLI:

```bash
# Step 1: Provision agents + submit intent + watch lifecycle
axme scenarios apply examples/delivery/stream/scenario.json --watch
Expand All @@ -136,8 +139,6 @@ cd lang/dotnet && dotnet run -p:ExampleClass=AxmeExamples.Delivery.StreamAgent

Model A gives you full programmatic control - your code creates intents, manages agents, and handles lifecycle directly via the SDK.

Model A examples use the SDK directly - the initiator creates intents via API:

```bash
# Start agent
AXME_API_KEY=<agent-key> python examples/delivery/stream/python/agent.py
Expand All @@ -148,66 +149,58 @@ AXME_TO_AGENT=agent://org/workspace/compliance-checker-agent \
python examples/model-a/simple-request/python/initiator.py
```

## Examples

### Delivery Bindings

| Example | Pattern | Agent needed? |
|---------|---------|:------------:|
| `delivery/stream` | SSE persistent connection - real-time delivery | Yes |
| `delivery/poll` | Periodic polling - batch/serverless friendly | Yes |
| `delivery/http` | AXME POSTs to agent's callback URL | Yes (HTTP server) |
| `delivery/inbox` | reply_to inbox - disconnect-safe | Yes |

### Human-in-the-Loop (8 Task Types)

All human task examples send an email with a magic link to a web task page. The page renders task-specific UI based on `task_type`.

| Example | Task type | What the human does |
|---------|-----------|-------------------|
| `human/cli` | `approval` | Approve/reject from CLI (`axme tasks approve`) |
| `human/email` | `approval` | Approve/reject via email magic link |
| `human/form` | `form` | Fill structured form with required fields |
| `human/confirmation` | `confirmation` | Confirm a real-world action was completed |
| `human/assignment` | `assignment` | Assign work to a person (with form fields) |
| `human/review` | `review` | Review and approve, request changes, or reject |
| `human/clarification` | `clarification` | Provide clarification (comment required) |
| `human/manual-action` | `manual_action` | Complete a physical task, attach evidence |
| `human/override` | `override` | Override a policy gate (comment required) |

### Internal Runtime

| Example | What it demonstrates |
|---------|---------------------|
| `internal/delay` | Step deadline (120s) - agent must respond in time |
| `internal/notification` | Built-in notification to service owner |
| `internal/escalation` | Reminders + timeout escalation chain |
| `internal/human_approval` | Pure human gate, no agent (scenario-only) |
| `internal/timeout` | Step timeout demo (scenario-only) |
| `internal/reminder` | Reminder email demo (scenario-only) |

### Durability

| Example | What it demonstrates |
|---------|---------------------|
| `durability/retry-failure` | Delivery retry exhaustion → FAILED |
| `durability/timeout` | Step deadline → TIMED_OUT |
| `durability/reminder-escalation` | Human SLA breach → reminders → escalation |

### Full Workflows
---

| Example | What it demonstrates |
|---------|---------------------|
| `full/multi-agent` | Compliance check → risk assessment → CAB human approval |
| `full/multi-binding` | SSE + HTTP push in one workflow (scenario-only) |
<details>
<summary>Repo structure, SDK versions, environment variables, related repositories</summary>

### Model A (Manual Lifecycle)
## Repository Structure

| Example | Pattern |
|---------|---------|
| `model-a/simple-request` | Create intent → observe → wait for completion |
| `model-a/fire-and-forget` | Create intent → disconnect → check status later |
| `model-a/manual-multi-step` | Chain 2 agents sequentially via initiator code |
```
axme-examples/
├── examples/
│ ├── delivery/
│ │ ├── stream/ # SSE persistent connection
│ │ ├── poll/ # Periodic polling
│ │ ├── http/ # AXME pushes to callback URL
│ │ └── inbox/ # reply_to inbox pattern
│ ├── human/
│ │ ├── cli/ # CLI approval (axme tasks approve)
│ │ ├── email/ # Email magic link approval
│ │ ├── form/ # Structured form with required fields
│ │ ├── confirmation/ # Confirm real-world action completed
│ │ ├── assignment/ # Assign work to a person or team
│ │ ├── review/ # Code/document review with approve/reject
│ │ ├── clarification/ # Request clarification (comment required)
│ │ ├── manual-action/ # Physical/manual action (evidence required)
│ │ └── override/ # Override policy gate (comment required)
│ ├── internal/
│ │ ├── delay/ # Step deadline enforcement
│ │ ├── notification/ # Owner notification + ack
│ │ ├── escalation/ # Reminder chain + escalation
│ │ ├── human_approval/ # Pure human gate (scenario-only)
│ │ ├── timeout/ # Timeout demo (scenario-only)
│ │ └── reminder/ # Reminder demo (scenario-only)
│ ├── durability/
│ │ ├── retry-failure/ # Delivery retry exhaustion - FAILED
│ │ ├── timeout/ # Step deadline - TIMED_OUT
│ │ └── reminder-escalation/ # Human SLA - reminders - escalation
│ ├── full/
│ │ ├── multi-agent/ # 2 agents + human approval in one workflow
│ │ └── multi-binding/ # SSE + HTTP in one workflow (scenario-only)
│ └── model-a/
│ ├── simple-request/ # Initiator waits for agent response
│ ├── fire-and-forget/ # Send intent, disconnect, check later
│ └── manual-multi-step/ # Chain 2 agents sequentially
├── protocol/ # AXP protocol-only examples (runtime-agnostic)
├── runner/ # Python handler library (used by axme CLI)
├── tests/ # Unit tests for handlers
├── lang/ # Language-specific build configs
│ ├── typescript/ # package.json, tsconfig.json
│ ├── java/ # pom.xml, SseHelper.java
│ └── dotnet/ # AxmeExamples.csproj, SseHelper.cs
└── docs/ # Supporting documentation
```

## SDK Versions

Expand All @@ -230,14 +223,22 @@ All examples use AXME SDK v0.1.2:
| `AXME_AGENT_ADDRESS` | No | Agent address (bare name or full `agent://...`) |
| `AXME_CLI_SECRET_STORAGE` | No | Set to `file` for headless/CI environments (default: OS keychain) |

## Alpha Access
## Related Repositories

Install the CLI and log in:
| Repository | Description |
|------------|-------------|
| [axme](https://github.com/AxmeAI/axme) | Main project and overview |
| [axp-spec](https://github.com/AxmeAI/axp-spec) | Protocol specification |
| [axme-docs](https://github.com/AxmeAI/axme-docs) | Documentation |
| [axme-cli](https://github.com/AxmeAI/axme-cli) | CLI tool |
| [axme-sdk-python](https://github.com/AxmeAI/axme-sdk-python) | Python SDK |
| [axme-sdk-typescript](https://github.com/AxmeAI/axme-sdk-typescript) | TypeScript SDK |
| [axme-sdk-go](https://github.com/AxmeAI/axme-sdk-go) | Go SDK |
| [axme-sdk-java](https://github.com/AxmeAI/axme-sdk-java) | Java SDK |
| [axme-sdk-dotnet](https://github.com/AxmeAI/axme-sdk-dotnet) | .NET SDK |

```bash
curl -fsSL https://raw.githubusercontent.com/AxmeAI/axme-cli/main/install.sh | sh
# Open a new terminal after install
axme login
```
</details>

---

Contact: hello@axme.ai
[hello@axme.ai](mailto:hello@axme.ai) · [@axme_ai](https://x.com/axme_ai) · [Security](SECURITY.md) · [License](LICENSE)
Loading