mivia-ai-sdk

module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 7, 2026 License: Apache-2.0

README

mivia

mivia-ai-sdk

Go SDK for building reliable AI agents and multi-agent workflows. Composable blocks, not a monolith.

Documentation

mivia-ai-sdk provides a set of independent, composable building blocks for building autonomous agents, multi-agent coordination pipelines, and verifiable message exchanges in Go.

Most packages rely solely on the Go standard library, keeping dependencies minimal, auditable, and fast.

Highlights

  • 🔒 Verifiable Agent Messaging — Cryptographic envelopes signed with Ed25519, tamper-evident hash audit chains, and semantic acknowledgments (envelope, room, identity).
  • 🔄 Deterministic Workflows & State — Declarative step graphs, parallel execution waves, guarded state machines, retries, loops, and pause/resume checkpoints (flow, machine).
  • 🧰 Extensible Tools & MCP — Named tool registries, permission scoping, approval gating, and MCP client support over stdio or streamable HTTP (tools, mcp).
  • 🤝 Interoperability & Protocols — Native A2A v1.0 mapping, gRPC client adapter, and NDJSON HTTP streaming endpoints (a2a, a2aclient, dispatch).
  • 🛡️ Confinement & Long-Term Context — Syscall-level filesystem confinement (os.Root), secret path denial, token-window compaction, and content-addressed memory (workspace, contextplan, longtermmemory).

Install

go get github.com/MiviaLabs/mivia-ai-sdk

Quick Start

Compose an agent pipeline from an identity, a capability card, a two-step plan, and registered tools. A single agentrun.Options literal wires and validates the pipeline:

package main

import (
	"context"
	"fmt"

	"github.com/MiviaLabs/mivia-ai-sdk/agent"
	"github.com/MiviaLabs/mivia-ai-sdk/agentrun"
	"github.com/MiviaLabs/mivia-ai-sdk/discovery"
	"github.com/MiviaLabs/mivia-ai-sdk/flow"
	"github.com/MiviaLabs/mivia-ai-sdk/identity"
	"github.com/MiviaLabs/mivia-ai-sdk/machine"
	"github.com/MiviaLabs/mivia-ai-sdk/tools"
)

type prefixTool struct {
	name   string
	prefix string
}

func (t prefixTool) Name() string { return t.name }

func (t prefixTool) Run(ctx context.Context, in tools.InOut) (tools.Out, error) {
	s, _ := in.Value.(string)
	return tools.Out{Value: t.prefix + s}, nil
}

func main() {
	artifacts := &agentrun.Artifacts{}
	plan, err := flow.New([]flow.Step{
		{ID: "review", To: "reviewed", Payload: "invoice 42"},
		{ID: "ship", To: "shipped", Needs: []string{"review"},
			PayloadFrom: agentrun.PayloadOf("review", artifacts)},
	}, nil)
	if err != nil {
		panic(err)
	}

	id, err := identity.New()
	if err != nil {
		panic(err)
	}
	a, err := agent.New(id, discovery.Card{
		Name: "invoice-agent", Capabilities: []string{"invoice.review"},
	}, plan)
	if err != nil {
		panic(err)
	}

	reg := tools.New()
	_ = reg.Add(prefixTool{name: "review", prefix: "reviewed: "})
	_ = reg.Add(prefixTool{name: "ship", prefix: "shipped: "})

	m, err := machine.New("queued",
		machine.Transition{From: "queued", To: "reviewed", Trigger: "run"},
		machine.Transition{From: "reviewed", To: "shipped", Trigger: "run"},
	)
	if err != nil {
		panic(err)
	}

	runner, err := agentrun.New(agentrun.Options{
		Agent: a, Machine: m, Tools: reg, Artifacts: artifacts,
	})
	if err != nil {
		panic(err)
	}

	status, _, err := runner.Run(context.Background(), "thread-1", machine.InOut{})
	if err != nil {
		panic(err)
	}

	ship, _ := artifacts.Get("ship")
	fmt.Println("status:", status)      // prints "status: shipped"
	fmt.Println("ship artifact:", ship) // prints "shipped: reviewed: invoice 42"
}

Documentation

Development

make install-hooks   # once per clone; sets core.hooksPath to .githooks
make verify-fast     # fast tier: fmt, vet, test, gates, semgrep scan
make verify          # full tier: coverage floor, semgrep probes, SQLite tests

Author & Contributors

Contributions are welcome!

License

Apache License 2.0. See NOTICE for attribution.

Directories

Path Synopsis
Package a2a maps an envelope.Message onto an A2A v1.0 message part and back.
 Package a2a maps an envelope.Message onto an A2A v1.0 message part and back.
Package a2aack turns a remote A2A task round trip into the agent composition layer's AckWait.
 Package a2aack turns a remote A2A task round trip into the agent composition layer's AckWait.
Package a2aclient sends an envelope.Message to a remote agent and polls task status and results, through the a2aproject/a2a-go client.
 Package a2aclient sends an envelope.Message to a remote agent and polls task status and results, through the a2aproject/a2a-go client.
