diff --git a/README.md b/README.md index 255d485..a852afc 100644 --- a/README.md +++ b/README.md @@ -114,7 +114,7 @@ The complete runtime container view — services, databases, queues, and their c ![Container Runtime — C4 Level 2](docs/diagrams/platform/02-container-runtime-c4.svg) -*Gateway, auth service, registry, scheduler, connector runtime, and policy engine run as independent services. Each has a dedicated store; the durable scheduler owns the retry/wakeup loop.* +*Gateway (public REST API), agent-core (workflow engine), auth service, MCP platform (48 JSON-RPC tools), and tool registry run as Cloud Run services sharing a PostgreSQL instance. The scheduler runs on the gateway via internal tick endpoints.* --- @@ -141,12 +141,24 @@ pytest | Document | Description | |---|---| | [`integration-quickstart.md`](docs/integration-quickstart.md) | End-to-end onboarding path for new integrators | -| [`examples-cloud-vs-protocol.md`](docs/examples-cloud-vs-protocol.md) | What works with AXME Cloud vs AXP-only mode | | [`public-api-auth.md`](docs/public-api-auth.md) | Authentication: platform API keys, actor tokens, JWT validation | -| [`security-overview.md`](docs/security-overview.md) | Public security architecture, controls, and enterprise review baseline | -| [`public-api-families-d1-intents-inbox-approvals.md`](docs/public-api-families-d1-intents-inbox-approvals.md) | Full API family reference for intents, inbox, and approvals | +| [`security-overview.md`](docs/security-overview.md) | Security architecture, controls, and enterprise review baseline | | [`supported-limits-and-error-model.md`](docs/supported-limits-and-error-model.md) | Rate limits, quotas, error codes, retriability table | | [`migration-and-deprecation-policy.md`](docs/migration-and-deprecation-policy.md) | API versioning, deprecation timelines, migration guides | +| [`mcp-api-reference.md`](docs/mcp-api-reference.md) | MCP Server — all 48 tools, auth model, response format | +| [`cross-org-receive-policy.md`](docs/cross-org-receive-policy.md) | Cross-org intent delivery: org policy + agent overrides | +| [`agent-addressing.md`](docs/agent-addressing.md) | Agent address registry, agent:// URI scheme | + +### API Family References + +| Document | Scope | +|---|---| +| [`D1 — Intents, Inbox, Approvals`](docs/public-api-families-d1-intents-inbox-approvals.md) | Intent CRUD, SSE, lifecycle events, human tasks | +| [`D2 — Webhooks, Capabilities`](docs/public-api-families-d2-webhooks-capabilities.md) | Webhook subscriptions, deliveries, event types | +| [`D3 — Users`](docs/public-api-families-d3-users.md) | User profiles, nicks, contacts | +| [`D4 — Invites, Media`](docs/public-api-families-d4-invites-media.md) | Invite links, media upload/download | +| [`D5 — Schemas`](docs/public-api-families-d5-schemas.md) | Schema governance, payload validation | +| [`D6 — Enterprise Governance`](docs/public-api-families-d6-enterprise-governance.md) | Orgs, workspaces, members, agents, policies, quotas | --- diff --git a/docs/diagrams/axme-complete-architecture.mmd b/docs/diagrams/axme-complete-architecture.mmd index 189f6a3..4b684f8 100644 --- a/docs/diagrams/axme-complete-architecture.mmd +++ b/docs/diagrams/axme-complete-architecture.mmd @@ -105,7 +105,7 @@ flowchart TB SCHED["Scheduler\nTick loop\nDeadline enforcement\nRetries"]:::service TOOLREG["Tool Registry\nAction catalog\nWorkflow compilation"]:::service POLICY["Policy Engine\nAccess decisions\nConsent checks\nRisk evaluation"]:::service - MCP["MCP Server\nTool access\nData access"]:::service + MCP["MCP Platform\n48 JSON-RPC tools\nMirrors CLI"]:::service end end @@ -129,7 +129,11 @@ flowchart TB ADDR_SCHEME["agent://org_slug/workspace_slug/sa_name"]:::agent ADDR_REGISTRY["Agent Registry"]:::agent ADDR_ROUTING["Routing Engine"]:::agent + ADDR_SEND_POLICY["Send Policy\nallowlist / denylist"]:::agent + ADDR_RECEIVE_POLICY["Receive Policy\norg: open / allowlist / closed\nagent override: allow / block"]:::agent ADDR_SCHEME --> ADDR_REGISTRY --> ADDR_ROUTING + ADDR_REGISTRY --> ADDR_SEND_POLICY + ADDR_REGISTRY --> ADDR_RECEIVE_POLICY end %% ═══════════════════════════════════════════════ @@ -167,6 +171,9 @@ flowchart TB T_QUOTA[("quota_counters")]:::datastore T_TENANT[("tenant_placements")]:::datastore T_AUDIT[("enterprise_admin_audit_events")]:::datastore + T_ADDR_REG[("agent_address_registry")]:::datastore + T_ORG_RCV[("org_receive_policies")]:::datastore + T_AGT_RCV[("agent_receive_overrides")]:::datastore end subgraph PG_WEBHOOK["Webhooks"] @@ -228,7 +235,8 @@ flowchart TB GW --> SCHED GW --> TOOLREG GW --> POLICY - AC --> MCP + CLIENTS --> MCP + MCP --> GW AC --> TOOLREG AC --> POLICY diff --git a/docs/diagrams/axme-complete-architecture.png b/docs/diagrams/axme-complete-architecture.png index 9397ae0..268ba40 100644 Binary files a/docs/diagrams/axme-complete-architecture.png and b/docs/diagrams/axme-complete-architecture.png differ diff --git a/docs/diagrams/axme-complete-architecture.svg b/docs/diagrams/axme-complete-architecture.svg index d83eef7..0481666 100644 --- a/docs/diagrams/axme-complete-architecture.svg +++ b/docs/diagrams/axme-complete-architecture.svg @@ -1 +1 @@ -
SCENARIO BUNDLE
JSON file
axme scenarios apply
Provisions:
agents + routing
workflow + intent
CLI
axme tasks approve
Email
Magic link
Action token 7-day TTL
Form
JSON Schema
Validated submission
Pub/Sub
intent-lifecycle topic
Inbox
gateway_threads
gateway_messages
gateway_thread_members
gateway_thread_events
Enterprise
usage_ledger
quota_counters
tenant_placements
enterprise_admin_audit_events
scheduled_jobs
workflow_runs
pubsub_processed_messages
gateway_webhook_subscriptions
gateway_webhook_events
gateway_webhook_deliveries
gateway_users
gateway_nicks
gateway_invites
human_task_action_tokens
gateway_intents
gateway_intent_events
gateway_idempotency
http_delivery_records
agent://org_slug/workspace_slug/sa_name
Agent Registry
Routing Engine
stream
SSE push
poll
Agent pulls
http
Webhook POST
HMAC signature
inbox
reply_to
internal
agent-core
Scheduler
Tick loop
Deadline enforcement
Retries
Tool Registry
Action catalog
Workflow compilation
Policy Engine
Access decisions
Consent checks
Risk evaluation
MCP Server
Tool access
Data access
Gateway
FastAPI — 85+ endpoints
Public API surface
Agent Core
Workflow orchestration
Step dispatch
Auth Service
JWT issuance
API key validation
AUTHENTICATION
x-api-key: AXME_API_KEY
Service-Account Key
axme_sa_...
Authorization: Bearer
Account Session Token
JWT 15-min TTL
Internal Secrets
GATEWAY_API_KEY
AUTH_API_KEY
AXP INTENT PROTOCOL
Intent Envelope
intent_id | from_agent | to_agent
type | payload | lifecycle_status
Intent Lifecycle
CREATED
SUBMITTED
DELIVERED
IN_PROGRESS
WAITING
COMPLETED
FAILED
CANCELLED
TIMED_OUT
Python SDK
axme-sdk-python
Syntax error in graphmermaid version 8.14.0
\ No newline at end of file +

