Documentation on Go Micro

AI Integration

Mon, 01 Jan 0001 00:00:00 +0000

AI Integration

Go Micro is an agent harness and service framework for Go. Every service you build can become an AI-callable tool, every agent runs as a service with model/memory/guardrails around it, and flows orchestrate the deterministic parts. This page explains how the services → agents → workflows lifecycle fits together.

The Stack

Services → write Go handlers, register with the framework
 ↓
Registry → automatic discovery for services, agents, and flows
 ↓
Gateways → micro api (HTTP→RPC), micro mcp (tools), micro a2a (agents)
 ↓
ai.Tools → discovers services + executes RPCs programmatically
 ↓
ai.Model → calls LLMs (Anthropic, OpenAI, Gemini, Atlas Cloud, ...)
 ↓
Agents → service-backed model loop with memory, guardrails, plan/delegate
 ↓
Flows → durable deterministic steps that can dispatch to agents

Every layer is optional. You can use Go Micro as a service framework without AI. You can use the ai package without MCP. But when you stack them, you get one runtime where services become tools, agents are reachable services, and workflows coordinate the predictable parts.

Analysis: Removing Reflection from go-micro

Mon, 01 Jan 0001 00:00:00 +0000

Date: 2026-02-03
Author: GitHub Copilot
Status: RECOMMENDATION - DO NOT PROCEED

Executive Summary

After comprehensive analysis of the go-micro codebase and comparison with livekit/psrpc (referenced as an example of a reflection-free approach), we recommend AGAINST removing reflection from go-micro. The architectural differences make this change infeasible without a complete redesign that would:

Break backward compatibility - Fundamentally change the API
Lose key advantages - Eliminate go-micro’s “any struct as handler” flexibility
Increase complexity - Require extensive code generation and boilerplate
Provide minimal benefit - Performance gains would be negligible for most use cases (~10-20% in specific hot paths)

Current Reflection Usage

Locations

Reflection is used extensively in:

Architecture Decision Records

Mon, 01 Jan 0001 00:00:00 +0000

Documentation of architectural decisions made in Go Micro, following the ADR pattern.

What are ADRs?

Architecture Decision Records (ADRs) capture important architectural decisions along with their context and consequences. They help understand why certain design choices were made.

Index

Available

Planned

Core Design

ADR-002: Interface-First Design
ADR-003: Default Implementations

Service Discovery

Broker

Mon, 01 Jan 0001 00:00:00 +0000

The broker provides pub/sub messaging for Go Micro services.

Features

Publish messages to topics
Subscribe to topics
Multiple broker implementations

Implementations

Supported brokers include:

HTTP (default)
NATS (go-micro.dev/v6/broker/nats)
RabbitMQ (go-micro.dev/v6/broker/rabbitmq)
Memory (go-micro.dev/v6/broker/memory)

Plugins are scoped under go-micro.dev/v6/broker/<plugin>.

Configure the broker in code or via environment variables.

Example Usage

Here’s how to use the broker in your Go Micro service:

Client/Server

Mon, 01 Jan 0001 00:00:00 +0000

Go Micro uses a client/server model for RPC communication between services.

Client

The client is used to make requests to other services.

Server

The server handles incoming requests.

Both client and server are pluggable and support middleware wrappers for additional functionality.

Example Usage

Here’s how to define a simple handler and register it with a Go Micro server:

package main

import (
 "context"
 "go-micro.dev/v6"
 "log"
)

type Greeter struct{}

func (g *Greeter) Hello(ctx context.Context, req *struct{}, rsp *struct{Msg string}) error {
 rsp.Msg = "Hello, world!"
 return nil
}

func main() {
 service := micro.NewService("greeter",
 )
 service.Init()
 micro.RegisterHandler(service.Server(), new(Greeter))
 if err := service.Run(); err != nil {
 log.Fatal(err)
 }
}

Commercial Support

Mon, 01 Jan 0001 00:00:00 +0000

Go Micro is free and open source. There are two ways to get help: the community, and commercial support.

