go-micro/internal/website/docs/getting-started.md

layout

layout
default

Getting Started

Go Micro has three core abstractions:

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

Install

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

# Or with Go
go install go-micro.dev/v5/cmd/micro@v5.25.0

Quick Start: Generate from a Prompt

Describe what you need. The AI designs services, writes handlers, compiles, and starts them:

micro run --prompt "task management system"

You'll see the design, confirm, and services + agent start:

Services:
  ● task — Core task management
  ● project — Project organization

Generate? [Y/n]

Micro
  Services:
    ● task
    ● project
  Agents:
    ◆ agent

The interactive console lets you talk to your services immediately:

> Create a project called Launch, then add a task called 'Write docs'

→ project_Project_Create({"name":"Launch"})
← {"record":{"id":"p1..."},"success":true}
→ task_Task_Create({"title":"Write docs","project_id":"p1..."})

Created project Launch and added task 'Write docs' to it.

The console discovers services from the registry and orchestrates across them via the agent. Use micro run -d for detached mode without the console, or micro chat as a standalone command.

Quick Start: Write a Service

Create and run a service manually:

micro new helloworld
cd helloworld
micro run

Open http://localhost:8080 to see the dashboard, call endpoints, and chat with your service.

A service is a Go struct with methods. Doc comments and @example tags become tool descriptions for AI agents:

package main

import "go-micro.dev/v5"

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.New("greeter")
    service.Handle(new(Say))
    service.Run()
}

micro run gives you:

• Dashboard at http://localhost:8080
• API Gateway at http://localhost:8080/api/{service}/{method}
• Agent Playground at http://localhost:8080/agent
• MCP Tools at http://localhost:8080/mcp/tools
• Hot Reload — auto-rebuild on file changes

Templates are available for common patterns:

micro new contacts --template crud
micro new events --template pubsub
micro new gateway --template api

Building Agents

An Agent is an intelligent layer that manages one or more services:

package main

import "go-micro.dev/v5"

func main() {
    agent := micro.NewAgent("task-mgr",
        micro.AgentServices("task", "project"),
        micro.AgentPrompt("You manage tasks and projects. You understand deadlines, priorities, and assignments."),
        micro.AgentProvider("anthropic"),
        micro.AgentAPIKey("sk-ant-..."),
    )
    agent.Run()
}

An agent is a service — it has a proto-defined Agent.Chat RPC endpoint and registers in the registry like everything else. It:

• Discovers its services from the registry
• Only sees endpoints from its assigned services (scoped tools)
• Maintains conversation memory in the store (persists across restarts)
• Is callable via micro call, the interactive console, or any go-micro client

Use it programmatically:

resp, _ := agent.Ask(ctx, "What tasks are overdue for Alice?")
fmt.Println(resp.Reply)

Or via the CLI:

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

When multiple agents are registered, the console routes to the right agent automatically.

Event-Driven Flows

A Flow subscribes to a broker topic and triggers an LLM when events arrive. You can define flows in code or run them from the CLI.

In code:

f := micro.NewFlow("onboard-user",
    micro.FlowTrigger("events.user.created"),
    micro.FlowPrompt("New user created: {{.Data}}. Send welcome email and create workspace."),
    micro.FlowProvider("anthropic"),
    micro.FlowAPIKey(os.Getenv("MICRO_AI_API_KEY")),
)
f.Register(service.Options().Registry, service.Options().Broker, service.Client())

From the CLI:

micro flow run --trigger events.user.created --prompt "New user: {{.Data}}. Send welcome email."
micro flow exec --prompt "Summarize all open tickets and email the report."

The flow discovers all services as tools and lets the LLM decide which RPCs to call in response to the event.

CLI Workflow

Command	Purpose
micro run --prompt "..."	Generate services + agent, start with interactive console
micro run	Dev mode: hot reload, gateway, interactive console
micro run -d	Detached mode (no console)
micro chat	Standalone chat (when not using micro run)
micro agent list	List registered agents
micro flow run --trigger <topic>	Run an event-driven flow
micro flow exec --prompt "..."	Execute a one-shot flow
micro new myservice	Scaffold a service
micro call service endpoint '{}'	Call a service or agent
micro build	Compile production binaries
micro deploy user@server	Deploy via SSH + systemd

Next Steps

• AI Integration — how services, agents, MCP, and LLMs fit together
• Agent Design — the full agent interface specification
• MCP & AI Agents — MCP gateway, tool discovery, and auth
• Data Model — typed persistence with CRUD and queries
• Deployment — deploy via SSH + systemd