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

Confidence Score: 5/5

The PR appears safe to merge.

Summary

Adds a sync lineage tutorial that shows data-source references and agent versions on real traces. It uses the existing streaming harness so the metadata follows normal tool calls.

• Demonstrates static, argument-based, and name-registered source references.
• Stamps every span with a build version from AGENT_VERSION.
• Adds runnable packaging, documentation, and offline tests for the tutorial.

Diagram

sequenceDiagram
    actor User
    participant ACP as FastACP
    participant Agent as OpenAI Agent
    participant Tool as Tutorial tool
    participant Harness as UnifiedEmitter
    participant Trace as SGP tracing

    User->>ACP: Send company research message
    ACP->>Trace: Start message span
    ACP->>Agent: Run streamed turn
    Agent->>Tool: Call search_filings, read_kpi, company_profile
    Tool-->>Agent: Return canned result
    Agent-->>Harness: Stream text and tool events
    Harness->>Trace: Create tool spans with sgp.lineage.refs
    Trace->>Trace: Add AGENT_VERSION as __agent_version__
    Harness-->>ACP: Yield task message updates
    ACP-->>User: Stream response

Loading

_{Reviews (3) · Last reviewed commit: "Merge origin/next into mparke/lineage-ex..."}