Package a2aloopback ships a real gRPC A2A test-server fixture, Loopback.
 Package a2aloopback ships a real gRPC A2A test-server fixture, Loopback.
Package agent defines one agent declaratively: an identity, a capability card, and a step plan, bound into one value.
 Package agent defines one agent declaratively: an identity, a capability card, and a step plan, bound into one value.
Package agentloop runs a model until it stops asking for tools.
 Package agentloop runs a model until it stops asking for tools.
Package agentrun wires an agent, a machine, and optional blocks into a runnable pipeline.
 Package agentrun wires an agent, a machine, and optional blocks into a runnable pipeline.
Package channel gives every part of this SDK that must ask a question and wait for a typed answer one shared shape to build a closure from: Question, Answer, and Notifier.
 Package channel gives every part of this SDK that must ask a question and wait for a typed answer one shared shape to build a closure from: Question, Answer, and Notifier.
Package contextbudget states and checks a budget for one model call's context.
 Package contextbudget states and checks a budget for one model call's context.
Package contextplan manages token budget windows and compaction.
 Package contextplan manages token budget windows and compaction.
Package contextref provides the canonical content-reference minter and parser.
 Package contextref provides the canonical content-reference minter and parser.
Package contextsession plans durable session history into a bounded provider request with retention rules and overflow spooling.
 Package contextsession plans durable session history into a bounded provider request with retention rules and overflow spooling.
Package contextstate holds the durable context contract.
 Package contextstate holds the durable context contract.
Package contextsummary turns the messages a compaction drops into one validated, bounded summary document, through one bounded provider.Completer call.
 Package contextsummary turns the messages a compaction drops into one validated, bounded summary document, through one bounded provider.Completer call.
Package discovery answers whether an agent can do a task.
 Package discovery answers whether an agent can do a task.
Package dispatch receives newline-delimited envelope JSON over HTTP, runs the full receive ladder per line, and answers with newline-delimited ack JSON.
 Package dispatch receives newline-delimited envelope JSON over HTTP, runs the full receive ladder per line, and answers with newline-delimited ack JSON.
docs
examples/_agentcomposition command
examples/_agentloop command
Command agentloop wires a complete agentloop.Options and runs one scripted two-turn tool exchange offline.
 Command agentloop wires a complete agentloop.Options and runs one scripted two-turn tool exchange offline.
examples/_agentloop_adoption command
Command agentloop_adoption is the external-adopter positive control: it sets every agentloop Options row an external consumer is expected to adopt, one commented line per row of the adoption table (Usage, Budget, MaxTotalTokens, MaxConsecutiveToolFailures, Tracer, DedupWithinTurn, Audit, Conclude, HeartbeatInterval + Bus, and the Window/Summarizer/Calibrated compaction triple).
 Command agentloop_adoption is the external-adopter positive control: it sets every agentloop Options row an external consumer is expected to adopt, one commented line per row of the adoption table (Usage, Budget, MaxTotalTokens, MaxConsecutiveToolFailures, Tracer, DedupWithinTurn, Audit, Conclude, HeartbeatInterval + Bus, and the Window/Summarizer/Calibrated compaction triple).
examples/_agentloop_minimal command
Command agentloop_minimal shows the smallest useful agentloop entry: one completer, one tool, DefaultBounds, and EnableCompaction build the whole Options.
 Command agentloop_minimal shows the smallest useful agentloop entry: one completer, one tool, DefaultBounds, and EnableCompaction build the whole Options.
examples/_agentrun command
Command agentrun walks a two-step pipeline through the agentrun composition layer.
 Command agentrun walks a two-step pipeline through the agentrun composition layer.
Package durablefence is a conformance-test kit, built on testing.TB.
 Package durablefence is a conformance-test kit, built on testing.TB.
Package e2e proves the composed SDK works end to end.
 Package e2e proves the composed SDK works end to end.
Package envelope implements the AI message envelope: a natural-language payload inside machine-checkable metadata.
 Package envelope implements the AI message envelope: a natural-language payload inside machine-checkable metadata.
Package envfile loads a dotenv file into a map.
 Package envfile loads a dotenv file into a map.
Package events implements a caller-owned reaction bus: typed events, one subscription set, and in-process dispatch.
 Package events implements a caller-owned reaction bus: typed events, one subscription set, and in-process dispatch.
Package flow implements the declarative workflow block: a step graph with dependencies and panels.
 Package flow implements the declarative workflow block: a step graph with dependencies and panels.
Package heartbeat tracks liveness by time.
 Package heartbeat tracks liveness by time.
Package hooks gives a caller a named, multi-handler registry for a lifecycle point: Point, Handler, and a Registry whose Fire runs every handler at a point in registration order and stops at the first veto.
 Package hooks gives a caller a named, multi-handler registry for a lifecycle point: Point, Handler, and a Registry whose Fire runs every handler at a point in registration order and stops at the first veto.
Package identity owns one agent key: an ed25519 pair, the key-file load, the invariant check, and the hex signer string.
 Package identity owns one agent key: an ed25519 pair, the key-file load, the invariant check, and the hex signer string.
