GoogleCloudPlatform / GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK
Add SDK tracing producers for OpenAI Agents and Claude Agent SDK
- 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
Assessment
This issue has not been assessed yet.