micro--go-micro/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Go Micro

Go Micro 是一个面向 Go 的 agent harness（智能体运行时框架） 与服务框架。

社区： 有问题、有想法，或想与我们一起构建？加入 Discord.

Harness 是围绕智能体的运行时：它能调用的工具、它保留的记忆、约束它的护栏、触发它的工作流、它依赖的服务，以及其他智能体与之通信所使用的协议。

Go Micro 以 Go 代码的形式提供该 harness。构建一个智能体即可获得模型、记忆、工具、规划、委派、护栏与服务发现；可通过 MCP 和 A2A. 被访问。编写服务后，每个端点都会成为 AI 可调用的工具。用持久化 flow 编排确定性部分。智能体、服务与 flow 共享同一运行时，因为智能体本质上是一个分布式系统，构建智能体就是在构建服务。

赞助商

     

想支持 Go Micro 并在此展示你的 logo？ 成为赞助商 — 可通过 Discord 联系。

商业支持

要在生产环境运行 Go Micro，或基于它进行开发并需要帮助？可直接向维护者购买 支持、咨询、培训与 retainer（长期服务） — 这些也是项目得以持续维护的支撑。详见 Support 中的层级说明，或 提交请求.

目录

• 快速开始
  • 首个智能体入门路径
• 为何需要 Agent Harness
• 编写服务
• 构建智能体 — 规划与委派、可插拔、付费工具 (x402)、A2A
• 功能特性
• CLI
• 自主改进循环
• 多服务项目
• 数据模型
• AI 提供商
• 示例
• 商业支持
• 文档

快速开始

安装 CLI：

# 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

如果安装或 PATH 检查失败，在搭建第一个服务之前，请先参阅 安装故障排除指南。

最快上手 — 无需 API key

搭建服务、运行并调用：

micro new helloworld
cd helloworld
micro run

然后在另一个终端中：

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

这条 安装 → 搭建 → 运行 → 调用 路径由无密钥 CI harness 覆盖。若要在无网络访问或提供商密钥的情况下，仅验证本地安装器与首次运行 CLI 边界，请使用：

make install-smoke

若要验证聚焦的 CLI 内循环契约 — 搭建 → 运行/聊天/检查 → 部署 dry-run — 请使用：

make inner-loop

若仅运行 CI 守护的有序 0→hero 服务 → 智能体 → 工作流 脚本，请使用：

make zero-to-hero-transcript

若要运行更广泛的本地契约（包括该脚本、聊天/检查 CLI 边界以及部署 dry-run），请使用：

make harness

首个智能体入门路径

完成安装并进行首次 micro new/micro run 冒烟检查后，按以下顺序走可逐步跟进的智能体路径：

1. 安装故障排除 — 在开始智能体相关工作前，验证二进制安装器或 go install、PATH、micro --version，以及无密钥冒烟路径。

运行 make docs-wayfinding 以验证聚焦的无密钥 docs/CLI 契约，确保本 README 与网站命令与已安装的 CLI 保持一致。

2. micro agent demo — 从已安装的 CLI 打印无需提供商的首个智能体演示命令及后续文档步骤。
3. micro agent quickcheck（或 micro agent debug）— 当 搭建 → 运行 → 聊天 → 检查 流程卡住时，在深入完整调试指南前，先打印简短恢复路线图。
4. micro examples — 按可复制/粘贴顺序打印维护中的、无需提供商的可运行示例。
5. micro zero-to-hero — 打印维护中的一条命令无密钥生命周期 harness 与可运行示例。
6. 示例导航索引 — 从一张地图中选择最小的无密钥首个智能体示例、维护中的 0→hero 支持参考，以及后续互操作示例。
7. 最小首个智能体示例 — 使用 mock 模型且无需提供商密钥，运行一个由服务支撑的智能体。
8. 无密钥首个智能体脚本 — 使用 mock 模型运行维护中的支持智能体，在无密钥情况下见证 服务 → 智能体 → 工作流 成功。
9. 你的第一个智能体 — 构建一个由服务支撑的智能体，并通过 micro chat 与之对话。
10. 调试你的智能体 — 在 micro run 之前使用 micro agent preflight，在 micro run 之后使用 micro agent doctor， 然后使用 micro chat 和 micro inspect agent <name> 恢复运行历史、记忆 以及提供商检查，以应对首次对话出现意外行为的情况。
11. 0→hero 参考 — 通过与服务维护 harness 一致的 搭建、运行、聊天、检查、flow 历史与部署 dry-run 命令，完成 服务 → 智能体 → 工作流 循环。

