Guides on Go Micro

`micro loop` quickstart

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

micro loop scaffolds the autonomous improvement loop that Go Micro uses on this repository: GitHub Actions workflows for planning, building, evaluation feedback, coherence, security, and release. Use it when you want a repository to continuously turn a ranked queue into small PRs while CI remains the merge gate.

1. Initialize the loop

Run the default loop from the repository root:

micro loop init

For every role used by Go Micro itself, scaffold all workflows:

0→hero reference path

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

The 0→hero path is the maintained, no-secret reference for the Go Micro services → agents → workflows lifecycle. It ties the CLI inner loop and the runtime harness together so a contributor can prove the framework still works as one system, not as separate demos.

Use it when you want to answer: “Can I scaffold a service, run it locally, talk to an agent, inspect durable work, and reach the deployment boundary without cloud credentials?”

Adding an AI Provider to Go Micro

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

This guide walks you through implementing a new AI model provider for go-micro’s ai package. After following these steps your provider will be available via ai.New("yourprovider") and automatically usable by the MCP gateway, the agent playground, and any service that calls service.Model().

Overview

The ai package uses the same plugin pattern as the rest of go-micro: define an interface, register an implementation, and let users swap providers with a single import. All providers live under ai/<name>/.

Agent Guardrails

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

An autonomous agent decides its own actions at runtime, which is what makes it useful — and what makes it risky. The common failure modes are mundane: it loops, repeating the same call without making progress; it runs away, taking far more steps (and cost) than the task warrants; it takes an action that should have had a human or a policy in the way.

Go Micro separates orchestration (the model deciding what to do) from execution safety (whether a decided action is allowed to run). Every tool call an agent makes passes through one choke point, and that’s where the guardrails live — so they apply uniformly to service calls, custom tools, and delegate, without touching the model or your services.

Agent Integration Patterns

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

This guide covers common patterns for integrating AI agents with Go Micro services, from single-agent workflows to multi-agent architectures.

Pattern 1: Single Agent with Multiple Services

The simplest and most common pattern. One AI agent has access to multiple microservices as MCP tools.

User → AI Agent → MCP Gateway → [Service A, Service B, Service C]

Setup

Run multiple services and expose them all through one MCP gateway:

Agent Loops

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

Most agent work is one-shot: a prompt goes in, an answer comes out. The next step in agentic systems is the loop — run a step over and over, letting the agent keep working until the goal is met instead of stopping after one pass. One agent improves an architecture while another removes duplicated abstractions, both opening pull requests continuously; a draft is refined until it’s good enough; a build is fixed and re-run until it’s green.

Agent2Agent (A2A)

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

Go Micro speaks the Agent2Agent (A2A) protocol — the open standard for agents on different frameworks to discover and call each other over HTTP. The A2A gateway is the agent-side analogue of the MCP gateway: MCP exposes your services as tools, A2A exposes your agents as agents.

There is nothing to add to an agent. An agent already registers in the registry with type=agent metadata; the gateway discovers it, generates an Agent Card from that metadata, and translates incoming A2A tasks to the agent’s existing Agent.Chat RPC — the same call delegate and flows use.

Agents and Workflows

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

Go Micro’s AI primitives map directly onto the taxonomy in Anthropic’s Building Effective Agents. That post draws one distinction that matters:

Workflows — “LLMs and tools orchestrated through predefined code paths.” Deterministic.
Agents — “LLMs dynamically direct their own processes and tool usage.” Model-driven.

Go Micro has both, plus the harness they run inside — and expresses them as plain services and tools, with no graph DSL. That’s deliberate: the same post advises finding “the simplest solution possible” and being “cautious with frameworks… they obscure the underlying mechanics.”

Atlas Cloud Integration

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

Atlas Cloud Integration Guide

Atlas Cloud is an enterprise AI infrastructure platform offering 300+ models across text, image, and video through a unified, OpenAI-compatible API. It is an official Go Micro sponsor and a first-class provider in the ai package.

Quick Start

Install or update Go Micro:

go get go-micro.dev/v6@latest

Import the Atlas Cloud provider and use it:

package main

import (
 "context"
 "fmt"
 "log"

 "go-micro.dev/v6/ai"
 _ "go-micro.dev/v6/ai/atlascloud"
)

