GoogleCloudPlatform / GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK

Add SDK tracing producers for OpenAI Agents and Claude Agent SDK

Open
#235 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
47
Forks
21
Avg merge
2d 13h
Merged PRs (30d)
33

Description

## Context

Issue #234 tracks distribution of the tracing package and Claude Code plugin. This issue tracks the SDK-facing producer adapters that should live in `producers/` after the shared writer/drainer scaffold from #232 lands.

The goal is to let Python users instrument SDK-based agents directly, without going through CLI wrappers or Claude Code hooks.

Related: #229, #232, #234.

## Goals

- Add an OpenAI Agents SDK tracing producer surface.
- Add a Claude Agent SDK tracing producer/loading surface.
- Reuse the shared `bigquery_agent_analytics_tracing` config, schema, logger, writer identity, spool, and drainer code.
- Preserve the canonical `agent_events` row shape and existing event mapping semantics.
- Keep producer identity in `attributes.writer.*` and source-specific metadata under non-reserved keys.

## Proposed work

1. OpenAI Agents SDK producer
- Add a module such as `bigquery_agent_analytics_tracing.openai_agents`.
- Port the existing OpenAI Agents trace processor behavior.
- Preserve span mapping:
- generation spans -> `LLM_REQUEST` / `LLM_RESPONSE`
- function spans -> `TOOL_STARTING` / `TOOL_COMPLETED`
- other spans -> `STATE_DELTA` where applicable
- Preserve default agent/source semantics, including `openai-agents` / `openai_agents_sdk` style attribution where currently used.
- Expose a small public helper/API for registering the processor with OpenAI Agents SDK.
- Keep BigQuery writes async/spooled through the shared logger.

2. Claude Agent SDK producer/loading path
- Add a module such as `bigquery_agent_analytics_tracing.claude_agent_sdk`.
- Port the existing Claude Agent SDK helper/loading behavior.
- Preserve default agent/source semantics, including `claude-agent-sdk` style attribution where currently used.
- Reuse the shared logger and avoid duplicating writer/drainer code.
- Keep compatibility with the Claude Code plugin path where the SDK helper is loaded from the plugin artifact, if applicable.

3. Packaging
- Keep base package dependencies minimal.
- Use extras for SDK-specific dependencies:
- `openai-agents` for OpenAI Agents SDK support.
- `claude-sdk` for Claude Agent SDK support.
- Do not make either SDK dependency required for users who only need Claude Code or Codex producers.

4. Tests
- Add unit tests using fakes/mocks so CI does not need live SDK calls or BigQuery access.
- Cover span/event mapping for OpenAI Agents SDK.
- Cover Claude Agent SDK loading/helper behavior.
- Cover disabled tracing via `BQAA_TRACE_ENABLED=false`.
- Cover writer attribution and source metadata.
- Cover malformed/minimal SDK payloads without crashing the host agent.

## Acceptance criteria

- OpenAI Agents SDK users can register the BQAA trace processor and emit canonical `agent_events` rows.
- Claude Agent SDK users can load/use the BQAA helper and emit canonical `agent_events` rows.
- SDK-specific dependencies are optional extras, not base requirements.
- No new top-level BigQuery columns are introduced.
- `attributes.writer` remains package-owned and queryable for adoption analytics.
- SDK producer tests pass in Producers CI across supported Python versions.
- The adapters do not emit ADK-only event types in v0.1.

## Non-goals

- No Claude Code plugin artifact or marketplace submission work here; that remains in #234.
- No Codex CLI wrapper work here; track that separately or under the broader producer migration issue.
- No PyPI publish workflow changes here unless they are required only to validate extras installation.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.