自主改进循环

想将同样的 服务 → 智能体 → 工作流 生命周期应用到你的仓库？micro loop 会搭建 Go Micro 自身使用的自主改进循环：North Star、排序后的问题队列、角色提示词、GitHub Actions 工作流，以及面向 CI 门禁 PR 的验证。

micro loop init --roles all
micro loop verify

在启用定时任务之前，请配置 dispatch token，例如 CODEX_TRIGGER_TOKEN，用必需的 CI 检查保护默认分支 （对本仓库为 go build ./...、go test ./... 和 golangci-lint run ./...）， 并在每个增量中为 .github/loop/PRIORITIES.md 填入一个范围明确的问题。设置清单与运行模型请参阅 micro loop 快速开始。

通过提示词生成 — 需要 LLM key

设置提供商密钥，描述你的需求，AI 会设计服务、编写 handler、编译并启动它们：

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

AI 设计架构，你进行评审，随后它会生成包含真实业务逻辑的 handler、编译并启动：

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

Generate? [Y/n]

Micro
  Services:
    ● task
    ● project
  Agents:
    ◆ agent

然后在控制台中与你的服务对话：

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

→ project_Project_Create({"name":"Launch"})
← {"record":{"id":"p1..."},"success":true}
→ 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.

当你需要尚不存在的能力时，代理会在对话过程中生成一项新服务：

> 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"})
  ← {"record":{"id":"xyz...","status":"pending"}}

  Created shipment for order 123 going to London.

你可以随时手动编辑生成的代码——重新运行会保留你的修改。了解更多.

为何需要 Agent Harness

第一波代理框架帮助开发者让模型进入循环。下一个问题是如何运营这个循环：将其连接到真实工具、限定可触及范围、保留状态、将工作路由给专家、从故障中恢复、观测发生了什么，并让其他代理调用它。这就是 harness 工作。

Go Micro 的答案是：让 harness 与你已部署的东西合二为一：

• 工具即服务 — 端点元数据成为工具 schema；RPC 执行调用。
• 代理即服务 — 它们注册、发现、负载均衡，并暴露 Agent.Chat。
• 工作流即持久化代码路径 — 路径已知时使用 flows；未知时分派给代理。
• 安全落在执行层 — MaxSteps、LoopLimit、ApproveTool 以及工具包装器在动作发生处运行。
• 互操作内置 — 工具用 MCP，代理用 A2A，付费工具用 x402。

当代理需要操作系统而不仅是回答提示时，使用 Go Micro。

编写服务

底层而言，服务是带方法的 struct。文档注释和 @example 标签会自动成为 AI 代理的工具描述。

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()
}

运行后一切皆可访问——REST、gRPC、MCP、agent playground：

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

你也可以从模板脚手架生成服务：

micro new helloworld
micro new contacts --template crud

构建代理

代理是内置 LLM 的服务。它拥有 proto 定义的 Agent.Chat RPC 端点，在 registry 中注册，并可像任何服务一样被调用：

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()

代理从 registry 发现其服务，将工具限定到对应端点，并在 store 中维护对话记忆。它会自我注册，以便 micro chat 及其他代理能找到它。

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

多个代理通过 RPC 协调——每个都是带有 Agent.Chat 端点的服务。micro chat 会路由到正确的那一个。

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

规划与委托（Plan & Delegate）

每个代理都具备两种内置 harness 能力，以工具形式暴露——无需额外设置或独立的图运行时：

• plan — 对于多步骤工作，代理在其 store 支撑的记忆中记录有序计划，并在多轮对话中保持方向。
• delegate — 代理将自包含的子任务交给另一个代理。若已注册的代理已拥有相关服务，则通过 RPC 交接给该代理；否则会为该子任务创建一个专注、短命的子代理，并配备独立隔离的上下文。

这让智能保持分布式：代理不必知道如何完成一切，只需知道谁来做。参见 examples/agent-plan-delegate。

// A sub-agent is just an agent — created with New, talked to with Ask.
// delegate-first: reuse a registered agent, or spin up a focused one.
resp, _ := agent.Ask(ctx, "Plan the launch, create the tasks, and have comms notify the owner.")