func main() {
 m := ai.New("atlascloud",
 ai.WithAPIKey("your-atlas-cloud-key"),
 )

 resp, err := m.Generate(context.Background(), &ai.Request{
 Prompt: "What is Go Micro?",
 SystemPrompt: "You are a helpful assistant.",
 })
 if err != nil {
 log.Fatal(err)
 }

 fmt.Println(resp.Reply)
}

Configuration

Options

Option	Default	Description
`ai.WithAPIKey(key)`	required	Your Atlas Cloud API key
`ai.WithModel(name)`	`llama-3.3-70b`	Model to use (see Model Selection)
`ai.WithBaseURL(url)`	`https://api.atlascloud.ai`	API base URL

Environment Variables

The micro chat CLI and micro run / micro server read configuration from environment variables:

Best Practices for Tool Descriptions

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

Your Go doc comments become the documentation that AI agents read when deciding how to call your service. Better descriptions lead to fewer errors, faster task completion, and a better user experience.

How Agents Use Your Docs

When an AI agent receives a user request like “create a task for Alice”, it:

Queries the MCP tools endpoint for available tools
Reads each tool’s description to understand what it does
Reads the parameter schema and descriptions to build the input
References the example to verify the format
Makes the call

If any of these are missing or unclear, the agent guesses — and often guesses wrong.

Building AI-Native Services

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

This guide walks you through building a Go Micro service that is AI-native from the start — meaning AI agents can discover, understand, and call your service automatically via the Model Context Protocol (MCP).

What You’ll Build

A task management service with full CRUD operations that:

Exposes every endpoint as an MCP tool automatically
Has rich documentation that agents can read
Includes auth scopes for write operations
Works with Claude Code, the agent playground, and any MCP client

Prerequisites

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

Step 1: Create the Service

micro new tasks
cd tasks

Step 2: Define Your Types

Design your request/response types with description tags. These tags become parameter descriptions that agents read:

CLI & Gateway Guide

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

The Go Micro CLI provides two gateway modes for accessing your microservices: development (micro run) and production (micro server). Both use the same underlying gateway architecture, ensuring consistent behavior across environments.

Overview

 ┌─────────────────────┐
 │ HTTP Requests │
 └──────────┬──────────┘
 │
 ┌──────────▼──────────┐
 │ Unified Gateway │
 │ │
 │ • Service Discovery│
 │ • HTTP → RPC │
 │ • Web Dashboard │
 │ • Health Checks │
 └──────────┬──────────┘
 │
 ┌──────────▼──────────┐
 │ Your Services │
 │ (via Registry) │
 └─────────────────────┘

Quick Comparison

Feature	`micro run`	`micro server`
Purpose	Local development	Production API gateway
Authentication	Yes (default `admin`/`micro`)	Yes (default `admin`/`micro`)
Process Management	Yes (builds & runs services)	No (services run separately)
Hot Reload	Yes (watches file changes)	No
Endpoint Scopes	Yes (`/auth/scopes`)	Yes (`/auth/scopes`)
Best For	Coding, testing, iteration	Deployed environments

Development Mode: `micro run`

Quick Start

# Create and run a service
micro new myservice
cd myservice
micro run

Open http://localhost:8080 - no login required!

Contributing

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

Overview

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

Quick Start

git clone --depth 1 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:

feat(registry): add consul health check
fix(broker): prevent reconnect storm

Testing

Run unit tests:

Debugging your agent

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

Debugging your agent

Use this guide when an agent surprises you: it answered without using a service, called the wrong endpoint, looped, lost memory, refused a tool, or behaved differently when a flow handed work to it. The local inner loop is:

micro run # start services, agents, gateway, dashboard
micro chat # reproduce one turn
micro inspect ... # read the recorded run or workflow history

Debug the lifecycle in the same order Go Micro runs it: first prove the service is registered and callable, then inspect the agent run that chose tools, then inspect any workflow that handed off to the agent.

Deployment Guide

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

This is a quick reference for deploying go-micro services. For the full guide, see the Deployment documentation.

Workflow

micro run → Develop locally with hot reload
micro build → Compile production binaries
micro deploy → Push to a remote Linux server via SSH + systemd
micro server → Optional: production web dashboard with auth

Quick Start

# Build binaries for Linux
micro build --os linux

# Deploy to server (builds automatically if needed)
micro deploy user@your-server

First-Time Server Setup

On your server (any Linux with systemd):

Error Handling for AI Agents

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

