agentmon/internal/sdk

Agentmon SDK

The agentmon SDK provides a Go client for sending telemetry events to the agentmon backend.

Installation

go get agentmon/internal/sdk

Quick Start

package main

import (
    "context"
    "log"

    "agentmon/internal/sdk"
)

func main() {
    emitter, err := sdk.NewEmitter(sdk.Config{
        ServerURL:  "http://localhost:8080",
        Framework:  "my-agent",
        ClientID:   "my-client-001",
        Host:       "localhost",
        BufferSize: 100,
    })
    if err != nil {
        log.Fatal(err)
    }
    defer emitter.Close(context.Background())

    ctx := context.Background()
    sessionID := "session-123"

    // Start a session
    sessionStart := sdk.NewSessionStart(sessionID, sdk.WithSource(emitter))
    if err := emitter.Emit(ctx, sessionStart); err != nil {
        log.Printf("Error: %v", err)
    }

    // ... do work ...

    // End the session
    sessionEnd := sdk.NewSessionEnd(sessionID, sdk.WithSource(emitter))
    if err := emitter.Emit(ctx, sessionEnd); err != nil {
        log.Printf("Error: %v", err)
    }

    // Flush buffered events
    if err := emitter.Flush(ctx); err != nil {
        log.Printf("Error: %v", err)
    }
}

Configuration

The Config struct configures the emitter:

Field	Type	Required	Default	Description
ServerURL	string	Yes	-	URL of the ingest gateway (e.g., http://localhost:8080)
APIKey	string	No	-	Optional API key for authentication
Framework	string	Yes	-	Name of the framework (e.g., opencode, claude-code)
ClientID	string	Yes	-	Stable identifier for this emitter instance
Host	string	No	localhost	Hostname where events originate
BufferSize	int	No	100	Max number of events to buffer before flushing
UseWebSocket	bool	No	false	Enable WebSocket streaming mode
EnableLogging	bool	No	false	Enable debug logging

Event Types

Session Events

// Start a session
sessionStart := sdk.NewSessionStart(sessionID,
    sdk.WithSource(emitter),
    sdk.WithAttributes(map[string]any{
        "cwd": "/home/user/project",
        "repo": "myrepo",
        "branch": "main",
    }),
)

// End a session
sessionEnd := sdk.NewSessionEnd(sessionID,
    sdk.WithSource(emitter),
)

Run Events

// Start a run
runStart := sdk.NewRunStart(sessionID, runID,
    sdk.WithSource(emitter),
    sdk.WithAttributes(map[string]any{
        "command": "my-command",
        "agent": "my-agent",
    }),
)

// End a run
runEnd := sdk.NewRunEnd(sessionID, runID, "success", 60000,
    sdk.WithSource(emitter),
    sdk.WithLLMUsage("claude-3-opus", 1000, 500, 0.015),
)

Span Events

// Start a span
spanStart := sdk.NewSpanStart(sessionID, runID, traceID, spanID,
    sdk.WithSource(emitter),
    sdk.WithSpanKind("tool"),
    sdk.WithName("Bash"),
    sdk.WithAttributes(map[string]any{
        "command": "echo hello",
    }),
)

// End a span
spanEnd := sdk.NewSpanEnd(sessionID, runID, traceID, spanID, "success", 1000,
    sdk.WithSource(emitter),
    sdk.WithSpanKind("tool"),
    sdk.WithName("Bash"),
)

Error Events

errEvent := sdk.NewError(sessionID, runID, traceID, spanID,
    "validation", "invalid input",
    sdk.WithSource(emitter),
    sdk.WithErrorDetails("VAL001", false),
)

Metric Snapshots

metrics := sdk.NewMetricSnapshot(sessionID, runID, map[string]any{
    "tokens_in":  1000.0,
    "tokens_out": 500.0,
    "cost_usd":   0.015,
    "latency_ms": 300.0,
    "error_count": 0,
})

Event Options

Event options are functions that modify events before sending:

• WithSource(emitter) - Add source information (framework, client_id, host)
• WithAttributes(attrs) - Add arbitrary attributes
• WithSpanKind(kind) - Set the span_kind attribute (llm, tool, skill, internal)
• WithName(name) - Set the name attribute
• WithParentSpanID(parentID) - Set the parent span ID
• WithPayload(payload) - Set custom payload
• WithSeq(seq) - Set sequence number (for WebSocket mode)
• WithLLMUsage(model, inTokens, outTokens, costUSD) - Add LLM usage to run.end or span.end
• WithErrorDetails(code, retryable) - Add error details

Span Kinds

Common span kinds:

• llm - LLM API calls
• tool - Tool/function calls
• skill - Skill execution
• internal - Internal operations

WebSocket Mode

For real-time streaming, enable WebSocket mode:

emitter, err := sdk.NewEmitter(sdk.Config{
    ServerURL:    "http://localhost:8080",
    Framework:    "my-agent",
    ClientID:     "my-client-001",
    Host:         "localhost",
    UseWebSocket: true,
})

In WebSocket mode, events are sent immediately rather than buffered.

Example

See examples/sdk-example/main.go for a complete example.

Testing

Run tests with:

go test ./internal/sdk/...

License

Same license as the agentmon project.