go-micro

# Go Micro [![Go.Dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/go-micro.dev/v6?tab=doc)


Go Micro is an **agent harness** and service framework for Go.

## Overview

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 it, the services it depends on, and the protocols other agents use to reach it.

Go Micro gives you the harness as Go code. Build an agent and it gets a model, memory, tools, planning, delegation, guardrails, and service discovery; it is reachable over [MCP](https://modelcontextprotocol.io/) and [A2A](https://a2a-protocol.org). Write services and every endpoint becomes an AI-callable tool. Orchestrate the deterministic parts with durable flows. Agents, services, and flows share one runtime because an agent is a distributed system, and building one is building a service.

## See it

Describe a system and Go Micro designs the services, writes the handlers, compiles them, starts them, and gives you an agent to talk to:

```
$ micro run --prompt "a task management system with categories"

Services:
  ● task — Task management with status tracking
  ● project — Project organization

Generate? [Y/n]

> Create a project called Launch, then add three tasks to it

→ project_Project_Create({"name":"Launch"})
→ task_Task_Create({"title":"Design specs","project_id":"p1..."})
→ task_Task_Create({"title":"Write code","project_id":"p1..."})
→ task_Task_Create({"title":"Ship it","project_id":"p1..."})

Created project Launch and added three tasks to it.
```

And when the agent needs a capability that doesn't exist, it builds the service mid-conversation:

```
> I need to track shipping. Create a shipment for order 123 to London.

  ⚡ generating shipping service...
  ✓ shipping
  → shipping_Shipping_Create({"order_id":"123","destination":"London"})

  Created shipment for order 123 going to London.
```

The generated code is plain Go on disk — edit it by hand at any time; re-running preserves your changes. No key? The [no-secret path below](#fastest-start--no-api-key) works without any provider.

## Sponsors

<a href="https://go-micro.dev/blog/2026/05/28/atlas-cloud-sponsors-go-micro-300-ai-models-one-integration.html"><img src="https://www.atlascloud.ai/logo.svg" height="26" /></a>

**Want to support Go Micro and see your logo here?** [Become a sponsor](https://discord.gg/G8Gk5j3uXr) — reach out on Discord.

## Contents

- [Quick Start](#quick-start)
  - [First agent on-ramp](#first-agent-on-ramp)
- [Why an Agent Harness](#why-an-agent-harness)
- [Writing Services](#writing-services)
- [Building Agents](#building-agents) — [Plan & Delegate](#plan--delegate), [Pluggable](#batteries-included-pluggable), [Paid tools (x402)](#paid-tools-x402), [A2A](#reachable-by-other-agents-a2a)
- [Features](#features)
- [CLI](#cli)
- [Multi-Service Projects](#multi-service-projects)
- [Data Model](#data-model)
- [AI Providers](#ai-providers)
- [Examples](#examples)
- [Autonomous improvement loop](#autonomous-improvement-loop)
- [Community](#community)
- [Commercial Support](#commercial-support)
- [Docs](#docs)

## Quick Start

Install the CLI:

```bash
# 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 `PATH` checks fail, use the [install troubleshooting guide](internal/website/docs/guides/install-troubleshooting.md).

### Fastest start — no API key

Scaffold a service, run it, call it:

```bash
micro new helloworld
cd helloworld
micro run
```

Then in another terminal:

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

Prefer Docker? The `micro` image (Docker Hub `micro/micro` or `ghcr.io/micro/go-micro`) bundles the CLI:

```bash
docker run --rm -it micro/micro new helloworld
docker run --rm -it --network host -v "$(pwd)":/micro/helloworld micro/micro run
```

### First agent on-ramp

New to agents? The shortest path, in order — every step works without a provider key:

1. **Verify the install** — the [install troubleshooting guide](internal/website/docs/guides/install-troubleshooting.md) covers `PATH`, `micro --version`, and first-run checks. (`make docs-wayfinding` keeps these steps aligned with the installed CLI.)
2. **Run the built-in demo** — `micro agent demo` prints the provider-free first-agent walkthrough, and `micro agent quickcheck` prints the short recovery map if a step stalls; `micro examples` and `micro zero-to-hero` print the runnable examples and the one-command lifecycle harness. Start from the [smallest first-agent example](examples/first-agent/) or the [examples wayfinding index](examples/INDEX.md).
3. **Build your own** — follow [No-secret first agent](internal/website/docs/guides/no-secret-first-agent.md) (mock model, no key), then [Your First Agent](internal/website/docs/guides/your-first-agent.md), and talk to it with `micro chat`.
4. **When something's off** — `micro agent preflight` before `micro run`, `micro agent doctor` after; the [debugging guide](internal/website/docs/guides/debugging-agents.md) walks the full recovery path, and `micro inspect agent <name>` recovers run history, memory, and provider checks. The [0→hero reference](internal/website/docs/guides/zero-to-hero.md) then closes the loop — services → agents → workflows — with the maintained [support example](examples/support/) as the reference app.

### Generate from a prompt — with an LLM key

The [See it](#see-it) transcript above is real. Set a provider key and run it:

```bash
export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY, GEMINI_API_KEY, ...
micro run --prompt "a task management system with categories" --provider anthropic
```

The AI designs the architecture, you review it, then it generates handlers with real business logic, compiles them, and starts them — and the console drops you into a conversation with your running system. [Read more](https://go-micro.dev/blog/13).

## Why an Agent Harness

The first wave of agent frameworks helped developers put a model in a loop. The next problem is operating that loop: connecting it to real tools, scoping what it can touch, preserving state, routing work to specialists, recovering from failures, observing what happened, and letting other agents call it. That is harness work.

Go Micro's answer is to make the harness the same thing you already deploy:

- **Tools are services** — endpoint metadata becomes tool schema; RPC executes the call.
- **Agents are services** — they register, discover, load-balance, and expose `Agent.Chat`.
- **Workflows are durable code paths** — use flows when the path is known; dispatch to agents when it is not.
- **Safety lives at execution** — `MaxSteps`, `LoopLimit`, `ApproveTool`, and tool wrappers run where actions happen.
- **Interop is built in** — MCP for tools, A2A for agents, x402 for paid tools.

Use Go Micro when the agent has to operate a system, not just answer a prompt.

## Writing Services

Under the hood, a service is a struct with methods. Doc comments and `@example` tags become tool descriptions for AI agents automatically.

```go
package main

import (
    "context"

    "go-micro.dev/v6"
)

type Request struct {
    Name string `json:"name"`
}

type Response struct {
    Message string `json:"message"`
}

type Say struct{}

// Hello greets a person by name.
// @example {"name": "Alice"}
func (h *Say) Hello(ctx context.Context, req *Request, rsp *Response) error {
    rsp.Message = "Hello " + req.Name
    return nil
}

func main() {
    service := micro.NewService("greeter")
    service.Handle(new(Say))
    service.Run()
}
```

Run it and everything is accessible — REST, gRPC, MCP, agent playground:

```bash
micro run
# Dashboard:   http://localhost:8080
# API:         http://localhost:8080/api/{service}/{method}
# Agent:       http://localhost:8080/agent
# MCP Tools:   http://localhost:8080/mcp/tools
```

You can also scaffold a service from a template:

```bash
micro new helloworld
micro new contacts --template crud
```

## Building Agents

An Agent is a service with an LLM inside it. It has a proto-defined `Agent.Chat` RPC endpoint, registers in the registry, and is callable like any service:

```go
agent := micro.NewAgent("task-mgr",
    micro.AgentServices("task", "project"),
    micro.AgentPrompt("You manage tasks and projects. You understand deadlines and priorities."),
    micro.AgentProvider("anthropic"),
)
agent.Run()
```

The agent discovers its services from the registry, scopes its tools to their endpoints, and maintains conversation memory in the store. It registers itself so `micro chat` and other agents can find it.

```go
// Programmatic interaction
resp, _ := agent.Ask(ctx, "What tasks are overdue?")
fmt.Println(resp.Reply)
```

Multiple agents coordinate via RPC — each is a service with an `Agent.Chat` endpoint. `micro chat` routes to the right one.

```bash
micro agent list                    # list registered agents
micro call task-mgr Agent.Chat '{"message": "What tasks are overdue?"}'
```

### Plan & Delegate

Every agent gets two built-in harness capabilities, exposed as tools — no extra setup or separate graph runtime:

- **`plan`** — for multi-step work, the agent records an ordered plan in its store-backed memory and stays oriented across turns.
- **`delegate`** — the agent hands a self-contained subtask to another agent. If a registered agent already owns the relevant services, the hand-off goes over RPC to that agent; otherwise a focused, short-lived sub-agent is created for the subtask with its own isolated context.

This keeps intelligence distributed: an agent doesn't need to know *how* to do everything, only *who* does. See [examples/agent-plan-delegate](examples/agent-plan-delegate/).

```go
// A sub-agent is just an agent — created with New