Error Handling for AI Agents

When AI agents call your services through MCP, they need to understand errors well enough to recover or inform the user. This guide covers how to write services that give agents useful error information.

Use Typed Errors

Go Micro’s errors package provides structured errors that the MCP gateway forwards to agents with status codes and detail messages.

import "go-micro.dev/v6/errors"

func (s *Users) Get(ctx context.Context, req *GetRequest, rsp *GetResponse) error {
 if req.ID == "" {
 return errors.BadRequest("users.Get", "id is required")
 }

 user, err := s.db.FindUser(req.ID)
 if err != nil {
 return errors.NotFound("users.Get", "user %s not found", req.ID)
 }

 rsp.User = user
 return nil
}

Agents receive structured error responses like:

Framework Comparison

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

How Go Micro compares to other Go microservices frameworks.

Quick Comparison

Feature	Go Micro	go-kit	gRPC	Dapr
Learning Curve	Low	High	Medium	Medium
Boilerplate	Low	High	Medium	Low
Plugin System	Built-in	External	Limited	Sidecar
Service Discovery	Yes (mDNS, Consul, etc)	No (BYO)	No	Yes
Load Balancing	Client-side	No	No	Sidecar
Pub/Sub	Yes	No	No	Yes
Transport	HTTP, gRPC, NATS	BYO	gRPC only	HTTP, gRPC
Zero-config Dev	Yes (mDNS)	No	No	No (needs sidecar)
Production Ready	Yes	Yes	Yes	Yes
Language	Go only	Go only	Multi-language	Multi-language

vs go-kit

go-kit Philosophy

“Just a toolkit” - minimal opinions
Compose your own framework
Maximum flexibility
Requires more decisions upfront

Go Micro Philosophy

“Batteries included” - opinionated defaults
Swap components as needed
Progressive complexity
Get started fast, customize later

When to Choose go-kit

You want complete control over architecture
You have strong opinions about structure
You’re building a custom framework
You prefer explicit over implicit

When to Choose Go Micro

You want to start coding immediately
You prefer conventions over decisions
You want built-in service discovery
You need pub/sub messaging

Code Comparison

go-kit (requires more setup):

Health Checks

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

The health package provides health check functionality for microservices, including Kubernetes-style liveness and readiness probes.

Quick Start

import "go-micro.dev/v6/health"

func main() {
 // Register health checks
 health.Register("database", health.PingCheck(db.Ping))
 health.Register("cache", health.TCPCheck("localhost:6379", time.Second))
 
 // Add health endpoints
 mux := http.NewServeMux()
 health.RegisterHandlers(mux) // Registers /health, /health/live, /health/ready
 
 http.ListenAndServe(":8080", mux)
}

Endpoints

Endpoint	Purpose	Returns 200 when
`/health`	Overall health status	All critical checks pass
`/health/live`	Kubernetes liveness probe	Service is running
`/health/ready`	Kubernetes readiness probe	All critical checks pass

Response Format

{
 "status": "up",
 "checks": [
 {
 "name": "database",
 "status": "up",
 "duration": 1234567
 },
 {
 "name": "cache",
 "status": "up", 
 "duration": 567890
 }
 ],
 "info": {
 "go_version": "go1.22.0",
 "go_os": "linux",
 "go_arch": "amd64",
 "version": "1.0.0"
 }
}

When unhealthy:

Install troubleshooting

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

Install troubleshooting

Use this page before micro new or micro agent demo when the CLI install is unclear. The goal is to prove three boundaries in order: the micro binary is on PATH, it is the version you expected, and the no-secret first-run path works without provider keys.

1. Choose one install path

Binary installer (no Go required to install)

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

Use this when you want the released micro binary without building it yourself. The generated services still need a Go toolchain when you run micro run, but the installer itself does not require Go.

MCP Security Guide

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

This guide covers how to secure your MCP gateway for production use, including authentication, per-tool scopes, rate limiting, and audit logging.

Overview

The MCP gateway provides four layers of security:

Authentication - Verify the caller’s identity via bearer tokens
Scopes - Control which tools each token can access
Rate Limiting - Prevent abuse with per-tool rate limits
Audit Logging - Record every tool call for compliance and debugging

Authentication

Bearer Token Auth

The MCP gateway uses bearer token authentication. Tokens are validated by the configured auth.Auth provider.

MCP Troubleshooting

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