开箱即用，可插拔

正如服务组合可插拔抽象（registry、broker、store），代理组合 model、memory 和 tools——开箱即用的合理默认，每一项都可替换。

agent := micro.NewAgent("assistant",
    micro.AgentProvider("anthropic"),                 // model — swap the provider
    micro.AgentCompactMemory(40, 12),                 // memory — durable, summarized, recallable
    micro.AgentTool("weather", "Get the weather for a city",
        map[string]any{"city": map[string]any{"type": "string"}},
        func(ctx context.Context, in map[string]any) (string, error) {
            return getWeather(in["city"].(string))    // tools beyond your services — any function
        }),
    micro.AgentMaxSteps(8),                            // guardrails
)

Memory（记忆） 默认持久且由 store 支撑（Postgres、NATS KV 或 file），因此代理在重启后可从上次停下的地方继续——也可用 AgentMemory 提供你自己的实现。长期运行的代理可选用 AgentCompactMemory(maxMessages, keepRecent)：较早轮次被折叠为确定性摘要，最近轮次保持原文，相关归档轮次在未来请求时被召回，而无需重放整段对话。Tools（工具） 自动就是你的服务，加上你用 AgentTool 注册的任何函数。

付费工具（x402）

每个端点都是 AI 可调用的工具——而且可以是付费工具。Go Micro 支持 x402, 面向代理的 HTTP 402 支付标准，因此工具可要求稳定币支付，代理可自主结算。这是可选功能，框架本身不携带加密货币逻辑：验证委托给可插拔的 facilitator（Coinbase、Alchemy、自托管），因此 Base 和 Solana 只是不同的 facilitator。

# Charge for tool calls at the MCP gateway (off unless you set a pay-to address)
micro mcp serve --x402_pay_to 0xYourAddress --x402_network solana --x402_amount 10000
# Per-tool amounts via a config file
micro mcp serve --x402_config x402.json

参见 Payments (x402) guide。

可被其他代理访问（A2A）

在 Go Micro 系统内，代理通过 RPC 相互访问。要让其他框架上的代理也能访问它们，Go Micro 使用 Agent2Agent (A2A) protocol. A2A 网关从 registry 发现你的代理，根据其元数据为每个代理生成 Agent Card——与 MCP 网关从服务端点派生工具的方式相同——并将传入的 A2A 任务翻译为代理的 Agent.Chat RPC。无需为每个代理编写代码：注册代理即可通过 A2A 访问。

micro a2a serve --address :4000    # gateway: expose every registered agent over A2A
micro a2a list                     # agents and their Agent Card URLs

或者完全跳过网关——代理可直接提供自己的 A2A 端点，在进程内处理任务：

micro.NewAgent("task-mgr", micro.AgentServices("task"), micro.AgentA2A(":4000"))

双向皆可。要调用其他框架上的代理，a2a.Client 会接入两处交接工作的地方：作为工作流步骤的 flow.A2A(url)（跨框架的 Dispatch），以及从代理内部向 http(s) URL 发起的 delegate。

MCP 将你的服务暴露为工具；A2A 将你的代理暴露为代理。参见 A2A guide。

功能特性

AI

功能	详情
Agents（智能体）	micro.NewAgent() — 管理服务的智能层
Plan & delegate（规划与委派）	内置 agent 工具 — 规划多步骤工作，将子任务委派给其他 agent
Pluggable memory（可插拔记忆）	默认基于持久化存储的对话记忆；可通过 AgentMemory 替换
Custom tools（自定义工具）	AgentTool — 为 agent 提供除服务之外的任意函数作为工具
Guardrails（护栏）	MaxSteps（按次数停止）、LoopLimit（停止重复的无进展调用）、ApproveTool（human-in-the-loop，人在回路）
Tool middleware（工具中间件）	AgentWrapTool — 包装工具执行以实现日志、指标或重试（类似 client/server wrappers）
Workflows（工作流）	micro.NewFlow() — 事件驱动；单步、有序持久化步骤，或触发 agent
Durable execution（持久化执行）	带检查点的流程步骤可在崩溃后存活并从停止处恢复；默认基于存储，后端可插拔
MCP gateway	每个 endpoint 自动成为 AI 工具
A2A gateway	每个 agent 均可通过 Agent2Agent 协议访问；卡片由 registry（micro a2a）生成
Payments (x402)	通过 x402 标准按调用选择性为工具付费；facilitator 可插拔（Base、Solana 等）
9 个 LLM 提供商	Anthropic、OpenAI、Gemini、Groq、Mistral、Together、Atlas Cloud、MiniMax、Ollama（本地 + 云端）
Interactive console（交互式控制台）	micro run 包含与服务对话的聊天控制台
Service generation（服务生成）	micro run --prompt — 描述系统即可获得运行中的服务