HUMAN TASK FLOW

DATA LAYER

AGENT ADDRESSING

DELIVERY BINDINGS

AXME CLOUD — Cloud Run Services

CLIENT LAYER

PostgreSQL — 22 Tables

Workflow

Webhooks

User / Identity

Intent Core

Support Services

Core Services

SCENARIO BUNDLE

JSON file

axme scenarios apply

Provisions:
agents + routing
workflow + intent

Enterprise

usage_ledger

quota_counters

tenant_placements

enterprise_admin_audit_events

agent_address_registry

org_receive_policies

agent_receive_overrides

Inbox

gateway_threads

gateway_messages

gateway_thread_members

gateway_thread_events

AUTHENTICATION

x-api-key: AXME_API_KEY
Service-Account Key
axme_sa_...

Authorization: Bearer
Account Session Token
JWT 15-min TTL

Internal Secrets
GATEWAY_API_KEY
AUTH_API_KEY

AXP INTENT PROTOCOL

Intent Lifecycle

CREATED

SUBMITTED

DELIVERED

IN_PROGRESS

WAITING

COMPLETED

FAILED

CANCELLED

TIMED_OUT

Intent Envelope

intent_id | from_agent | to_agent
type | payload | lifecycle_status

CLI: axme

axme login

axme examples

