> ## Documentation Index
> Fetch the complete documentation index at: https://runmirrors.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Go

> The trace collector for Go agents — you build the trace, it ships it.

`mirrorkit-go` is the Go sibling of the Python and TypeScript collectors. It does exactly one thing: take traces you hand it and send them to Mirrors — batched in the background, non-blocking, and safe (it never panics into your app after `Init`). It does **not** instrument SDKs and does **not** run agents; you build the trace, it ships it.

## Install

```bash theme={null}
go get github.com/ai-singhal/mirrorkit-go
```

Requires **Go ≥ 1.21**. Zero dependencies (standard library only).

## Usage

```go theme={null}
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"))
}
```

## Tool calls

Build tool-call and tool-result messages with the helpers:

```go theme={null}
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."),
})
```

## Options

```go theme={null}
mirrorkit.Init(mirrorkit.Options{
	APIKey:        "mk_live_...",              // required
	Project:       "my-agent",                 // default "default"
	Endpoint:      "https://api.runmirrors.com", // else MIRRORKIT_ENDPOINT / MIRROR_ENDPOINT / prod
	FlushInterval: 2 * time.Second,            // time 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)
})
```

Endpoint resolution: `Options.Endpoint` → `MIRRORKIT_ENDPOINT` → `MIRROR_ENDPOINT` → the production default.

## Lifecycle

```go theme={null}
mirrorkit.Flush(5 * time.Second)     // block until the queue drains
mirrorkit.Shutdown(5 * time.Second)  // stop the background goroutine (flushes first)
```

Prefer one collector per process via the package-level `Init` / `LogTrace` / `Flush` / `Shutdown`. For multiple independent collectors, use `NewClient` and call `LogTrace` / `Flush` / `Shutdown` on the returned `*Client`.

<Note>
  Each trace is flushed to `{endpoint}/api/collect` with `Authorization: Bearer <apiKey>` — see the [collect API reference](/api-reference/collect) for the wire format.
</Note>