MCP Troubleshooting

Common issues when using the MCP gateway and AI agents with Go Micro services.

Agent Can’t Find My Tools

Symptom: Agent says “no tools available” or doesn’t list your service endpoints.

Check 1: Is the service registered?

# List registered services
micro services

If your service isn’t listed, it hasn’t registered with the registry. Make sure your service is running and using the same registry as the MCP gateway.

micro run - Local Development

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

micro run provides a complete development environment for Go microservices.

Note: This guide focuses on micro run features. For a comparison with micro server and gateway architecture details, see the CLI & Gateway Guide.

Quick Start

micro new helloworld
cd helloworld
micro run

Open http://localhost:8080 to see your service.

What You Get

When you run micro run, you get:

URL	Description
http://localhost:8080	Web dashboard - browse and call services
http://localhost:8080/agent	Agent playground - AI chat with MCP tools
http://localhost:8080/api	API explorer - browse endpoints and schemas
http://localhost:8080/api/{service}/{method}	API gateway - HTTP to RPC proxy
http://localhost:8080/mcp/tools	MCP tools - list all services as AI tools
http://localhost:8080/auth/tokens	Token management - create and manage API tokens
http://localhost:8080/auth/scopes	Scope management - restrict endpoint access
http://localhost:8080/auth/users	User management - create and manage users
http://localhost:8080/health	Health checks - aggregated service health
http://localhost:8080/services	Service list - JSON

Plus:

Native gRPC Compatibility

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

This guide explains how to make your Go Micro services compatible with native gRPC clients like grpcurl, grpcui, or clients generated by the standard protoc gRPC plugin in any language.

Understanding Transport vs Server

Go Micro has two different gRPC-related concepts that are often confused:

gRPC Transport (`go-micro.dev/v6/transport/grpc`)

The gRPC transport uses the gRPC protocol as a communication layer, similar to how you might use NATS, RabbitMQ, or HTTP. It does not guarantee compatibility with native gRPC clients.

No-secret first-agent transcript

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

This is the fastest first-agent success path when you do not have a provider key handy. It starts from the maintained examples/support app and uses the repository harness that CI already runs: real Go Micro services, registry, broker, client, store, agent loop, flow handoff, and guardrail code with only the LLM provider mocked.

Use it before the live-provider Your First Agent walkthrough when you want to see the services → agents → workflows lifecycle run end to end with no secrets.

Payments (x402)

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

Go Micro can require a payment before a tool runs, using x402 — the open HTTP 402 Payment Required standard for stablecoin payments, designed for AI agents and onchain APIs. It lets every Go Micro endpoint, already exposed as an AI-callable tool, become a paid tool: a service answers a call with 402 and payment requirements, the client pays and retries, and the gateway verifies the payment before serving.

Payments are opt-in and dependency-light. Go Micro carries no chain or crypto code — it speaks the protocol and delegates verification and settlement to a pluggable facilitator (Coinbase CDP, Alchemy, or self-hosted), so Base and Solana are just different facilitators behind one interface.

Plan & Delegate

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

Every Go Micro agent has two built-in capabilities, on top of the service tools it discovers:

plan — record an ordered plan in memory before doing multi-step work.
delegate — hand a self-contained subtask to another agent.

They are exposed to the model as ordinary tools. There is no separate graph runtime to configure — these harness capabilities are tools, and the agent calls them the same way it calls a service endpoint. They are added automatically to every agent, so you don’t wire anything up. micro chat exposes them too, so you get planning and delegation even when talking to your services directly.

Provider Conformance Matrix

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

Go Micro treats model providers as interchangeable pieces of the same agent harness: services expose tools, agents reason over them, and workflows stitch the work together. The conformance harness keeps that promise honest by running the same deterministic services → agents → workflows scenarios against every configured provider.

The live harness is in internal/harness/provider-conformance. It skips providers without API keys by default, so it is safe to run locally, and it fails when any configured provider breaks the shared contract.

Quick Start

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

Install

go install go-micro.dev/v5/cmd/micro@v5.16.0

Note: Use a specific version instead of @latest to avoid module path conflicts. See releases for the latest version.

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

Full Tutorial - In-depth guide
Examples - Learn by example
API Reference - Complete API docs
Deployment - Deploy to production

Common Patterns

RPC Service

package main

import "go-micro.dev/v5"

type Greeter struct{}

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

