google/adk-go plugin/agentanalytics/v0.1.0

plugin/agentanalytics v0.1.0

on GitHub

The first release of the BigQuery Agent Analytics plugin for ADK Go. It logs every agent run to a BigQuery table, so you can query and dashboard agent behavior with SQL: invocations, model requests and responses, tool calls, state changes, agent transfers and human-in-the-loop requests.

The table schema, event type names and analytics views match adk-python's BigQuery Agent Analytics plugin, so Go and Python agents can write to the same table and be queried together.

Install

go get google.golang.org/adk/plugin/agentanalytics@v0.1.0

Requires google.golang.org/adk/v2 v2.0.0 or later.

Quick start

analytics, err := agentanalytics.NewBigQueryAgentAnalyticsPlugin(ctx, "my-project", "agent_analytics", "agent_events")
if err != nil {
	log.Fatal(err)
}
defer analytics.Close() // flushes queued rows to BigQuery

r, err := runner.New(runner.Config{
	AppName:        "my-app",
	Agent:          myAgent,
	SessionService: session.InMemoryService(),
	PluginConfig:   runner.PluginConfig{Plugins: []*plugin.Plugin{analytics}},
})

Call Close before the process exits, so that rows still in the queue are written.

What's included

• Ready to query out of the box. The plugin creates the events table if it is missing, adds new columns to an existing table, and creates 25 per-event views such as v_llm_request and v_tool_completed.
• Batched, non-blocking writes through the BigQuery Storage Write API, 100 rows or 1 second per batch by default. Batches over 8 MiB are split so that a single large batch is not rejected as a whole.
• Redaction on by default. Values under keys like api_key, password and token, credentials in URLs, and Authorization, Bearer and Basic credentials are replaced with [REDACTED]. Text values longer than 512,000 characters are truncated unless CaptureFullMessageContent is set.
• Control over what is logged: event allow and deny lists, a payload column deny list, a ContentFormatter hook to transform or redact payloads before they are written, custom tags, and an allow list for CustomMetadata keys.
• Cloud Storage offload (optional). Set GCSBucketName to store large text and binary parts in a bucket and keep a reference in the row.
• Exactly-once delivery (optional). ExactlyOnceDelivery writes through a committed stream with explicit offsets, so retries do not write rows twice.
• Drop counters. DropStats reports rows lost to a full queue, failed writes or shutdown.
• OpenTelemetry correlation (optional). EnableOTelCorrelation adds the current trace and span IDs to each row.

See the package documentation for every option.

Before you use it

• This is a pre-1.0 release. The exported API may still change before v1.0.0, including helpers such as BatchProcessor, FormatContentParts, SmartTruncate and ArrowSchema. The path to v1.0.0 is tracked in #2014.
• Register it before plugins that replace results. ADK stops at the first plugin callback that returns a replacement event, model response or tool result, so the analytics plugin does not see what an earlier plugin replaced.
• Known differences from adk-python are listed in #2046 and #2047. For example, when a callback recovers a failed tool call, Go logs TOOL_ERROR followed by TOOL_COMPLETED, while Python logs only TOOL_ERROR.