sdk-go

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

---

What is this?

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

Axon collapses tenant isolation, rate limiting, policy evaluation, node selection, concurrency admission, and circuit breaking into a single atomic decision against the same state snapshot. No race window between policy check and routing.

The SDK ships a native Dendrite bridge binary (loaded via cgo + dlopen/dlsym) that provides protocol-complete Axon gRPC calls without gRPC codegen in Go.

Install

go get easynet.run/axon/sdk/go

Platform / Native Bundle Notes

• The Go module release (easynet.run/axon/sdk/go) is source-first and can be fetched regardless of host.
• Native + runtime payload for deployed targets is distributed via GitHub Release SDK-pack artifacts, not always inside the module tarball itself.
• If building or testing on another target than your host:
  • download the matching sdk-packs-<target>.tar.gz from Releases
  • extract go/ and align your runtime dependency/runtime files with that pack.
  • optional: SDK_VERSION=<version> (resolver checks explicit version first, then fallback)
  • set EASYNET_DENDRITE_BRIDGE_PLATFORM=ios|android|linux|windows|macos.
  • set EASYNET_DENDRITE_BRIDGE_LIB=/abs/path/to/libaxon_dendrite_bridge.<ext> when you want fully explicit binding.
  • set EASYNET_DENDRITE_BRIDGE_HOME=<pack-root> (directory containing native/) to reuse one extracted target pack across tools.
  • set EASYNET_DENDRITE_BRIDGE_SOURCE=local to let source-presets auto-detect local core/runtime-rs artifacts in repository checkouts.
• If building from repo source for target-specific output:
  • set SDK_TARGET + SDK_LIB_EXT in packaging scripts and install from that pack.
  • set SDK_VERSION=<version> and EASYNET_DENDRITE_BRIDGE_SOURCE=local when you want source-tree probing first.

Quick Start

Expose an ability

easynet.Ability("easynet:///r/org/reg/agent.quote-bot/abilities/order.quote@1?tenant_id=tenant-test").
  Handle(func(ctx context.Context, in easynet.Payload) (easynet.Payload, error) {
    qty := 1
    if v, ok := in["qty"].(int); ok {
      qty = v
    }
    return easynet.Payload{"sku": in["sku"], "price": 19.9 * float64(qty)}, nil
  }).
  Expose()

Invoke an ability

res, _ := easynet.NewClient(nil).
  Tenant("tenant-test").
  Ability("easynet:///r/org/reg/agent.quote-bot/abilities/order.quote@1?tenant_id=tenant-test").
  Call(ctx, easynet.Payload{"sku": "A1", "qty": 2})

Use CallAny() or CallRaw() for stream/media-oriented non-object payloads.

Bootstrap a local runtime behind NAT

srv, err := easynet.StartServerWithOptions(easynet.StartServerOptions{
  Hub:       "axon://hub.easynet.run:50084",
  HubTenant: "tenant-test",
  HubLabel:  "alice-macbook",
})
defer srv.Stop()

No public IP required — the local runtime connects outbound to the Hub.

Capabilities

Core Protocol

• Fluent builders — Tenant() → Principal() → Ability() → Call() are immutable, chainable, and context-aware.
• Native Dendrite bridge — DendriteBridge loads the platform C ABI via cgo; all Axon gRPC shapes (unary, server-stream, client-stream, bidi-stream) available without gRPC codegen.
• Semantic builder — SemanticBridge for catalog-aware invocation with functional options (WithAbilityTimeoutMs, WithMetadata).
• Subject binding — Principal(...) scopes invocation to a subject identity with automatic URI visibility mapping.

Ability Lifecycle

Full lifecycle management — not just invocation:

• BuildAbilityDescriptor() / ExportAbility() — define and register abilities with schemas
• DeployToNode() — install + activate on target nodes
• ListAbilities() / InvokeAbility() / UninstallAbility()
• DiscoverNodes() / ExecuteCommand() / DisconnectDevice() / DrainDevice()

MCP & A2A Protocols

• MCP server — StdioMcpServer hosts JSON-RPC 2.0 tool endpoints over stdio.
• MCP operations — deploy, list, call, and update MCP tools on remote nodes.
• A2A agent protocol — ListA2aAgents(), SendA2aTask() for inter-agent discovery and task dispatch.
• Tool adapter — convert abilities to OpenAI/Anthropic tool definitions.

Voice & Media Signaling

First-class voice call lifecycle and transport negotiation (cgo build-tagged):

• Call management: create, join, leave, end, watch events, report metrics
• Transport sessions: create, set description, add ICE candidates, refresh lease
• Media path updates

Orchestration

High-level capability management for server-side workflows:

orch := easynet.NewOrchestrator(
  easynet.WithEndpoint("http://127.0.0.1:50051"),
  easynet.WithTenant("tenant-test"),
)
defer orch.Close()

node, _ := orch.SelectNode("", "")
lifecycle, _ := orch.PublishInstallActivate(
  node["node_id"].(string), packageRef, capName, bundle, execPolicy,
)

Federation

• StartServerWithOptions() spawns a local Axon runtime and joins the Hub — all traffic is outbound.
• Federated node discovery and cross-network invocation dispatch.
• Preset status: the high-level federation preset helper is currently Python-only; Go exposes the runtime bootstrap and federation transport surfaces directly.

License

Apache-2.0 — see LICENSE.

Author

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