Mirrors

mirrorkit (Go)

LLM エージェント向けの軽量な、そのまま置き換えて使える本番用トレースコレクターです。Python の mirrorkit および TypeScript の mirrorkit（npm）パッケージの Go 版です。

機能はひとつだけです。渡されたトレースを受け取り、Mirrors バックエンドに送信します。バックグラウンドでバッチ処理し、ノンブロッキングで安全に動作します（Init の実行後にアプリ内でパニックが発生することはありません）。SDK を計測することも、エージェントを実行することもありません。トレースはご自身で作成し、このパッケージが送信します。

インストール

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

各トレースはキューに追加され、バックグラウンドのゴルーチンによって {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 ./...