docs(examples): lineage tutorial — data-source refs + agent version on traces

[max-parke-scale]

New sync tutorial 00_sync/080_lineage: the first agent that exercises the lineage capture surface shipped in 0.25.0 (#469), so the provenance is visible in real traces instead of only in SDK unit tests.

What it demonstrates

• All three sgp.lineage.refs capture forms: @data_sources with static refs (search_filings), an argument resolver (read_kpi — ref derived from the table argument, nothing recorded when it's absent), and register_tool_sources for an unowned MCP-style tool (company_profile).
• __agent_version__ on every span, from the AGENT_VERSION env var. Nothing wires that var today (deploy-chart wiring is still open), so the tutorial sets it via a Dockerfile build arg and documents .env for local runs.
• Same harness wiring as 050_openai_agents (OpenAITurn → UnifiedEmitter), so refs resolve through the harness tracer path.

Verified live on sgp-dev

Ran the agent against sgp-dev (trace lineage-demo-8fe657d30fa3, account 68754be7ac3f41b875f912a1). Every tool span carries its declared refs, e.g. read_kpi:

"metadata": {
  "__source__": "agentex", "__acp_type__": "sync",
  "__agent_name__": "s080-lineage", "__agent_version__": "0.1.0-demo",
  "sgp.lineage.refs": [{"name": "main.kpi.revenue", "role": "input",
                        "namespace": "databricks://demo-workspace.cloud.databricks.com"}]
}

POST /v5/spans/search with {"extra_metadata": {"__agent_version__": "0.1.0-demo"}} returns exactly the run's 4 spans — first live confirmation of the filterability #469's description asserted.

The offline test verifies the three capture forms resolve under the tool names the harness sees; CI runs it in-image like the other tutorials.

🧑‍💻🤖 — posted via Claude Code

Greptile Summary

This PR adds a synchronous lineage tutorial demonstrating static, resolver-derived, and registered data-source references together with agent-version trace metadata. The attempted agent-version fallback correction still does not distinguish ordinary unlabeled builds.

• Adds an OpenAI Agents-based ACP tutorial and three lineage-reference capture forms.
• Adds offline lineage-resolution tests and container/build configuration.
• Documents local and container-based agent-version configuration.

Confidence Score: 4/5

The PR is not yet safe to merge because unlabeled builds still collapse distinct agent versions into the same trace identity.

The default build and deployment path does not inject an image tag or Git SHA, so the constant unversioned fallback continues to prevent traces from being attributed to the build that produced them.

Files Needing Attention: examples/tutorials/00_sync/080_lineage/Dockerfile

Important Files Changed

Filename	Overview
examples/tutorials/00_sync/080_lineage/Dockerfile	Builds the tutorial image and exports agent-version metadata, but its shared fallback leaves distinct unlabeled builds indistinguishable.
examples/tutorials/00_sync/080_lineage/project/agent.py	Defines the tutorial agent and demonstrates all three lineage data-source reference registration forms.
examples/tutorials/00_sync/080_lineage/project/acp.py	Connects the OpenAI turn to the ACP harness and SGP tracing processor.
examples/tutorials/00_sync/080_lineage/tests/test_agent.py	Verifies static, argument-derived, absent-argument, and name-registered lineage reference resolution.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Build[Docker image build] --> Arg{AGENT_VERSION supplied?}
  Arg -->|Yes| Version[Image tag or Git SHA]
  Arg -->|No| Fallback[Shared unversioned fallback]
  Version --> Env[AGENT_VERSION environment]
  Fallback --> Env
  Env --> Processor[SGP tracing processor]
  Processor --> Spans[__agent_version__ on spans]

Loading

Prompt To Fix All With AI

### Issue 1
examples/tutorials/00_sync/080_lineage/Dockerfile:51-52
**Shared fallback obscures build identity**

When an image is built without `--build-arg AGENT_VERSION=<image-tag-or-sha>`, these lines assign the same `unversioned` value to every build. The normal build and deployment paths do not inject a version automatically, so traces from distinct commits remain indistinguishable by `__agent_version__`.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (2): Last reviewed commit: "docs(examples): honest unversioned fallb..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.