Skip to content
Canonical source: README.md. This page is rendered from the repository document during the MkDocs build.

NeKiro Go SDK

This repository is the canonical source for NeKiro's public Go SDKs:

  • agent: runtime-neutral managed Agent-to-Agent invocation through the NeKiro A2A Router.
  • agent/registration/nacos: strict public composition for publishing a Runtime instance through a Core-owned Nacos lease.
  • agent/routerauth: verification and middleware for Router-issued invocation credentials.
  • client: application invocation of Agents already installed in one Workspace.

The first released SDK targets the Gateway /v1 surface exclusively. Agent nested calls remain on /agent/v1; the SDK never probes retired Gateway /v2, /v3, or /v4 paths.

The SDK depends only on public NeKiro Core packages: versioned contracts, and the provider-neutral registry surface used by the Nacos registration adapter. It does not import Core service internals, discover endpoints, retry, select alternate components, or provide an Agent Runtime.

1
go get github.com/NeKiro-project/nekiro-sdk-go@<reviewed-release>

Import packages with:

1
2
3
4
5
6
import (
    agentsdk "github.com/NeKiro-project/nekiro-sdk-go/agent"
    registrationnacos "github.com/NeKiro-project/nekiro-sdk-go/agent/registration/nacos"
    "github.com/NeKiro-project/nekiro-sdk-go/agent/routerauth"
    clientsdk "github.com/NeKiro-project/nekiro-sdk-go/client"
)

agent/registration/nacos is the only package here that composes public Core registry mechanics in addition to contracts. Core remains the owner of the registration protocol and lease semantics; the SDK adds strict Runtime-facing configuration and transport ergonomics without endpoint discovery or fallback.

Compatibility is explicit in go.mod. Consumers must update the SDK and core contract versions deliberately; local replace directives and floating source references are unsupported.

Development and verification

Run the complete SDK-owned checks from the repository root:

1
2
3
4
5
6
7
go build ./...
go test -count=1 ./...
go test -race ./...
go vet ./...
go mod tidy
go mod verify
git diff --check

Verification succeeds when every package builds, all Agent/auth/client tests pass, the race detector and vet report no findings, and go mod tidy leaves the module files unchanged. Contract-boundary tests must also confirm that no SDK package imports a Core service implementation package.

The Core compatibility workflow can test the canonical SDK source against an explicit full Core commit SHA. It temporarily resolves that exact public Core module revision in the CI checkout, runs the public-contract suite, and never commits the changed module files or adds a local replace directive. Core uses this reusable workflow after every merge to main.

Releases

An annotated stable semantic tag runs the complete SDK checks and publishes a GitHub release with release.json. That evidence records the SDK tag and commit plus the exact Core module revision used by the release. The first release line requires NeKiro Core v0.1.x and its unified Platform API v1.

RepoWiki

The NeKiro Go SDK RepoWiki publishes the SDK documentation in English and Chinese with MkDocs Material. The source README files remain canonical.

Pull requests

Pull requests must identify affected public packages and types, the exact Core contract revision used for verification, compatibility impact, commands run, and observable success signals. A public API break requires an explicit versioning and migration decision.

Provenance

The package history was exported from NeKiro-project/NeKiro@aad73c450435a9b6c76c26cc6c525fa811b0e7ad. The original sdks/ tree is b99c20c335322f623f850c14f20604d23c9d0079, and the history-preserving export commit is 1fe1f62ca17dd821a47c1d000734e2babeddee19. The source repository retains the annotated tag pre-repository-split-2026-08-04 for original commit and signature provenance.

Licensed under Apache-2.0. See LICENSE.