diff --git a/docs/diagrams/axme-complete-architecture.svg b/docs/diagrams/axme-complete-architecture.svg index 0481666..f1aa0ab 100644 --- a/docs/diagrams/axme-complete-architecture.svg +++ b/docs/diagrams/axme-complete-architecture.svg @@ -1 +1 @@ -

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 +

HUMAN TASK FLOW

DATA LAYER

AGENT ADDRESSING

DELIVERY BINDINGS

AXME CLOUD — Cloud Run Services

CLIENT LAYER

PostgreSQL — 22 Tables

Webhooks

User / Identity

Infrastructure

Support Services

Core Services

OIDC HTTP

proxy REST

dispatch step intents

publish intent.created

push subscription

publish lifecycle events

push TIMEOUT/REMINDER

tick + maintenance

SCENARIO BUNDLE

JSON file

axme scenarios apply

Provisions:
agents + routing
workflow + intent

Workflow

scheduled_jobs

workflow_runs

pubsub_processed_messages

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

Intent Core

gateway_intents

gateway_intent_events

gateway_idempotency

http_delivery_records

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
Sync: INSERT + COMMIT + Pub/Sub → 200
Admin: /admin/probes/*, /admin/maintenance/*

Gateway Worker
Background processing
Pub/Sub push receiver
Lifecycle, threads, webhooks, jobs

Agent Core
Workflow DAG engine
Step dispatch + lifecycle

Auth Service
JWT issuance
API key validation

Tool Registry
Action catalog
Workflow compilation

Policy Engine
Access decisions
Consent checks

MCP Platform
48 JSON-RPC tools
Proxy to Gateway REST
No DB access

Cloud Tasks
axme-timeout-jobs (50/s)
axme-reminder-jobs (20/s)
Push to Worker (OIDC)

Cloud Scheduler
workflow-tick + webhook-tick (1 min)
daily-cleanup + weekly-vacuum
All with OIDC auth

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_users

gateway_nicks

gateway_invites

human_task_action_tokens

gateway_webhook_subscriptions

gateway_webhook_events

gateway_webhook_deliveries

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 4d75fe9..d71ea19 100644 --- a/docs/diagrams/platform/02-container-runtime-c4.mmd +++ b/docs/diagrams/platform/02-container-runtime-c4.mmd @@ -2,24 +2,32 @@ sequenceDiagram autonumber participant C as Client/SDK participant M as MCP Server
(AI Assistants) - participant G as Gateway API - participant W as Workflow Runtime
(Agent-Core) - participant J as Job Scheduler - participant D as Data Stores + participant G as Gateway API
(FastAPI, async) + participant A as Auth Service
(JWT, OTP) + participant AC as Agent-Core
(Workflow DAG) + participant W as Worker
(Pub/Sub + Cloud Tasks) + participant D as PostgreSQL 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 + 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 - W->>R: deliver step/intent - R-->>W: callback/progress - W->>D: persist state + events - W->>J: set next wakeup if waiting - J-->>W: tick due run - W-->>G: latest status + G->>A: validate x-api-key + Bearer token + A-->>G: auth result + G->>D: write intent + audit envelope + G->>AC: start or continue workflow + AC->>R: deliver step/intent (SSE/http/poll) + R-->>AC: callback/progress + AC->>D: persist state + events + + Note over W,AC: Async pipeline (Pub/Sub + Cloud Tasks) + G->>W: publish intent.created (Pub/Sub) + W->>AC: lifecycle events + W->>D: persist step state + W-->>W: Cloud Tasks: timeout + reminder jobs + W-->>AC: tick due run (scheduled wakeup) + AC-->>G: latest status G-->>C: response/read model diff --git a/docs/diagrams/platform/02-container-runtime-c4.svg b/docs/diagrams/platform/02-container-runtime-c4.svg index b070513..997c61e 100644 --- a/docs/diagrams/platform/02-container-runtime-c4.svg +++ b/docs/diagrams/platform/02-container-runtime-c4.svg @@ -1 +1 @@ -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 +Recipient AgentPostgreSQLWorker(Pub/Sub + Cloud Tasks)Agent-Core(Workflow DAG)Auth Service(JWT, OTP)Gateway API(FastAPI, async)MCP Server(AI Assistants)Client/SDKRecipient AgentPostgreSQLWorker(Pub/Sub + Cloud Tasks)Agent-Core(Workflow DAG)Auth Service(JWT, OTP)Gateway API(FastAPI, async)MCP Server(AI Assistants)Client/SDKMCP path (AI assistants via JSON-RPC)Direct API path (SDK/CLI)Async pipeline (Pub/Sub + Cloud Tasks)proxy tool call -> REST API1JSON response -> MCP result2API request3validate x-api-key + Bearer token4auth result5write intent + audit envelope6start or continue workflow7deliver step/intent (SSE/http/poll)8callback/progress9persist state + events10publish intent.created (Pub/Sub)11lifecycle events12persist step state13Cloud Tasks: timeout + reminder jobs14tick due run (scheduled wakeup)15latest status16response/read model17 \ No newline at end of file