Mirrors

mirrorkit（Go）

面向 LLM Agent 的轻量级、可直接替换使用的生产级追踪收集器——Python mirrorkit 和 TypeScript mirrorkit（npm）包的 Go 版本。

它只做一件事：接收你提供的追踪记录，并将其发送到你的 Mirrors 后端——在后台批量发送，不阻塞，且安全（调用 Init 后绝不会导致你的应用发生 panic）。它不会检测 SDK，也不会运行 Agent；追踪记录由你构建，它负责发送。

安装

go get github.com/ai-singhal/mirrorkit-go

需要 Go ≥ 1.21。零依赖（仅使用标准库）。

用法

package main

import (
	"time"

	mirrorkit "github.com/ai-singhal/mirrorkit-go"
)

func main() {
	mirrorkit.Init(mirrorkit.Options{APIKey: "mk_live_...", Project: "my-agent"})
	defer mirrorkit.Shutdown(5 * time.Second)

	mirrorkit.LogTrace([]mirrorkit.Message{
		mirrorkit.SystemMessage("You are a helpful assistant."),
		mirrorkit.UserMessage("What's the weather in Paris?"),
		mirrorkit.AssistantMessage("It's 18C and sunny."),
	}, mirrorkit.WithModel("claude-opus-4-8"))
}

每条追踪记录都会排入队列，并由后台 goroutine 刷新至 {endpoint}/api/collect（Authorization: Bearer <apiKey>，请求体为 {project, traces}）。

工具调用

使用辅助函数构建工具调用和工具结果消息：

mirrorkit.LogTrace([]mirrorkit.Message{
	mirrorkit.UserMessage("Cancel booking BK-4471."),
	mirrorkit.AssistantToolCalls(
		mirrorkit.NewToolCall("call_1", "cancel_booking", map[string]any{"id": "BK-4471"}),
	),
	mirrorkit.ToolResult("call_1", `{"status":"cancelled"}`),
	mirrorkit.AssistantMessage("Done — BK-4471 is cancelled."),
})

选项

mirrorkit.Init(mirrorkit.Options{
	APIKey:        "mk_live_...",           // required
	Project:       "my-agent",              // default "default"
	Endpoint:      "https://api.mirror.dev", // else MIRRORKIT_ENDPOINT / MIRROR_ENDPOINT / prod
	FlushInterval: 2 * time.Second,         // ms between background flushes
	MaxBatch:      50,                      // max traces per POST
	MaxQueue:      10_000,                  // in-memory cap; oldest dropped past this
	Debug:         false,                   // internal debug logs (or MIRRORKIT_DEBUG=1)
})

端点解析顺序：Options.Endpoint → MIRRORKIT_ENDPOINT → MIRROR_ENDPOINT → 生产环境默认值。

生命周期

mirrorkit.Flush(5 * time.Second)     // block until the queue drains
mirrorkit.Shutdown(5 * time.Second)  // stop the background goroutine (flushes first)

建议每个进程使用一个收集器，通过包级别的 Init / LogTrace / Flush / Shutdown 操作。若需要多个相互独立的收集器，请使用 NewClient，并在返回的 *Client 上调用 LogTrace / Flush / Shutdown。

测试

cd mirrorkit-go && go vet ./... && go test ./...