Community support (free)

Documentation — /docs
Examples — github.com/micro/go-micro/tree/master/examples
Bugs & features — github.com/micro/go-micro/issues
Questions — open a Question issue

Community support is best-effort, from maintainers and contributors, with no response-time guarantees.

Commercial support

If you’re running Go Micro in production — or building agents and services on it and want a hand — paid support and consulting are available directly from the maintainer. This is what keeps the project maintained.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Go Micro follows a progressive configuration model so you can start with zero setup and layer in complexity only when needed.

Levels of Configuration

Zero Config (Defaults)
- mDNS registry, HTTP transport, in-memory broker/store
Environment Variables
- Override core components without code changes
Code Options
- Fine-grained control via functional options
External Sources (Future / Plugins)
- Configuration loaded from files, vaults, or remote services

Core Environment Variables

Component	Variable	Example	Purpose
Registry	`MICRO_REGISTRY`	`MICRO_REGISTRY=consul`	Select registry implementation
Registry Address	`MICRO_REGISTRY_ADDRESS`	`MICRO_REGISTRY_ADDRESS=127.0.0.1:8500`	Point to registry service
Broker	`MICRO_BROKER`	`MICRO_BROKER=nats`	Select broker implementation
Broker Address	`MICRO_BROKER_ADDRESS`	`MICRO_BROKER_ADDRESS=nats://localhost:4222`	Broker endpoint
Transport	`MICRO_TRANSPORT`	`MICRO_TRANSPORT=nats`	Select transport implementation
Transport Address	`MICRO_TRANSPORT_ADDRESS`	`MICRO_TRANSPORT_ADDRESS=nats://localhost:4222`	Transport endpoint
Store	`MICRO_STORE`	`MICRO_STORE=postgres`	Select store implementation
Store Database	`MICRO_STORE_DATABASE`	`MICRO_STORE_DATABASE=app`	Logical database name
Store Table	`MICRO_STORE_TABLE`	`MICRO_STORE_TABLE=records`	Default table/collection
Store Address	`MICRO_STORE_ADDRESS`	`MICRO_STORE_ADDRESS=postgres://user:pass@localhost:5432/app?sslmode=disable`	Connection string
Server Address	`MICRO_SERVER_ADDRESS`	`MICRO_SERVER_ADDRESS=:8080`	Bind address for RPC server

Example: Switching Components via Env Vars

# Use NATS for broker and transport, Consul for registry
export MICRO_BROKER=nats
export MICRO_TRANSPORT=nats
export MICRO_REGISTRY=consul
export MICRO_REGISTRY_ADDRESS=127.0.0.1:8500

# Run your service
go run main.go

No code changes required. The framework internally wires the selected implementations.

Contributing

Mon, 01 Jan 0001 00:00:00 +0000

This is a rendered copy of the repository CONTRIBUTING.md for convenient access via the documentation site.

Overview

Go Micro welcomes contributions of all kinds: code, documentation, examples, and plugins.

Quick Start

git clone https://github.com/micro/go-micro.git
cd go-micro
go mod download
go test ./...

Process

Fork and create a feature branch
Make focused changes with tests
Run linting and full test suite
Open a PR describing motivation and approach

Commit Format

Use conventional commits:

Deployment

Mon, 01 Jan 0001 00:00:00 +0000

Deploying Go Micro Services

This guide covers deploying go-micro services to a Linux server using systemd.

Overview

go-micro provides a clear workflow from development to production:

Stage	Command	Purpose
Develop	`micro run`	Local dev with hot reload and API gateway
Build	`micro build`	Compile production binaries for any target OS
Deploy	`micro deploy`	Push binaries to a remote Linux server via SSH + systemd
Dashboard	`micro server`	Optional production web UI with JWT auth and user management

Each command has a distinct role — they don’t overlap:

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Go Micro has three core abstractions:

