GoogleCloudPlatform / GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK
adk-2.0 producer: emit attributes.adk.scope with v15 derivation rule
- 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
Assessment
This issue has not been assessed yet.