diff --git a/README.md b/README.md index 5633117..4ab86bf 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -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 @@ -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= python examples/delivery/stream/python/agent.py @@ -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) | +
+Repo structure, SDK versions, environment variables, related repositories -### 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 @@ -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 -``` +
+ +--- -Contact: hello@axme.ai +[hello@axme.ai](mailto:hello@axme.ai) · [@axme_ai](https://x.com/axme_ai) · [Security](SECURITY.md) · [License](LICENSE)