Package ledger implements the durable-task-admission block: idempotency-keyed admission, lease-based ownership with fencing, and dependency-driven blocking on failure.
 Package ledger implements the durable-task-admission block: idempotency-keyed admission, lease-based ownership with fencing, and dependency-driven blocking on failure.
Package longtermmemory holds durable-feeling learnings an agent wants across turns: entries in core and archive tiers, a small never-evicted core per scope, automatic consolidation near capacity, keyword search, and a bounded core-context frame a caller renders into its own system prompt.
 Package longtermmemory holds durable-feeling learnings an agent wants across turns: entries in core and archive tiers, a small never-evicted core per scope, automatic consolidation near capacity, keyword search, and a bounded core-context frame a caller renders into its own system prompt.
Package machine implements the state-machine block: typed statuses, triggers, guards, actions, and the transition table.
 Package machine implements the state-machine block: typed statuses, triggers, guards, actions, and the transition table.
Package mcp wraps the official Model Context Protocol Go SDK's client (github.com/modelcontextprotocol/go-sdk/mcp) and maps a remote MCP server's tools onto this module's tools.Tool and tools.Registry.
 Package mcp wraps the official Model Context Protocol Go SDK's client (github.com/modelcontextprotocol/go-sdk/mcp) and maps a remote MCP server's tools onto this module's tools.Tool and tools.Registry.
Package memory stores and fetches context blobs by content address.
 Package memory stores and fetches context blobs by content address.
Package provider defines the Completer contract a caller uses to complete a chat turn against a language model, plus the request and response shapes the contract carries.
 Package provider defines the Completer contract a caller uses to complete a chat turn against a language model, plus the request and response shapes the contract carries.
anthropic
Package anthropic implements a provider.Completer adapter for the Anthropic Messages API.
 Package anthropic implements a provider.Completer adapter for the Anthropic Messages API.
Package providerregistry holds named provider.Completer values and routes one request across them in a caller-chosen order.
 Package providerregistry holds named provider.Completer values and routes one request across them in a caller-chosen order.
Package room manages standing groups for envelope messages: a roster with roles, moderator-gated admission, and a gate that admits an envelope.Message only when its signer is a member.
 Package room manages standing groups for envelope messages: a roster with roles, moderator-gated admission, and a gate that admits an envelope.Message only when its signer is a member.
Package runconfig loads a JSON document into a validated agentrun runner and its tool set.
 Package runconfig loads a JSON document into a validated agentrun runner and its tool set.
Package scheduler invokes a caller-supplied Job on a schedule.
 Package scheduler invokes a caller-supplied Job on a schedule.
Package schema compiles a JSON Schema document, validates JSON payloads against it, and builds a bounded, model-facing corrective message on a validation failure.
 Package schema compiles a JSON Schema document, validates JSON payloads against it, and builds a bounded, model-facing corrective message on a validation failure.
Command api_surface prints the exported API surface of every package directory in this module, at any depth.
 Command api_surface prints the exported API surface of every package directory in this module, at any depth.
Package secretpath matches a filesystem path against a configured list of glob-style secret path patterns, so a caller can decide whether a path holds sensitive content before it reads, writes, or logs it.
 Package secretpath matches a filesystem path against a configured list of glob-style secret path patterns, so a caller can decide whether a path holds sensitive content before it reads, writes, or logs it.
Package skills holds a reusable instruction bundle a caller registers under a name and finds again by trigger phrase or by name.
 Package skills holds a reusable instruction bundle a caller registers under a name and finds again by trigger phrase or by name.
Package spool stores oversized content under a principal-scoped grant and hands the caller a bounded view plus a reference.
 Package spool stores oversized content under a principal-scoped grant and hands the caller a bounded view plus a reference.
Package subagent exposes built SDK blocks as tools in three groups.
 Package subagent exposes built SDK blocks as tools in three groups.
Package taskrun runs one task under ledger admission: admit, claim, complete.
 Package taskrun runs one task under ledger admission: admit, claim, complete.
Package tools defines a named-action interface and a registry that resolves a name to a Tool and runs it.
 Package tools defines a named-action interface and a registry that resolves a name to a Tool and runs it.
Package trace gives a caller a structured trace of a multi-step run: Span records one named operation, Tracer issues spans and links them through ctx.
 Package trace gives a caller a structured trace of a multi-step run: Span records one named operation, Tracer issues spans and links them through ctx.
Package trigger gives every part of this SDK one shared vocabulary for "a condition fired, so run this": Condition, Action, and a Registry mapping a name to one of each.
 Package trigger gives every part of this SDK one shared vocabulary for "a condition fired, so run this": Condition, Action, and a Registry mapping a name to one of each.
Package usage gives a caller a per-session running total of provider.Usage.
 Package usage gives a caller a per-session running total of provider.Usage.
Package workspace confines all filesystem access to one root directory, so a tool or agent that reads and writes files cannot escape its sandbox through path traversal or a symlink.
 Package workspace confines all filesystem access to one root directory, so a tool or agent that reads and writes files cannot escape its sandbox through path traversal or a symlink.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.