func main() {
 service := micro.New("greeter")
 service.Handle(new(Greeter))
 service.Run()
}

Pub/Sub Event Handler

import "go-micro.dev/v5"

func main() {
 service := micro.New("subscriber")
 
 // Subscribe to events
 micro.RegisterSubscriber("user.created", service.Server(), 
 func(ctx context.Context, event *UserCreatedEvent) error {
 log.Infof("User created: %s", event.Email)
 return nil
 },
 )
 
 service.Run()
}

Publishing Events

publisher := micro.NewEvent("user.created", client)
publisher.Publish(ctx, &UserCreatedEvent{
 Email: "user@example.com",
})

Get Help

Discord Community - Chat with other users
GitHub Issues - Report bugs or request features
Documentation - Complete docs

Testing Micro Services

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

The testing package provides utilities for testing micro services in isolation.

Quick Start

import (
 "testing"
 "go-micro.dev/v6/test"
)

func TestGreeter(t *testing.T) {
 h := test.NewHarness(t)
 defer h.Stop()

 h.Name("greeter").Register(new(GreeterHandler))
 h.Start()

 var rsp HelloResponse
 err := h.Call("GreeterHandler.Hello", &HelloRequest{Name: "World"}, &rsp)
 if err != nil {
 t.Fatal(err)
 }

 if rsp.Message != "Hello World" {
 t.Errorf("expected 'Hello World', got '%s'", rsp.Message)
 }
}

How It Works

The harness creates isolated instances of:

The Agent Harness

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

The first wave of agent frameworks solved one problem: put a model in a loop with some tools. The harder problem is operating that loop — and that’s what a harness is.

A harness is the runtime around an agent:

the tools it can call,
the memory it keeps,
the guardrails that bound it,
the workflows that trigger and structure it,
the state that survives a restart,
the observability to see what it did,
the services it depends on,
and the protocols other agents use to reach it.

Go Micro’s bet is that this runtime is the one you already deploy. An agent is a service with a model inside; the harness is the distributed-systems machinery services already have. So you don’t bolt a separate orchestration product onto your stack — the harness is the stack.

Your First Agent

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

This walkthrough builds the smallest useful Go Micro agent path: one service with typed endpoints, one agent scoped to that service, and one CLI conversation that proves the agent can use the service as a tool. It is the 0→1 version of the services → agents → workflows lifecycle: build capability first, add intelligence on top, then keep a clear path toward flows when the work needs to run on events or schedules.

Guides on Go Micro

`micro loop` quickstart

1. Initialize the loop

0→hero reference path

Adding an AI Provider to Go Micro

Overview

Agent Guardrails

Agent Integration Patterns

Pattern 1: Single Agent with Multiple Services

Setup

Agent Loops

Agent2Agent (A2A)

Agents and Workflows

Atlas Cloud Integration

Atlas Cloud Integration Guide

Quick Start

Configuration

Options

Environment Variables

Best Practices for Tool Descriptions

How Agents Use Your Docs

Building AI-Native Services

What You’ll Build

Prerequisites

Step 1: Create the Service

Step 2: Define Your Types

CLI & Gateway Guide

Overview

Quick Comparison

Development Mode: micro run

Quick Start

Contributing

Overview

Quick Start

Process

Commit Format

Testing

Debugging your agent

Debugging your agent

Deployment Guide

Workflow

Quick Start

First-Time Server Setup

Error Handling for AI Agents

Error Handling for AI Agents

Use Typed Errors

Framework Comparison

Quick Comparison

vs go-kit

go-kit Philosophy

Go Micro Philosophy

When to Choose go-kit

When to Choose Go Micro

Code Comparison

Health Checks

Quick Start

Endpoints

Response Format

Install troubleshooting

Install troubleshooting

1. Choose one install path

Binary installer (no Go required to install)

MCP Security Guide

Overview

Authentication

Bearer Token Auth

MCP Troubleshooting

MCP Troubleshooting

Agent Can’t Find My Tools

micro run - Local Development

Quick Start

What You Get

Native gRPC Compatibility

Understanding Transport vs Server

gRPC Transport (go-micro.dev/v6/transport/grpc)

No-secret first-agent transcript

Payments (x402)

Plan & Delegate

Provider Conformance Matrix

Quick Start

Development Mode: `micro run`

gRPC Transport (`go-micro.dev/v6/transport/grpc`)