Go SDK: net/http Middleware for Agent Feedback Apps

The Go SDK wraps any http.Handler with a single function call. It instruments finite JSON object and HTML responses, detects Flush calls and leaves streams completely untouched, and sends telemetry through a bounded background goroutine. It uses only the Go standard library — no external dependencies are required.

Installation

Add the module

go get github.com/open-software-network/os-epode/sdk/go

Import the package

import agentfeedback "github.com/open-software-network/os-epode/sdk/go"

Create a product key

Open the Agent Feedback dashboard, create a product, and copy the API key. Store it as AGENT_FEEDBACK_KEY in your environment.

Creating the middleware

Call agentfeedback.New with an Options struct. The function validates your API key and starts the background telemetry worker immediately.

package main

import (
    "context"
    "log"
    "net/http"
    "os"

    agentfeedback "github.com/open-software-network/os-epode/sdk/go"
)

func main() {
    feedback, err := agentfeedback.New(agentfeedback.Options{
        APIKey:  os.Getenv("AGENT_FEEDBACK_KEY"),
        Include: []string{"/search", "/docs/**"},
        CustomerRef: func(r *http.Request) string {
            return r.Header.Get("X-Account-ID")
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    defer feedback.Shutdown(context.Background())

    mux := http.NewServeMux()
    mux.HandleFunc("/search", searchHandler)

    log.Fatal(http.ListenAndServe(":8080", feedback.Middleware(mux)))
}

Options struct fields

Pass an agentfeedback.Options struct to agentfeedback.New. Only APIKey is required.

string

required

Your Agent Feedback product key. Must match the pattern af_live_<keyId>_<secret>. Store this as an environment variable.

string

Override the Agent Feedback API endpoint. Trailing slashes are trimmed automatically.

[]string

Glob-style path patterns that opt routes in. When empty, all routes are instrumented (subject to Exclude). Supports * (any path segment) and ** (any path). Example: []string{"/search", "/docs/**"}.

[]string

Glob-style patterns to skip. The default exclusion list (/health, /healthz, /metrics, /favicon.ico, /robots.txt, /_agent-feedback/*, /api/v2/outcomes) is always applied. Patterns you add here extend that list.

FeedbackMode

default:"FeedbackAuto"

Controls the feedback instruction sent to agents. Use the package constants: agentfeedback.FeedbackAuto, agentfeedback.FeedbackAsk, or agentfeedback.FeedbackOff.

func(*http.Request) string

Function that extracts an opaque customer identifier from the request. Used to group interactions by account in the dashboard.

func(*http.Request) string

Function that extracts a session identifier from the request. Links a sequence of interactions for session-level analytics.

func(*http.Request) string

Function that returns a hint about the agent runtime making the request. Used for runtime-level breakdown in the dashboard.

time.Duration

default:"500ms"

How often the background goroutine flushes telemetry events. The queue also flushes immediately when 50 events accumulate.

int

default:"1000"

Capacity of the telemetry channel. When the channel is full, the oldest event is discarded to make room for the newest.

*http.Client

Override the HTTP client used for telemetry delivery. Defaults to a client with a 3-second timeout.

func(context.Context, string, http.Header, []byte) error

Provide a custom telemetry sender for testing or proxying. When set, HTTPClient is ignored.

Stream detection

The middleware wraps http.ResponseWriter in a capture buffer. If the handler calls Flush() before finishing, the buffer is flushed directly to the underlying writer and the response is marked as streamed — instrumentation is skipped and no body buffering occurs. Streaming handlers are never blocked or modified.

Graceful shutdown

Call feedback.Shutdown(ctx) at server shutdown to drain the telemetry queue. Pass a context with a deadline to set a maximum wait time.

srv := &http.Server{Addr: ":8080", Handler: feedback.Middleware(mux)}

go func() {
    <-quit
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    _ = srv.Shutdown(ctx)
    _ = feedback.Shutdown(ctx)
}()

Agent helper functions

Import FeedbackFromResponse and SubmitProductOutcome from the same package to build a feedback-aware agent runtime that submits outcomes deterministically.

`FeedbackFromResponse`

Reads the *Envelope from an *http.Response and the response body bytes. Checks the JSON body for _agentFeedback, then the HTML body for <script id="agent-feedback">, then the Agent-Feedback response header.

resp, err := http.Get("https://api.example.com/search?q=logs")
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)

envelope, err := agentfeedback.FeedbackFromResponse(resp, body)
if err != nil {
    log.Println("no feedback contract:", err)
}

`SubmitProductOutcome`

Submits a compact outcome review to the URL embedded in the envelope. Validates the contract and enforces the allowed-origin allow-list.

result, err := agentfeedback.SubmitProductOutcome(
    context.Background(),
    envelope,
    agentfeedback.OutcomeReview{
        Outcome: "success",
        Note:    "The search returned the log entries needed to resolve the incident.",
    },
    nil,  // nil uses the default trusted origin
    nil,  // nil uses http.DefaultClient
)
if err != nil {
    log.Println("outcome submission failed:", err)
}

Pass a non-nil allowedOrigins slice only when submitting to a self-hosted Agent Feedback endpoint. The default trusted origin is https://agent-feedback-api-production.up.railway.app.

The Go SDK uses only the standard library for its middleware and agent helpers. The only HTTP call it makes is the background telemetry batch — your product response never waits for it.

Get Started

Core Concepts

SDK Guides

Agent Integration

Configuration & Tools

Go SDK: net/http Middleware for Agent Feedback Apps

Installation

Creating the middleware

Options struct fields

Stream detection

Graceful shutdown

Agent helper functions

`FeedbackFromResponse`

`SubmitProductOutcome`

​Installation

​Creating the middleware

​Options struct fields

​Stream detection

​Graceful shutdown

​Agent helper functions

​FeedbackFromResponse

​SubmitProductOutcome

Installation

Creating the middleware

Options struct fields

Stream detection

Graceful shutdown

Agent helper functions

`FeedbackFromResponse`

`SubmitProductOutcome`