axme scenarios

axme intents

axme tasks

axme agents

Key SDK Methods

listen\(\)

observe\(\)

createIntent\(\)

resumeIntent\(\)

sendIntent\(\)

SDKs

Python SDK
axme-sdk-python

TypeScript SDK
axme-sdk-typescript

Go SDK
axme-sdk-go

Java SDK
axme-sdk-java

.NET SDK
axme-sdk-dotnet

Gateway
FastAPI — 85+ endpoints
Public API surface

Agent Core
Workflow orchestration
Step dispatch

Auth Service
JWT issuance
API key validation

Scheduler
Tick loop
Deadline enforcement
Retries

Tool Registry
Action catalog
Workflow compilation

Policy Engine
Access decisions
Consent checks
Risk evaluation

MCP Platform
48 JSON-RPC tools
Mirrors CLI

stream
SSE push

poll
Agent pulls

http
Webhook POST
HMAC signature

inbox
reply_to

internal
agent-core

agent://org_slug/workspace_slug/sa_name

Agent Registry

Routing Engine

Send Policy
allowlist / denylist

Receive Policy
org: open / allowlist / closed
agent override: allow / block

gateway_intents

gateway_intent_events

gateway_idempotency

http_delivery_records

gateway_users

gateway_nicks

gateway_invites

human_task_action_tokens

gateway_webhook_subscriptions

gateway_webhook_events

gateway_webhook_deliveries

scheduled_jobs

workflow_runs

pubsub_processed_messages

Pub/Sub
intent-lifecycle topic

CLI
axme tasks approve

Email
Magic link
Action token 7-day TTL

Form
JSON Schema
Validated submission

 \ No newline at end of file diff --git a/docs/diagrams/platform/02-container-runtime-c4.mmd b/docs/diagrams/platform/02-container-runtime-c4.mmd index 0fd9d11..4d75fe9 100644 --- a/docs/diagrams/platform/02-container-runtime-c4.mmd +++ b/docs/diagrams/platform/02-container-runtime-c4.mmd @@ -1,12 +1,18 @@ sequenceDiagram autonumber participant C as Client/SDK + participant M as MCP Server