Abstraction	What	Constructor
Service	Capability — endpoints, data, business logic	`micro.NewService("task")`
Agent	Intelligence — manages services with an LLM	`micro.NewAgent("task-mgr")`
Flow	Orchestration — event-driven LLM triggers	`micro.NewFlow("onboard")`

Prerequisites

Go 1.24+ for development. The curl install below gives you the micro binary without Go, but micro run compiles your services, so you’ll want Go installed to build them.
No LLM provider key is required for the first run below. Add an Anthropic, OpenAI, Gemini, or other provider key only when you reach the provider-backed generation and chat steps.

Install

# Binary (no Go required)
curl -fsSL https://go-micro.dev/install.sh | sh

# Or with Go
go install go-micro.dev/v6/cmd/micro@latest

If install or shell setup fails, start with Install troubleshooting to verify the binary installer or go install, PATH, micro --version, and the no-secret smoke path.

Go Micro Roadmap

Mon, 01 Jan 0001 00:00:00 +0000

Roadmap

This 2026 “AI-Native Era” roadmap has been superseded. Go Micro now has a single, current roadmap.

→ Read the roadmap

Hosting

Mon, 01 Jan 0001 00:00:00 +0000

Hosting Go Micro Services

This document outlines what hosting looks like for go-micro services, the options available today, and what an ideal hosting platform would provide.

Overview

Go Micro services are compiled Go binaries that communicate via RPC and event-driven messaging. Hosting them requires infrastructure that supports service discovery, inter-service communication, persistent storage, and configuration management. Because go-micro uses a pluggable architecture, the hosting environment can range from a single VPS to a fully orchestrated cluster.

Micro Server (Optional)

Mon, 01 Jan 0001 00:00:00 +0000

The Micro server is an optional web dashboard and authenticated API gateway for production environments. It provides a secure entrypoint for discovering and interacting with services that are already running (e.g., managed by systemd via micro deploy).

micro server does not build, run, or watch services. It only discovers services via the registry and provides a UI/API to interact with them.

micro server vs micro run

	`micro run`	`micro server`
Purpose	Local development	Production dashboard
Builds services	Yes	No
Runs services	Yes (as child processes)	No (discovers already-running services)
Hot reload	Yes	No
Authentication	Yes (default `admin`/`micro`)	Yes (default `admin`/`micro`)
Scopes	Yes (`/auth/scopes`)	Yes (`/auth/scopes`)
Dashboard	Full gateway UI with auth, scopes, agent	Full dashboard with API explorer, logs, user/token management
When to use	Day-to-day development	Deployed environments, shared servers

For local development, use micro run instead.

Model Context Protocol (MCP)

Mon, 01 Jan 0001 00:00:00 +0000

Go Micro provides built-in support for the Model Context Protocol (MCP), enabling AI agents like Claude to discover and interact with your microservices as tools.

Overview

MCP gateway automatically exposes your microservices as AI-accessible tools through:

Automatic service discovery via the registry
Dynamic tool generation from service endpoints
Stdio transport for local AI tools (Claude Code, etc.)
HTTP/SSE transport for web-based agents
Automatic documentation extraction from Go comments

Quick Start

1. Add Documentation to Your Service

Simply write Go doc comments on your handler methods:

Observability

Mon, 01 Jan 0001 00:00:00 +0000

Observability in Go Micro spans logs, metrics, and traces. The goal is rapid insight into service behavior with minimal configuration.

Core Principles

Structured Logs – Machine-parsable, leveled output
Metrics – Quantitative trends (counters, gauges, histograms)
Traces – Request flows across service boundaries
Correlation – IDs flowing through all three signals

Logging

The default logger can be replaced. Use env vars to adjust level:

Performance Considerations

Mon, 01 Jan 0001 00:00:00 +0000

Overview

go-micro is designed for developer productivity and ease of use while maintaining good performance for most use cases. This document explains the performance characteristics and trade-offs.

Reflection Usage

go-micro uses Go’s reflection package to enable its core feature: registering any Go struct as a service handler without code generation or boilerplate.

Why Reflection?

