easynet-run-axon

Python SDK for EasyNet Axon — the Capability Control Plane for agent-native distributed execution.

What is this?

This is the Python surface for Axon, a protocol-level control plane that treats agent capabilities as first-class network objects — not raw RPC endpoints. Every ability you expose carries its own schema, trust posture, scheduling contract, and tenant isolation rules, enforced atomically at invocation time.

Why this matters: In traditional architectures, policy evaluation, node selection, rate limiting, and concurrency admission happen in separate systems with separate state. That creates a race window — OPA approves a call against nodes {A,B,C}, but the load balancer routes to Node D added between decisions. Axon collapses all six checks (tenant isolation, rate limit, policy, node selection, concurrency, circuit breaker) into a single atomic decision against the same state snapshot.

Note: The wheel is platform-tagged (not any) because it ships a native Dendrite bridge binary — the same C ABI that powers protocol-complete Axon gRPC calls without reimplementing protobuf encoding or streaming semantics in Python.

Install

pip install easynet-run-axon

Platform / Native Bundle Notes

The Python wheel contains native runtime + bridge payload and is therefore target-specific.

• Wheels are published to PyPI per target. pip install on a host automatically selects the matching wheel.
• For explicit cross-target workflows (CI + dev), use matching GitHub Release packs:
  • sdk-packs-aarch64-apple-darwin.tar.gz
  • sdk-packs-aarch64-apple-ios.tar.gz
  • sdk-packs-x86_64-apple-ios.tar.gz
  • sdk-packs-x86_64-unknown-linux-gnu.tar.gz
  • sdk-packs-aarch64-unknown-linux-gnu.tar.gz
  • sdk-packs-aarch64-linux-android.tar.gz
  • sdk-packs-x86_64-pc-windows-msvc.tar.gz
  • sdk-packs-x86_64-apple-darwin.tar.gz
• If auto selection is not available (e.g., offline/air-gapped), install from pack file directly:

pip install /path/to/dist/sdk-packs/<version>/python/easynet_run_axon-<version>-cp*.whl

• CI/source cross-target hints:
  • SDK_VERSION=<version> (optional; resolver checks this value and then falls back to 0.1.0)
  • EASYNET_DENDRITE_BRIDGE_PLATFORM=ios|android|linux|windows|macos
  • EASYNET_DENDRITE_BRIDGE_LIB=/abs/path/libaxon_dendrite_bridge.<ext>
  • EASYNET_DENDRITE_BRIDGE_HOME=/path/to/sdk-packs-<target>.tar.gz/extracted/package（例如 dist/sdk-packs/<version>/python 或其父级的统一目录）
  • EASYNET_DENDRITE_BRIDGE_SOURCE=local to auto-bind from source-tree release output (core/runtime-rs/dendrite-bridge/target/...) when running from repository checkout.

Quick Start

Expose an ability

from easynet_axon import ability, serve

@ability("easynet:///r/org/reg/agent.quote-bot/abilities/order.quote@1?tenant_id=tenant-test")
def quote(ctx, sku: str, qty: int = 1):
    return {"sku": sku, "price": 19.9 * qty}

serve("agent.quote-bot")

Invoke an ability

from easynet_axon import client

res = (
    client()
    .tenant("tenant-test")
    .ability("easynet:///r/org/reg/agent.quote-bot/abilities/order.quote@1?tenant_id=tenant-test")
    .call({"sku": "A1", "qty": 2})
)

Bootstrap a local runtime behind NAT

No public IP required. The SDK spawns a local Axon runtime that joins a federation Hub over outbound gRPC only:

from easynet_axon import start_server

srv = start_server(
    hub="axon://hub.easynet.run:50084",
    hub_tenant="tenant-test",
    hub_label="alice-macbook",
)

Capabilities

Core Protocol

• Fluent builders — .tenant() → .principal() → .ability() → .call() are immutable and chainable.
• Native Dendrite bridge — DendriteBridge loads the platform C ABI via ctypes; all Axon gRPC shapes (unary, server-stream, client-stream, bidi-stream) are available without gRPC codegen.
• Semantic DSL — SemanticBridge and @ability_call decorator for ergonomic protocol invocation.
• Subject binding — .principal(...) scopes invocation to a subject identity with automatic URI visibility mapping (pub/prv/org).

Ability Lifecycle

Full lifecycle management — not just invocation:

• build_ability_descriptor() / export_ability() — define and register abilities with schemas
• deploy_to_node() — install + activate on target nodes
• list_abilities() / invoke_ability() / uninstall_ability()
• forget_all() — bulk removal of all deployed abilities

MCP & A2A Protocols

• MCP server — StdioMcpServer hosts JSON-RPC 2.0 tool endpoints over stdio.
• MCP operations — deploy_mcp_list_dir(), list_mcp_tools(), call_mcp_tool_with_args(), update_mcp_list_dir()
• A2A agent protocol — list_a2a_agents(), get_a2a_agent_card(), send_a2a_task() for inter-agent task dispatch.
• Tool adapter — AbilityToolAdapter converts Axon abilities to OpenAI/Anthropic tool definitions with local handler registration.

Voice & Media Signaling

First-class voice call lifecycle and transport negotiation:

• Call management: create, join, leave, end, watch events, report metrics
• Transport sessions: create, set description, add ICE candidates, refresh lease
• Codec profile negotiation

Federation

• start_server() spawns a local Axon runtime and joins the Hub — all traffic is outbound.
• FederationCaseKit for cross-network orchestration workflows.
• Federated node discovery, heartbeat, and invocation dispatch.
• Preset status: FederationCaseKit is currently the only first-party high-level federation preset helper; other SDKs expose federation through lower-level runtime/client surfaces only.

Remote Control & Orchestration

• OrchestratorFactory / RemoteOrchestratorFactory for subprocess template building and capability deployment workflows.
• Bundle reading, media persistence, CLI argument handling.

License

Apache-2.0 — see LICENSE.

Author

Silan Hu · silan.hu@u.nus.edu