GoogleCloudPlatform / GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK

adk-2.0 producer: emit attributes.adk.scope with v15 derivation rule

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

Description

Parent tracker: #190 (v15 contract).
Wave: 2 — Producer event rows.
Blocked by: #194 (EventData source-event plumbing).

## Contract — derivation order matters (v15)

The raw `Event.isolation_scope` is **internal** in ADK and not a stable public API. The producer emits a normalized `attributes.adk.scope`:

1. Raw value is `None` → `scope = null` (do not emit `{id, kind}` at all). This is the **single canonical** unscoped form.
2. **Node-run shape**: `name@` (bare) or `/@` (full path, emitted by task-mode workflows per `workflow/_workflow.py::_compute_isolation_scope_for_node`) → `kind = node_run`.
3. **Function-call default**: any non-empty string that didn't match step 2 → `kind = function_call`. **Do not depend on prefix shape** (`adk-...`, `call_...`, `toolu_...`, etc.) — ADK only generates `adk-` prefixes when an ID is missing in `flows/llm_flows/functions.py:180`, and model-provided IDs from the FC delegation path (`workflow/_llm_agent_wrapper.py:135`) can use any provider-native format.
4. Empty string / non-string anomalies → `kind = unknown` with a producer-side warning log.

No `root` kind — current ADK has no explicit root marker.

## Acceptance

- [ ] `attributes.adk.scope = null` for unscoped rows (single canonical form).
- [ ] Full-path node scope `/@` → `kind = node_run`.
- [ ] **Bare** node scope `name@` → `kind = node_run` (not `function_call`; v4 bug guard).
- [ ] ADK-generated `adk-...` function-call ID → `kind = function_call`.
- [ ] **Model-provided non-`adk-` function-call ID** (`call_abc123`, `toolu_xyz`) → `kind = function_call` (v10 bug guard, no prefix dependence).
- [ ] Anomalous input (e.g. empty string) → `kind = unknown` with a warning log.
- [ ] `SDK.md` documents that raw ADK `isolation_scope` is internal/unstable and not part of the public contract.

## References

- #190 (v15 producer §2; v11 derivation order; v11 fixture requirements).
- `src/google/adk/workflow/_workflow.py::_compute_isolation_scope_for_node`.
- `src/google/adk/workflow/_llm_agent_wrapper.py:135` (`override_isolation_scope=fc.id`).
- `src/google/adk/flows/llm_flows/functions.py:180` (`adk-` ID generation).

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.