// Simple handler registration - no proto files, no code generation
type GreeterService struct{}

func (g *GreeterService) SayHello(ctx context.Context, req *Request, rsp *Response) error {
 rsp.Message = "Hello " + req.Name
 return nil
}

server.Handle(server.NewHandler(&GreeterService{}))

This simplicity is only possible with reflection. Alternative approaches (like gRPC or psrpc) require:

Plugins

Mon, 01 Jan 0001 00:00:00 +0000

Plugins are scoped under each interface directory within this repository. To use a plugin, import it directly from the corresponding interface subpackage and pass it to your service via options.

Common interfaces and locations:

Registry: go-micro.dev/v6/registry/* (e.g. consul, etcd, nats, mdns)
Broker: go-micro.dev/v6/broker/* (e.g. nats, rabbitmq, http, memory)
Transport: go-micro.dev/v6/transport/* (e.g. nats, default http)
Server: go-micro.dev/v6/server/* (e.g. grpc for native gRPC compatibility)
Client: go-micro.dev/v6/client/* (e.g. grpc for native gRPC compatibility)
Store: go-micro.dev/v6/store/* (e.g. postgres, mysql, nats-js-kv, memory)
Auth, Cache, etc. follow the same pattern under their respective directories.

Registry Examples

Consul:

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

Get up and running with go-micro in under 5 minutes.

Install

The recommended way is the precompiled binary — no Go toolchain required:

curl -fsSL https://go-micro.dev/install.sh | sh

Or, if you have Go and prefer to build from source:

go install go-micro.dev/v6/cmd/micro@latest

If the installer finishes but your shell cannot find micro, open Install troubleshooting before creating your first service.

Create Your First Service

# Create a new service
micro new helloworld
cd helloworld

# Review the generated code
ls -la

# Run locally with hot reload
micro run

# Test it
curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call \
 -H "Content-Type: application/json" \
 -d '{"name": "World"}'

Next Steps

You now have the service half of the services → agents → workflows lifecycle running locally. Keep the on-ramp going in this order:

Registry

Mon, 01 Jan 0001 00:00:00 +0000

The registry is responsible for service discovery in Go Micro. It allows services to register themselves and discover other services.

Features

Service registration and deregistration
Service lookup
Watch for changes

Implementations

Go Micro supports multiple registry backends, including:

MDNS (default)
Consul
Etcd
NATS

You can configure the registry when initializing your service.

Plugins Location

Registry plugins live in this repository under go-micro.dev/v6/registry/<plugin> (e.g., consul, etcd, nats). Import the desired package and pass it via micro.Registry(...).

Roadmap

Mon, 01 Jan 0001 00:00:00 +0000

Go Micro is a framework for building agents and services in Go. An agent is a distributed system — it discovers services, calls them, holds state, and recovers from failure — so building an agent is building a service. The roadmap has two jobs: make agentic development excellent, and make the developer experience around it excellent. Nothing else.

Where we are (v6)

The foundation is in place:

Services — register, discover, RPC, events; every endpoint is automatically an MCP tool.
Agents — a model with memory and tools that manages services, with plan, delegate, guardrails (MaxSteps, LoopLimit, ApproveTool), tool-execution middleware (WrapTool), run metadata, checkpoint/resume, and OpenTelemetry run spans built in.
Flows — durable, event-driven workflows: ordered steps that checkpoint and resume after a crash.
Interop — the MCP gateway (services as tools) and the A2A gateway (agents as agents, both directions, including A2A streaming, push notifications, and multi-turn continuation), both generated from the registry; x402 for paid tools.
Secure by default — TLS verification on, state scoped per component.

Principles

These constrain everything below:

Store

Mon, 01 Jan 0001 00:00:00 +0000

The store provides a pluggable interface for data storage in Go Micro.

Features

Key-value storage
Multiple backend support

Implementations

Supported stores include:

Memory (default)
File (go-micro.dev/v6/store/file)
MySQL (go-micro.dev/v6/store/mysql)
Postgres (go-micro.dev/v6/store/postgres)
NATS JetStream KV (go-micro.dev/v6/store/nats-js-kv)

Plugins are scoped under go-micro.dev/v6/store/<plugin>.

Configure the store in code or via environment variables.

Example Usage

Here’s how to use the store in your Go Micro service:

package main

import (
 "go-micro.dev/v6"
 "go-micro.dev/v6/store"
 "log"
)

func main() {
 service := micro.NewService("store-example")
 service.Init()

 // Write a record
 if err := store.Write(&store.Record{Key: "foo", Value: []byte("bar")}); err != nil {
 log.Fatal(err)
 }

 // Read a record
 recs, err := store.Read("foo")
 if err != nil {
 log.Fatal(err)
 }
 log.Printf("Read value: %s", string(recs[0].Value))
}

Configure a specific store in code

Postgres:

Summary: Reflection Removal Evaluation

Mon, 01 Jan 0001 00:00:00 +0000

Issue: [FEATURE] Remove reflect
Date: 2026-02-03
Status: EVALUATION COMPLETE - RECOMMENDATION AGAINST REMOVAL

Executive Summary

After comprehensive analysis of go-micro’s reflection usage and comparison with livekit/psrpc (the referenced example), we recommend AGAINST removing reflection from go-micro.

Key Findings

1. Reflection is Fundamental to go-micro’s Architecture

Reflection enables go-micro’s core value proposition:

// Simple, idiomatic Go - no proto files, no code generation
type MyService struct{}

func (s *MyService) SayHello(ctx context.Context, req *Request, rsp *Response) error {
 rsp.Message = "Hello " + req.Name
 return nil
}

server.Handle(server.NewHandler(&MyService{}))

This requires reflection. There is no way to achieve this simplicity with generics or code generation.

TLS Security Migration Guide

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Go Micro v6 verifies TLS certificates by default. This guide is for teams upgrading from v5, where TLS verification was disabled by default for backward compatibility.

Current Status (v6)

Default Behavior: TLS certificate verification is enabled by default (InsecureSkipVerify: false).

What changed from v5: v5 allowed MICRO_TLS_SECURE=true to opt into certificate verification. In v6, secure verification is the default and MICRO_TLS_SECURE is no longer used.

TLS Security Update - Important Information

Mon, 01 Jan 0001 00:00:00 +0000

What Changed

Go Micro v6 verifies TLS certificates by default. This completes the v5 security migration where verification was opt-in.

Current Behavior (v6.x)

Default: TLS certificate verification is enabled.

MICRO_TLS_SECURE was a v5 opt-in flag and is no longer used.
For local development with untrusted self-signed certificates, opt out explicitly with MICRO_TLS_INSECURE=true or an explicit insecure TLS config.

Production Recommendation

For production deployments:

Use CA-signed certificates or distribute your private CA to every host.
Remove old MICRO_TLS_SECURE settings from v5-era manifests.
Do not set MICRO_TLS_INSECURE=true in production.
Consider service mesh mTLS (Istio, Linkerd) if certificate lifecycle should be managed outside the application.

Migration Timeline

v5.x: Insecure by default, opt-in security via MICRO_TLS_SECURE=true.
v6.x current: Secure by default; use MICRO_TLS_INSECURE=true only for an explicit development opt-out.

Documentation

See SECURITY_MIGRATION.md for the detailed migration guide.

Transport

Mon, 01 Jan 0001 00:00:00 +0000

The transport layer is responsible for communication between services.

Features

Pluggable transport implementations
Secure and efficient communication

Implementations

Supported transports include:

HTTP (default)
NATS (go-micro.dev/v6/transport/nats)
gRPC (go-micro.dev/v6/transport/grpc)
Memory (go-micro.dev/v6/transport/memory)

Important: Transport vs Native gRPC

The gRPC transport uses gRPC as an underlying communication protocol, similar to how NATS or RabbitMQ might be used. It does not provide native gRPC compatibility with tools like grpcurl or standard gRPC clients generated by protoc.