(AI Assistants) participant G as Gateway API - participant W as Workflow Runtime + participant W as Workflow Runtime
(Agent-Core) participant J as Job Scheduler participant D as Data Stores participant R as Recipient Agent + Note over M,G: MCP path (AI assistants via JSON-RPC) + M->>G: proxy tool call → REST API + G-->>M: JSON response → MCP result + + Note over C,G: Direct API path (SDK/CLI) C->>G: API request G->>D: write request/audit envelope G->>W: start or continue workflow diff --git a/docs/diagrams/platform/02-container-runtime-c4.png b/docs/diagrams/platform/02-container-runtime-c4.png index 8d11369..adc962e 100644 Binary files a/docs/diagrams/platform/02-container-runtime-c4.png and b/docs/diagrams/platform/02-container-runtime-c4.png differ diff --git a/docs/diagrams/platform/02-container-runtime-c4.svg b/docs/diagrams/platform/02-container-runtime-c4.svg index 61f677f..b070513 100644 --- a/docs/diagrams/platform/02-container-runtime-c4.svg +++ b/docs/diagrams/platform/02-container-runtime-c4.svg @@ -1,151 +1 @@ - - - - - - -container_runtime - - - -C - -Client / SDK - - - -GW - -Gateway API - - - -C->GW - - - - - -WR - -Workflow Runtime - - - -GW->WR - - - - - -EV - -Event + -Audit Store - - - -GW->EV - - - - - -OBS - -Observability -logs / metrics / traces - - - -GW->OBS - - - - - -DL - -Delivery / -Transport Layer - - - -WR->DL - - - - - -DB - -Intent + -Policy Store - - - -WR->DB - - - - - -WR->EV - - - - - -SJ - -Scheduled Jobs - - - -WR->SJ - - - - - -AG - -Recipient Agents - - - -DL->AG - - - - - -SC - -Internal Scheduler - - - -SC->WR - - -tick due run - - - -SJ->SC - - - - - -AG->GW - - -callbacks - - - +Recipient AgentData StoresJob SchedulerWorkflow Runtime(Agent-Core)Gateway APIMCP Server(AI Assistants)Client/SDKRecipient AgentData StoresJob SchedulerWorkflow Runtime(Agent-Core)Gateway APIMCP Server(AI Assistants)Client/SDKMCP path (AI assistants via JSON-RPC)Direct API path (SDK/CLI)proxy tool call → REST API1JSON response → MCP result2API request3write request/audit envelope4start or continue workflow5deliver step/intent6callback/progress7persist state + events8set next wakeup if waiting9tick due run10latest status11response/read model12 \ No newline at end of file diff --git a/docs/public-api-families-d6-enterprise-governance.md b/docs/public-api-families-d6-enterprise-governance.md index a69157c..c305216 100644 --- a/docs/public-api-families-d6-enterprise-governance.md +++ b/docs/public-api-families-d6-enterprise-governance.md @@ -78,10 +78,22 @@ Enterprise operation groups currently published on `gateway.v1.json`: - agents (agent registry and send policy): - `GET /v1/agents` - `GET /v1/agents/{address}` + - `DELETE /v1/service-accounts/{service_account_id}` + - `PATCH /v1/service-accounts/{service_account_id}/delivery` - `GET /v1/agents/{address}/policy` - `PUT /v1/agents/{address}/policy` - `POST /v1/agents/{address}/policy/entries` - `DELETE /v1/agents/{address}/policy/entries/{entry_id}` +- agents (receive override — per-agent cross-org exceptions): + - `GET /v1/agents/{address}/receive-override` + - `PUT /v1/agents/{address}/receive-override` + - `POST /v1/agents/{address}/receive-override/entries` + - `DELETE /v1/agents/{address}/receive-override/entries/{entry_id}` +- organizations (receive policy — cross-org intent delivery control): + - `GET /v1/organizations/{org_id}/receive-policy` + - `PUT /v1/organizations/{org_id}/receive-policy` + - `POST /v1/organizations/{org_id}/receive-policy/entries` + - `DELETE /v1/organizations/{org_id}/receive-policy/entries/{entry_id}` - naming/routing/transports/deliveries: - `POST /v1/principals` - `GET /v1/principals/{principal_id}`