# Aroha Labs — Full LLM Context # https://www.aroha-labs.com/llms-full.txt # Last updated: 2026-07-06 # License: MIT (protocol spec and SDK). Copyright (c) 2026 Aroha Labs. This file contains the complete Aroha protocol specification, SDK quickstarts, API reference, and integration guides inlined for LLM consumption. No link- following required. See /llms.txt for a shorter indexed version. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ WHAT IS AROHA? ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Aroha is the trust and delegation layer for MCP-powered agent networks. The Model Context Protocol (MCP) connects agents to tools (APIs, databases, file systems). Aroha connects agents to each other — with: • Cryptographic mandate chains — Ed25519-signed authority that narrows as it delegates. An orchestrator can never grant more scope than it received. Every chain traces to a human issuer. • Spending mandates — hard caps on what an agent can spend. Enforced at every hop. Agents that exceed their mandate are rejected before they can act. • Saga transactions — distributed coordination with automatic LIFO rollback. If any step fails, all completed steps are compensated in reverse order. Based on the proven saga pattern from distributed systems. • DID identity — every agent has a did:aroha: identifier. DIDs are registered on the Hub, resolved to manifests stored on IPFS, and verified with Ed25519 public keys. • Settlement — payments between agents are settled cryptographically, with spending limits enforced end-to-end. Positioning: Aroha is NOT an alternative to MCP. It is a layer on top of MCP. Your existing MCP servers keep working. Aroha wraps the agents that call them. "MCP for tools. Aroha for trust." ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ARCHITECTURE — FIVE LAYERS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Strict one-way dependency: each layer imports only from layers below it. L04 — Application Layer Consumer-facing agents: Personal Agents, Provider Agents, Orchestrators, Data Agent, Calendar Agent. L03 — Orchestration Layer Multi-agent coordination: SagaEngine, AgentSelector, CSN Negotiator, ApprovalGate, HumanApprovalGate. L02 — Extension Layer Pluggable, zero upward dependencies: credentials, settlement, reputation, registry, cache, policy. L01 — Transport Layer HTTP + WebSocket: ArohaServer, ArohaClient, WebSocket, Middleware, ArohaMicro. L00 — Identity & Crypto (Foundation) did:aroha:, Ed25519, AES-256-GCM, SpendingMandate, NonceRegistry. Never imports from any layer above it. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PROTOCOL v1.0 — CORE CONCEPTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ## ArohaEnvelope — every message Every agent-to-agent message is wrapped in an ArohaEnvelope: interface ArohaEnvelope { // Routing from: string; // sender DID, e.g. "did:aroha:studio:abc123" to: string; // recipient DID sessionId: string; // conversation thread ID (UUID) messageId: string; // this message (UUID) // Authority mandateToken: string; // signed JWT — scope of authority for this call spendingCap: number; // USD ceiling inherited from mandate // Payload message: string; // human-readable request history?: Message[]; // prior turns (optional) context?: Record; // caller metadata // Trust signature: string; // Ed25519 sig over canonical JSON of above fields timestamp: number; // Unix ms — prevents replay attacks nonce: string; // single-use — registered in NonceRegistry } ## DID Format did:aroha:: Examples: did:aroha:studio:abc123 — Studio-created agent did:aroha:hub:weather-agent-v2 — Hub-registered agent did:aroha:user:alice — Human issuer Resolution: 1. GET https://aroha-registry.aroha-labs.workers.dev/v1/agents/{didHash} → Returns { endpointUrl, manifestCID, publicKeyB64 } 2. GET https://gateway.pinata.cloud/ipfs/{manifestCID} → Returns the canonical agent manifest (IPFS-pinned) 3. POST {manifest.endpoint}/v1/run → Call the agent ## Agent Manifest Schema (v1.0) { "arohaProtocolVersion": "1.0", "did": "did:aroha:studio:abc123", "name": "Weather Agent", "description": "Real-time weather for any city", "endpoint": "https://my-agent.fly.dev", "provider": "anthropic", "model": "claude-sonnet-4-6", "systemPrompt": "You are a weather assistant…", "memory": { "type": "session" }, "auth": { "type": "bearer" }, "capabilities": [ { "id": "mcp:weather-tools", "name": "WeatherTools", "trustLevel": "medium" }, { "id": "skill:web-search", "name": "WebSearch", "trustLevel": "low" } ] } ## Mandate Chain The mandate is the core primitive. A mandate is a signed, attenuatable scope of authority. Rules: - Authority can only narrow as it delegates, never widen - Every mandate chain traces to a human issuer - Mandates carry a spend limit (USD) and allowed action set - Verified with Ed25519 — tampering is detectable TypeScript example: import { issueIntentMandate, attenuateToPayment, verifyMandate } from "@aroha-sdk/credentials"; // Human → Orchestrator: "spend up to $500, flights only" const { mandate, token } = await issueIntentMandate( humanDID, orchestratorDID, { spendLimitUsd: 500, allowedActions: ["book-flights"] }, humanPrivateKey, 3_600_000, // 1 hour TTL ); // Orchestrator → Sub-agent: narrows to $200, same action set const subToken = await attenuateToPayment(token, { spendLimitUsd: 200, // ≤ parent's $500 allowedActions: ["book-flights"], // must be subset }, orchestratorPrivateKey); // Sub-agent verifies before acting const result = await verifyMandate(subToken, agentDID); // result.spendLimitUsd === 200 ## Saga Pattern Distributed transaction coordination with LIFO rollback. States: PENDING → RESERVING → [APPROVING] → COMMITTING → COMMITTED (happy path) Any state → COMPENSATING → FAILED (error path) APPROVING is optional (requires human-in-the-loop approval gate). COMPENSATING does LIFO rollback: the last completed step is undone first. TypeScript example: import { SagaEngine } from "@aroha-sdk/orchestration"; const engine = new SagaEngine({ steps: [ { name: "reserve-flight", execute: async (ctx) => await flightApi.reserve(ctx.params), compensate: async (ctx) => await flightApi.cancel(ctx.reservationId), }, { name: "charge-payment", execute: async (ctx) => await paymentApi.charge(ctx.amount), compensate: async (ctx) => await paymentApi.refund(ctx.chargeId), }, ], }); const result = await engine.run({ params: { destination: "Auckland" } }); // On failure: charge-payment.compensate(), then reserve-flight.compensate() ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ HTTP API — CALLING AN AGENT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ## Run endpoint POST {agent.endpoint}/v1/run Content-Type: application/json Authorization: Bearer // optional — agent declares auth type { "message": "What is the weather in Auckland?", "sessionId": "sess_abc123", // optional — enables memory across turns "history": [ // optional — prior conversation turns { "role": "user", "content": "Hi" }, { "role": "assistant", "content": "Hello! How can I help?" } ], "context": { // optional — caller metadata "userId": "user:xyz", "locale": "en-NZ" } } 200 OK { "message": "It's 14°C and partly cloudy in Auckland right now.", "sessionId": "sess_abc123", "artifacts": [], "usage": { "inputTokens": 120, "outputTokens": 45 } } ## Registry endpoints # Register an agent POST https://aroha-registry.aroha-labs.workers.dev/v1/agents Authorization: Bearer { "did": "did:aroha:studio:abc123", "manifestCID": "QmXxx…", "publicKeyB64": "MFkwEw…", "endpointUrl": "https://my-agent.fly.dev" } # Resolve an agent GET https://aroha-registry.aroha-labs.workers.dev/v1/agents/{didHash} → { endpointUrl, manifestCID, publicKeyB64, createdAt } # List agents (Hub search) GET https://aroha-registry.aroha-labs.workers.dev/v1/agents?q=weather&limit=20 → { agents: [...], total, page } ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PYTHON SDK QUICKSTART ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Install: pip install aroha ## Minimal agent (FastAPI / asyncio) from aroha.agent import serve import anthropic @serve( name="My Agent", system_prompt="You are a helpful assistant.", provider="anthropic", model="claude-sonnet-4-6", memory="session", ) async def my_agent(message, session_id, history, context): client = anthropic.Anthropic() resp = client.messages.create( model="claude-sonnet-4-6", max_tokens=1024, system="You are a helpful assistant.", messages=[{"role": "user", "content": message}], ) return resp.content[0].text if __name__ == "__main__": my_agent.start(port=8000) # Register: my_agent.register("https://my-agent.fly.dev") ## LangChain bridge # pip install "aroha[langchain]" from aroha.bridges.langchain_v1 import from_chain from langchain_anthropic import ChatAnthropic from langchain_core.prompts import ChatPromptTemplate llm = ChatAnthropic(model="claude-sonnet-4-6") prompt = ChatPromptTemplate.from_messages([ ("system", "You are a helpful assistant."), ("human", "{message}"), ]) chain = prompt | llm agent = from_chain(chain, name="LangChain Agent", memory="session") agent.start(port=8000) # LangGraph: from aroha.bridges.langchain_v1 import from_graph ## CrewAI bridge # pip install "aroha[crewai]" from aroha.bridges.crewai_v1 import from_crew from crewai import Agent, Task, Crew crew_agent = Agent( role="Assistant", goal="Be helpful", backstory="Registered on the Aroha Protocol.", llm="anthropic/claude-sonnet-4-6", ) def make_crew(message): task = Task(description=message, agent=crew_agent, expected_output="A helpful response") return Crew(agents=[crew_agent], tasks=[task], verbose=False) agent = from_crew(make_crew, name="CrewAI Agent") agent.start(port=8000) ## Google ADK bridge # pip install "aroha[google-adk]" from aroha.bridges.google_adk import from_runner from google.adk.agents import LlmAgent from google.adk.runners import Runner from google.adk.sessions import InMemorySessionService adk_agent = LlmAgent( name="my_agent", model="gemini-2.0-flash", instruction="You are a helpful assistant.", ) runner = Runner( agent=adk_agent, app_name="my-agent", session_service=InMemorySessionService(), ) agent = from_runner(runner, name="Gemini Agent", memory="session") agent.start(port=8000) ## OpenAI SDK bridge # pip install "aroha[openai]" from aroha.bridges.openai_v1 import from_openai_client from openai import OpenAI agent = from_openai_client( OpenAI(), model="gpt-4o", system_prompt="You are a helpful assistant.", name="GPT Agent", memory="session", ) agent.start(port=8000) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ TYPESCRIPT SDK QUICKSTART ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Install: npm install @aroha-sdk/core Version: v1.2.0 ## Key packages @aroha-sdk/core — ArohaServer, ArohaClient, ArohaEnvelope @aroha-sdk/credentials — DID, Ed25519, mandate chain, SpendingMandate @aroha-sdk/orchestration — SagaEngine, AgentSelector, ApprovalGate @aroha-sdk/registry — Agent registration, DID resolution @aroha-sdk/settlement — Payment settlement primitives @aroha-sdk/micro — Lightweight single-file runtime ## Minimal TypeScript server import { ArohaServer } from "@aroha-sdk/core"; const server = new ArohaServer({ did: "did:aroha:studio:my-agent", privateKey: process.env.AROHA_PRIVATE_KEY!, handler: async (envelope) => { return { message: `Hello from TypeScript — you said: ${envelope.message}` }; }, }); server.listen(8000); ## Mandate chain (TypeScript) import { issueIntentMandate, attenuateToPayment, verifyMandate } from "@aroha-sdk/credentials"; // Issue: human → orchestrator const { token } = await issueIntentMandate( humanDID, orchestratorDID, { spendLimitUsd: 500, allowedActions: ["book-flights"] }, humanPrivateKey, 3_600_000, ); // Attenuate: orchestrator → sub-agent (scope narrows) const subToken = await attenuateToPayment(token, { spendLimitUsd: 200, allowedActions: ["book-flights"], }, orchestratorPrivateKey); // Verify at sub-agent before acting const result = await verifyMandate(subToken, agentDID); ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ AROHA + MCP — HOW THEY FIT TOGETHER ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Human ↓ issues mandate (Aroha) Aroha layer — trust: mandate chain, saga, spending caps, settlement ↓ delegates to Your agent (wrapped by Aroha SDK) ↓ calls tools via MCP layer — tools: file system, APIs, databases, search ↓ External services MCP handles: tool discovery, tool calls, server connections, schema. Aroha handles: agent identity, authority, spending limits, multi-agent coordination, rollback, settlement, auditability. They are complementary protocols. Aroha agents can call any MCP server without modification. MCP servers don't need to know about Aroha. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ CONFORMANCE & COMPATIBILITY ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Aroha-compatible frameworks and bridges: • Hermes Agent — production agent runtime • ZeroClaw — Rust-based, zero-overhead MCP framework • OpenClaw — space-lobster mascot, creative agent layer • TrustClaw / Composio — Composio integration with Aroha trust layer • LangChain / LangGraph • CrewAI • AutoGen (Microsoft) • Google ADK (Gemini) • OpenAI SDK / Agents SDK • Google A2A protocol Conformance test suite: https://www.aroha-labs.com/conformance Governance and RFC process: https://www.aroha-labs.com/governance ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ LINKS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Website: https://www.aroha-labs.com Protocol: https://www.aroha-labs.com/protocol Architecture: https://www.aroha-labs.com/architecture Docs: https://www.aroha-labs.com/docs Hub: https://www.aroha-labs.com/hub Studio: https://www.aroha-labs.com/studio Playground: https://www.aroha-labs.com/playground Conformance: https://www.aroha-labs.com/conformance Governance: https://www.aroha-labs.com/governance Security: https://www.aroha-labs.com/security LLM index: https://www.aroha-labs.com/llms.txt Plugin manifest: https://www.aroha-labs.com/.well-known/ai-plugin.json Registry API: https://aroha-registry.aroha-labs.workers.dev/v1/agents