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

# Go SDK Quickstart

> Start here for the WhyOps Go module: create the client, initialize the agent, send your first trace event, and then move into proxy transport.

The Go SDK is optimized for backend services that want strongly typed runtime telemetry plus a reusable transport for provider requests. This page is the basic setup path.

<CardGroup cols={3}>
  <Card title="Proxy Transport" icon="plug" href="/integrations/go-sdk-proxy">
    Read this next if you want OpenAI or Anthropic traffic to go through WhyOps using `ProxyHTTPClient()`.
  </Card>

  <Card title="Runtime Events" icon="diagram-project" href="/integrations/go-sdk-runtime">
    Add tool spans, prompt-caching usage, hybrid patterns, and self-hosted settings.
  </Card>

  <Card title="SDK Overview" icon="box-open" href="/integrations/sdk-packages">
    Compare Go with the TypeScript and Python packages.
  </Card>
</CardGroup>

## Before you start

| You need                                  | Why                                                                            |
| ----------------------------------------- | ------------------------------------------------------------------------------ |
| `WHYOPS_API_KEY`                          | Authenticates agent init, manual events, and proxied model traffic to WhyOps   |
| A stable `AgentName`                      | Keeps proxy traffic and runtime events attached to the same agent identity     |
| `AgentMetadata` with `SystemPrompt`       | Lets WhyOps version the agent and show the correct configuration in the UI     |
| Your provider key in the WhyOps dashboard | Lets WhyOps authenticate upstream when it forwards OpenAI or Anthropic traffic |

## 1. Install the module

<Tabs>
  <Tab title="go get">
    ```bash theme={null}
    go get github.com/whyops-org/whyops-op/packages/sdk-go@latest
    ```
  </Tab>

  <Tab title="Module path">
    ```txt theme={null}
    github.com/whyops-org/whyops-op/packages/sdk-go
    ```
  </Tab>
</Tabs>

## 2. Create the WhyOps client once

```go theme={null}
package main

import whyops "github.com/whyops-org/whyops-op/packages/sdk-go"

var sdk = whyops.New(whyops.Config{
	APIKey:    os.Getenv("WHYOPS_API_KEY"),
	AgentName: "customer-support-agent",
	AgentMetadata: whyops.AgentMetadata{
		SystemPrompt: "You are a precise customer support assistant.",
		Description:  "Handles support, billing, and order status flows.",
		Tools: []whyops.AgentTool{
			{
				Name:         "search_orders",
				Description:  "Look up order state by ID",
				InputSchema:  `{"type":"object","properties":{"orderId":{"type":"string"}},"required":["orderId"]}`,
				OutputSchema: `{"type":"object","properties":{"status":{"type":"string"}}}`,
			},
		},
	},
})
```

<Callout type="warning" title="Set `SystemPrompt` and keep `Tools` explicit">
  If the agent has tools, include them in `AgentMetadata.Tools`. If it has no tools, using an empty slice keeps the registered definition unambiguous.
</Callout>

## 3. Initialize the agent during startup

```go theme={null}
info := sdk.InitAgent(ctx)
_ = info
```

You do not have to call this manually because trace methods initialize on first event, but early registration is the better default because configuration problems fail before live traffic.

## 4. Send your first runtime event

<Tabs>
  <Tab title="User message">
    ```go theme={null}
    trace := sdk.Trace("session-123")

    _ = trace.UserMessage(ctx, []whyops.MessageItem{
    	{Role: "user", Content: "Reset my password."},
    }, whyops.UserMessageOptions{})
    ```
  </Tab>

  <Tab title="LLM response">
    ```go theme={null}
    trace := sdk.Trace("session-123")

    _ = trace.LLMResponse(ctx, "openai/gpt-4o-mini", "openai", "I can help with that.", whyops.LLMResponseOptions{
    	LatencyMs:    420,
    	FinishReason: "stop",
    	Usage: &whyops.TokenUsage{
    		PromptTokens:     42,
    		CompletionTokens: 16,
    		TotalTokens:      58,
    	},
    })
    ```
  </Tab>
</Tabs>

## 5. Move to proxy transport or richer runtime tracing

<CardGroup cols={2}>
  <Card title="Go SDK Proxy Transport" icon="plug" href="/integrations/go-sdk-proxy">
    Learn the Go-specific proxy flow: `ProxyHTTPClient()` injects headers only, so your provider client must still point at the WhyOps proxy host.
  </Card>

  <Card title="Go SDK Runtime Events" icon="terminal" href="/integrations/go-sdk-runtime">
    Add tool spans, prompt-caching usage, hybrid patterns, self-hosted overrides, and a full method map.
  </Card>
</CardGroup>