diff --git a/README.md b/README.md index a4c2b71..ad7ed46 100644 --- a/README.md +++ b/README.md @@ -1,71 +1,15 @@ # axme-sdk-java -**Official Java SDK for the AXME platform.** Send and manage intents, poll lifecycle events and history, handle approvals, and access the enterprise admin surface — built for Java 11+, with clean exception types and request/response maps. +**Java SDK for AXME** - send intents, poll for deliveries, resume workflows. Java 11+, clean exception hierarchy, no third-party HTTP dependencies. -> **Alpha** · API surface is stabilizing. Not recommended for production workloads yet. -> **Alpha** — install CLI, log in, run your first example in under 5 minutes. [Quick Start](https://cloud.axme.ai/alpha/cli) · [hello@axme.ai](mailto:hello@axme.ai) +[![Alpha](https://img.shields.io/badge/status-alpha-orange)](https://cloud.axme.ai/alpha/cli) [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE) ---- - -## What Is AXME? - -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. - -## 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 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 - -## 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 -- handling of timeouts, waits, reminders, and escalation -- observability of intent status and execution history - -State and events can be accessed through: - -- API and SDKs -- event streams and webhooks -- the cloud console - ---- - -## What You Can Do With This SDK - -- **Send intents** — create typed, durable actions with delivery guarantees -- **Poll lifecycle events** — retrieve real-time state events and intent history via `listIntentEvents` -- **Approve or reject** — handle human-in-the-loop steps from Java services -- **Control workflows** — pause, resume, cancel, update retry policies and reminders -- **Administer** — manage organizations, workspaces, service accounts, and grants +**[Quick Start](https://cloud.axme.ai/alpha/cli)** · **[Docs](https://github.com/AxmeAI/axme-docs)** · **[Examples](https://github.com/AxmeAI/axme-examples)** --- ## Install -Build and install from source (local Maven repository): - -```bash -git clone https://github.com/AxmeAI/axme-sdk-java.git -cd axme-sdk-java -mvn -q -DskipTests install -``` - -Then add to your `pom.xml`: - ```xml ai.axme @@ -74,11 +18,16 @@ Then add to your `pom.xml`: ``` -Maven Central publication target: `ai.axme:axme`. +Maven Central publication is in progress. Build locally until then: + +```bash +git clone https://github.com/AxmeAI/axme-sdk-java.git +cd axme-sdk-java && mvn -q -DskipTests install +``` --- -## Quickstart +## Quick Start ```java import dev.axme.sdk.AxmeClient; @@ -86,324 +35,58 @@ import dev.axme.sdk.AxmeClientConfig; import dev.axme.sdk.RequestOptions; import java.util.Map; -public class Quickstart { - public static void main(String[] args) throws Exception { - AxmeClient client = new AxmeClient( - AxmeClientConfig.forCloud( - "AXME_API_KEY", // sent as x-api-key - "OPTIONAL_USER_OR_SESSION_TOKEN" // sent as Authorization: Bearer - ) - ); - // Optional override for staging/dev: - // AxmeClientConfig cfg = new AxmeClientConfig("https://staging-api.cloud.axme.ai", "AXME_API_KEY"); - - // Check connectivity / discover available capabilities - System.out.println(client.getCapabilities(RequestOptions.none())); - - // Send an intent to a registered agent address - Map intent = client.createIntent( - Map.of( - "intent_type", "order.fulfillment.v1", - "to_agent", "agent://acme-corp/production/fulfillment-service", - "payload", Map.of("order_id", "ord_123", "priority", "high") - ), - new RequestOptions("fulfill-ord-123-001", null) - ); - System.out.println(intent.get("intent_id") + " " + intent.get("status")); - - // List registered agent addresses - Map agents = client.listAgents("acme-corp-uuid", "prod-ws-uuid", null, RequestOptions.none()); - System.out.println(agents.get("agents")); - } -} -``` - ---- - -## Minimal Language-Native Example - -Short basic submit/get example: - -- [`examples/BasicSubmit.java`](examples/BasicSubmit.java) - -Run (after SDK build/install): - -```bash -export AXME_API_KEY="axme_sa_..." -# compile/run according to your app setup, reusing examples/BasicSubmit.java -``` - -Full runnable scenario set lives in: - -- Cloud: -- Protocol-only: - ---- - -## API Method Families - -The SDK covers the full public API surface: - -![API Method Family Map](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/api/01-api-method-family-map.svg) - -*D1 families (intents, inbox, approvals) are the core integration path. D2 adds schemas, webhooks, and media. D3 covers enterprise admin. The Java SDK implements all three tiers.* - ---- - -## Pagination and Cursor Flows - -Cursor-based list endpoints are available for inbox change streams: - -![Pagination, Filtering, and Sorting Patterns](https://raw.githubusercontent.com/AxmeAI/axme-docs/main/docs/diagrams/api/03-pagination-filtering-sorting-patterns.svg) - -*All list methods return a `cursor` field for the next page. Pass it as `after` in the next call. Filter and sort parameters are typed per endpoint.* - -```java -// Paginate through inbox changes -Map page = client.listInboxChanges( - "agent://manager", - null, - 50, - RequestOptions.none() +AxmeClient client = new AxmeClient( + AxmeClientConfig.forCloud("axme_sa_...", null) ); -while (page.get("cursor") != null) { - page = client.listInboxChanges( - "agent://manager", - (String) page.get("cursor"), - 50, - RequestOptions.none() - ); -} -``` - ---- - -## Human-in-the-Loop (8 Task Types) - -AXME supports 8 human task types. Each pauses the workflow and notifies a human via email with a link to a web task page. - -| Task type | Use case | Default outcomes | -|-----------|----------|-----------------| -| `approval` | Approve or reject a request | approved, rejected | -| `confirmation` | Confirm a real-world action completed | confirmed, denied | -| `review` | Review content with multiple outcomes | approved, changes_requested, rejected | -| `assignment` | Assign work to a person or team | assigned, declined | -| `form` | Collect structured data via form fields | submitted | -| `clarification` | Request clarification (comment required) | provided, declined | -| `manual_action` | Physical task completion (evidence required) | completed, failed | -| `override` | Override a policy gate (comment required) | override_approved, rejected | - -```java -// Create an intent with a human task step -var result = client.createIntent(CreateIntentParams.builder() - .intentType("intent.budget.approval.v1") - .toAgent("agent://agent_core") - .payload(Map.of("amount", 32000, "department", "engineering")) - .humanTask(HumanTask.builder() - .title("Approve Q3 budget") - .description("Review and approve the Q3 infrastructure budget.") - .taskType("approval") - .notifyEmail("approver@example.com") - .allowedOutcomes(List.of("approved", "rejected")) - .build()) - .build()); -``` - -Task types with forms use `form_schema` to define required fields: - -```java -HumanTask.builder() - .title("Assign incident commander") - .taskType("assignment") - .notifyEmail("oncall@example.com") - .formSchema(Map.of( - "type", "object", - "required", List.of("assignee"), - "properties", Map.of( - "assignee", Map.of("type", "string", "title", "Commander name"), - "priority", Map.of("type", "string", "enum", List.of("P1", "P2", "P3")) - ) - )) - .build() -``` - -### Programmatic approvals (inbox API) - -```java -Map inbox = client.listInbox("agent://manager", RequestOptions.none()); - -for (Object item : (List) inbox.get("items")) { - Map entry = (Map) item; - Map action = (Map) entry.get("action"); - if (action == null || action.get("approval_id") == null) { - continue; - } - client.decideApproval( - (String) action.get("approval_id"), - Map.of("decision", "approve", "reason", "Reviewed and approved"), - RequestOptions.none() - ); -} -``` - ---- - -## Intents - -```java -Map created = client.createIntent( +// Send an intent - survives crashes, retries, timeouts +Map intent = client.createIntent( Map.of( "intent_type", "order.fulfillment.v1", - "owner_agent", "agent://fulfillment-service", - "payload", Map.of("order_id", "ord_123") + "to_agent", "agent://myorg/production/fulfillment-service", + "payload", Map.of("order_id", "ord_123") ), - new RequestOptions("intent-ord-123", null) -); - -String intentId = (String) created.get("intent_id"); - -Map current = client.getIntent(intentId, RequestOptions.none()); -Map events = client.listIntentEvents(intentId, null, RequestOptions.none()); -``` - ---- - -## Enterprise Admin APIs - -The Java SDK includes the full service-account lifecycle surface: - -```java -// Create a service account -Map sa = client.createServiceAccount( - Map.of("name", "ci-runner", "org_id", "org_abc"), - new RequestOptions("sa-ci-runner-001", null) -); - -// Issue a key -Map key = client.createServiceAccountKey( - (String) sa.get("id"), - Map.of(), - new RequestOptions(null, null) -); - -// List service accounts -client.listServiceAccounts("org_abc", "", RequestOptions.none()); - -// Revoke a key -client.revokeServiceAccountKey( - (String) sa.get("id"), - (String) key.get("key_id"), - RequestOptions.none() + new RequestOptions("fulfill-ord-123-001", null) ); +System.out.println(intent.get("intent_id") + " " + intent.get("status")); ``` -Available methods: -- `createServiceAccount` / `listServiceAccounts` / `getServiceAccount` -- `createServiceAccountKey` / `revokeServiceAccountKey` - --- -## Nick and Identity Registry +## Human Approvals ```java -Map registered = client.registerNick( - Map.of("nick", "@partner.user", "display_name", "Partner User"), - new RequestOptions("nick-register-001", null) -); - -Map check = client.checkNick("@partner.user", RequestOptions.none()); - -Map renamed = client.renameNick( - Map.of("owner_agent", registered.get("owner_agent"), "nick", "@partner.new"), - new RequestOptions("nick-rename-001", null) -); - -Map profile = client.getUserProfile( - (String) registered.get("owner_agent"), - RequestOptions.none() -); +var result = client.createIntent(Map.of( + "intent_type", "intent.budget.approval.v1", + "to_agent", "agent://myorg/prod/agent_core", + "payload", Map.of("amount", 32000), + "human_task", Map.of( + "task_type", "approval", + "notify_email", "approver@example.com", + "allowed_outcomes", List.of("approved", "rejected") + ) +), new RequestOptions(null, null)); ``` ---- - -## Cross-Org Delivery Control - -Organizations can control which external orgs may send intents to their agents: - -1. **Org receive policy** — org-wide default (`open`, `allowlist`, `closed`) -2. **Agent receive override** — per-agent exceptions to the org policy - -```java -// Get org receive policy -var policy = client.get("/v1/organizations/" + orgId + "/receive-policy"); - -// Set to allowlist mode -client.put("/v1/organizations/" + orgId + "/receive-policy", - Map.of("mode", "allowlist", "allowlist", List.of("org_id_of_trusted_partner"))); - -// Per-agent override -client.put("/v1/agents/" + address + "/receive-override", - Map.of("override_type", "allow", "source_org_id", "org_id_of_partner")); -``` - -See [`cross-org-receive-policy.md`](https://github.com/AxmeAI/axme-docs/blob/main/docs/cross-org-receive-policy.md) for the full decision flow. +8 task types: `approval`, `confirmation`, `review`, `assignment`, `form`, `clarification`, `manual_action`, `override`. Full reference: [axme-docs](https://github.com/AxmeAI/axme-docs). --- -## MCP (Model Context Protocol) - -The Java SDK includes a built-in MCP endpoint client for gateway-hosted MCP sessions. +## Observe Lifecycle Events ```java -// Initialize an MCP session -Map init = client.mcpInitialize(RequestOptions.defaults()); -System.out.println(init.get("serverInfo")); - -// List available tools -Map tools = client.mcpListTools(RequestOptions.defaults()); -List toolList = (List) tools.get("tools"); -for (Object tool : toolList) { - Map t = (Map) tool; - System.out.println(t.get("name")); -} - -// Call a tool -Map result = client.mcpCallTool( - "create_intent", - Map.of( - "intent_type", "order.fulfillment.v1", - "payload", Map.of("order_id", "ord_123"), - "owner_agent", "agent://fulfillment-service" - ), - RequestOptions.defaults() -); -System.out.println(result); +Map events = client.listIntentEvents(intentId, null, RequestOptions.none()); ``` -By default the SDK posts to `/mcp`. Override with `mcpEndpointPath` in client options. - --- -## Repository Structure +## Examples -``` -axme-sdk-java/ -├── src/ -│ ├── main/java/dev/axme/sdk/ -│ │ ├── AxmeClient.java # All API methods -│ │ ├── AxmeClientConfig.java # Configuration -│ │ ├── RequestOptions.java # Idempotency key and correlation ID -│ │ └── AxmeAPIException.java # Typed exception -│ └── test/ # JUnit test suite -├── examples/ -│ └── BasicSubmit.java # Minimal language-native quickstart -└── docs/ -``` +See [`examples/BasicSubmit.java`](examples/BasicSubmit.java). More: [axme-examples](https://github.com/AxmeAI/axme-examples) --- -## Tests +## Development ```bash mvn test @@ -411,24 +94,16 @@ mvn test --- -## Related Repositories +## Related -| Repository | Role | +| | | |---|---| -| [axme-docs](https://github.com/AxmeAI/axme-docs) | Full API reference and integration guides | -| [axme-spec](https://github.com/AxmeAI/axme-spec) | Schema contracts this SDK implements | -| [axme-conformance](https://github.com/AxmeAI/axme-conformance) | Conformance suite that validates this SDK | -| [axme-examples](https://github.com/AxmeAI/axme-examples) | Runnable examples using this SDK | -| [axme-sdk-python](https://github.com/AxmeAI/axme-sdk-python) | Python equivalent | -| [axme-sdk-typescript](https://github.com/AxmeAI/axme-sdk-typescript) | TypeScript equivalent | -| [axme-sdk-go](https://github.com/AxmeAI/axme-sdk-go) | Go equivalent | -| [axme-sdk-dotnet](https://github.com/AxmeAI/axme-sdk-dotnet) | .NET equivalent | +| [axme-docs](https://github.com/AxmeAI/axme-docs) | API reference and integration guides | +| [axme-examples](https://github.com/AxmeAI/axme-examples) | Runnable examples | +| [axp-spec](https://github.com/AxmeAI/axp-spec) | Protocol specification | +| [axme-cli](https://github.com/AxmeAI/axme-cli) | CLI tool | +| [axme-conformance](https://github.com/AxmeAI/axme-conformance) | Conformance suite | --- -## Contributing & Contact - -- Bug reports and feature requests: open an issue in this repository -- 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) +[hello@axme.ai](mailto:hello@axme.ai) · [Security](SECURITY.md) · [License](LICENSE)