micro--go-micro/internal/website/docs/ai-integration.md

layout, title

layout	title
default	AI Integration

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.

Layer by Layer

1. Services (your code)

Write normal Go handlers. Add doc comments for AI tool descriptions:

// CreateUser creates a new user account.
// @example {"name": "Alice", "email": "alice@example.com"}
func (h *Users) CreateUser(ctx context.Context, req *pb.CreateRequest, rsp *pb.CreateResponse) error {
    // your business logic
}

The doc comment becomes the tool description. The @example tag gives the LLM a usage hint. No AI-specific code in your handler.

2. Registry (service discovery)

Services register automatically. The registry is the source of truth for what's running:

service := micro.NewService("users")
service.Handle(handler.New())
service.Run() // registers with the registry

Pluggable: mDNS (default, zero config), Consul, etcd, NATS.

3. MCP Gateway (services → tools)

The MCP gateway walks the registry and exposes every endpoint as a tool via the Model Context Protocol:

// One line to expose all services as AI tools
service := micro.NewService("myservice", mcp.WithMCP(":3001"))

Or run it standalone:

micro mcp serve              # stdio for Claude Code
micro mcp serve --address :3000  # HTTP for web agents

Any MCP-compatible agent (Claude Code, ChatGPT, custom agents) can discover and call your services.

4. ai.Tools (discover + execute)

ai.Tools turns registered services into LLM-callable tools — discovery plus RPC execution in one type:

tools := ai.NewTools(service.Registry())
discovered, _ := tools.Discover()  // []ai.Tool from all registered services

// Wire execution into a model with one option:
m := ai.New("anthropic", ai.WithAPIKey(key), ai.WithTools(tools))

This is what powers micro chat and the agent playground. You can use it directly in your own services to build agentic workflows.

5. ai.Model (LLM providers)

The ai package provides a pluggable interface for calling LLMs:

import (
    "go-micro.dev/v6/ai"
    _ "go-micro.dev/v6/ai/anthropic"
)

m := ai.New("anthropic", ai.WithAPIKey(key))
resp, _ := m.Generate(ctx, &ai.Request{
    Prompt: "What users are in the system?",
    Tools:  discovered,  // from ai.Tools
})

Seven text providers, two image providers, one video provider. Same interface, swap with an import.

Provider	Text	Image	Video
Anthropic	yes
OpenAI	yes	yes
Google Gemini	yes
Atlas Cloud	yes	yes	yes
Groq	yes
Mistral	yes
Together AI	yes

6. micro chat (orchestration)

The CLI ties it all together — discovers services, builds the tool list, and lets you talk to your services:

ANTHROPIC_API_KEY=sk-ant-... micro chat --provider anthropic
> list all users
> send a welcome email to alice@example.com
> create an order for product-42

Multi-turn conversation with ai.History — the model remembers context across turns. Type reset to clear history.

7. micro flow (event-driven orchestration)

Subscribe to broker events and let an LLM orchestrate the response:

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

f := flow.New("onboard",
    flow.Trigger("events.user.created"),
    flow.Prompt("New user: {{.Data}}. Send welcome email and create workspace."),
    flow.Provider("anthropic"),
    flow.APIKey(key),
)
f.Register(service.Registry(), service.Options().Broker, service.Client())

Or from the CLI:

micro flow run --trigger events.user.created \
  --prompt "New user: {{.Data}}. Send welcome email." \
  --provider anthropic

micro flow exec --prompt "List all users" --provider anthropic

8. micro api (HTTP gateway)

A standalone HTTP-to-RPC gateway for exposing services over HTTP without the full dashboard:

micro api                    # listen on :8080
micro api --address :3000    # custom port

# Call services through the gateway
curl -XPOST -d '{"name":"Alice"}' http://localhost:8080/greeter/Greeter.Hello

What You Don't Need

• No agent framework — the building blocks compose; you don't need a LangChain or CrewAI equivalent
• No special handler code — your services are normal Go handlers with doc comments
• No API key to use MCP — external agents bring their own models; your services just expose tools
• No vendor lock-in — every provider implements the same interface; swap with one import

Getting Started

The fastest path:

# Create a service with MCP enabled
micro new myservice --template crud
cd myservice

# Run it
micro run

# Chat with it
ANTHROPIC_API_KEY=sk-ant-... micro chat --provider anthropic
> list all records

See also:

• MCP Documentation — detailed MCP gateway guide
• Atlas Cloud Integration — using Atlas Cloud as a provider
• AI Provider Guide — adding new providers
• gRPC Interop Example — calling go-micro from standard gRPC clients