框架

功能	详情
Service registry（服务注册）	mDNS（默认）、Consul、etcd
RPC client/server	gRPC 传输、负载均衡、流式传输
Pub/sub events（发布/订阅事件）	NATS、RabbitMQ、HTTP broker
Key-value store（键值存储）	File (bbolt)、Postgres、NATS KV
Typed model layer（类型化模型层）	CRUD + 查询，SQLite/Postgres 后端
Everything swappable（一切皆可替换）	所有抽象均为 Go interface

开发者体验与部署

功能	详情
Hot reload（热重载）	micro run 监听文件变更并重新构建
Templates（模板）	micro new --template crud/pubsub/api
One-command deploy（一键部署）	micro deploy user@server — SSH + systemd，无需 Docker

CLI

命令	用途
micro run --prompt "..."	生成服务与 agent，并启动交互式控制台
micro run	开发模式：热重载、gateway、交互式控制台
micro run -d	分离模式（无控制台）
micro chat	独立聊天（未使用 micro run 时）
micro agent list	列出已注册的 agent
micro new myservice	脚手架生成服务
micro call service endpoint '{}'	从 CLI 调用服务或 agent
micro build	编译生产二进制文件
micro deploy user@server	通过 SSH + systemd 部署

多服务项目

同时运行多个服务：

users := micro.NewService("users", micro.Address(":9001"))
orders := micro.NewService("orders", micro.Address(":9002"))

users.Handle(new(Users))
orders.Handle(new(Orders))

g := micro.NewGroup(users, orders)
g.Run()

或使用 micro.mu 配置文件：

service users
    path ./users

service orders
    path ./orders
    depends users

数据模型

类型化持久化，支持 CRUD 与查询：

type User struct {
    ID    string `json:"id" model:"key"`
    Name  string `json:"name"`
    Email string `json:"email" model:"index"`
}

db := service.Model()
db.Register(&User{})
db.Create(ctx, &User{ID: "1", Name: "Alice", Email: "alice@example.com"})

var results []*User
db.List(ctx, &results, model.Where("email", "alice@example.com"))

后端：memory（默认）、SQLite、Postgres。

AI 提供商

单次 import 即可切换提供商 — 各处使用相同 interface：

提供商	默认模型
Anthropic	claude-sonnet-4-20250514
OpenAI	gpt-4o
Google Gemini	gemini-2.5-flash
Groq	llama-3.3-70b-versatile
Mistral	mistral-large-latest
Together AI	meta-llama/Llama-3.3-70B-Instruct-Turbo
Atlas Cloud	deepseek-ai/DeepSeek-V3-0324
MiniMax	MiniMax-M3
Ollama	llama3.2 (local)

m := ai.New("anthropic", ai.WithAPIKey(key))
resp, _ := m.Generate(ctx, &ai.Request{Prompt: "hello"})

示例

初次接触 agent？请跟随 first-agent on-ramp，然后使用 examples index 查看完整的 services → agents → workflows 映射。

• hello-world — 基础 RPC 服务
• multi-service — 单个二进制文件中运行多个服务
• mcp — 与 AI agent 的 MCP 集成
• first-agent — 最小化、无需 provider 的服务支撑型 agent
• agent-plan-delegate — Agent 规划与多 agent 委派
• agent-durable — 检查点与恢复 agent 运行，无需重放已完成的工具副作用
• grpc-interop — 从任意 gRPC 客户端调用 go-micro

查看 all examples。

文档

• 入门指南
• AI 集成
• 你的第一个 Agent
• 0→hero 参考
• Agent 与工作流
• Agent 设计
• 规划与委派
• Agent 护栏
• 支付（x402）
• MCP 与 AI Agent
• 数据模型
• 部署
• 插件

包参考：https://pkg.go.dev/go-micro.dev/v6