chore: import upstream snapshot with attribution

internal/website/docs/ai-integration.md

@@ -0,0 +1,200 @@
+---
+layout: default
+title: 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.
+
+<img src="/images/generated/mcp-agent.jpg" alt="AI integration architecture" style="width: 100%; border-radius: 8px; margin: 1rem 0 1.5rem;" />
+
+## 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:
+
+```go
+// 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:
+
+```go
+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](https://modelcontextprotocol.io/):
+
+```go
+// One line to expose all services as AI tools
+service := micro.NewService("myservice", mcp.WithMCP(":3001"))
+```
+
+Or run it standalone:
+
+```bash
+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:
+
+```go
+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:
+
+```go
+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:
+
+```bash
+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:
+
+```go
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+# 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](/docs/mcp.html) — detailed MCP gateway guide
+- [Atlas Cloud Integration](/docs/guides/atlascloud-integration.html) — using Atlas Cloud as a provider
+- [AI Provider Guide](/docs/guides/ai-provider-guide.html) — adding new providers
+- [gRPC Interop Example](https://github.com/micro/go-micro/tree/master/examples/grpc-interop) — calling go-micro from standard gRPC clients