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..."